Add documentation on use of translation provider Loco

2025-12-02 00:18:29 +00:00 · 2025-11-28 12:41:59 +01:00
parent 009846853b
commit 45d7d1614a
1 changed files with 148 additions and 0 deletions
--- a/docs/source/development/translation_provider.rst
+++ b/docs/source/development/translation_provider.rst
@@ -0,0 +1,148 @@
+=======================================================================
+Managing translations within CHILL using Loco as a translation provider
+=======================================================================
+
+Within CHILL we make use of Symfony's translation component together with *Loco* as an external
+translation provider. Using this setup centralise translations in a single online
+location (Loco), while still allowing developers to create and update
+translation keys locally in the project (YAML files).
+
+Workflow
+========
+
+We use the following workflow:
+
+* Developers create translation keys in YAML files inside each bundle.
+* Keys are written in **English**.
+* Application UI defaults to **French**, with **Dutch** as an additional locale (other languages can be added in the future).
+* Loco acts as the central translation memory and synchronisation source.
+* Loco Symfony package was installed so that built-in translation commands can be used to push/pull content
+  between Loco and the local project.
+
+
+Translation directory structure
+===============================
+
+Each bundle contains its own ``translations`` directory, for example::
+
+    chill-bundles/
+        ChillCoreBundle/
+            translations/
+                messages.fr.yml
+                messages.nl.yml
+        ChillPersonBundle/
+            translations/
+                messages.fr.yml
+                messages.nl.yml
+        ...
+
+Configuration
+=============
+
+The translation configuration is defined in
+``config/packages/translation.yaml``::
+
+    framework:
+        default_locale: '%env(resolve:LOCALE)%'
+        translator:
+            default_path: '%kernel.project_dir%/translations'
+            fallbacks:
+                - '%env(resolve:LOCALE)%'
+                - 'en'
+            providers:
+                loco:
+                    dsn: '%env(LOCO_DSN)%'
+                    domains: [ 'messages' ]
+                    locales: [ 'fr', 'nl' ]
+
+Note:
+
+* ``en`` is the **source locale** in Loco.
+* ``fr`` and ``nl`` are the **application locales**.
+* ``domains: [messages]`` means only ``messages.*.yml`` files are pushed.
+
+
+Environment variables
+---------------------
+
+In ``.env``::
+
+    LOCALE=fr
+
+In ``.env.local``::
+
+    LOCO_DSN="loco://API_KEY@default"
+
+Replace ``API_KEY`` with the key provided by Loco.
+
+
+Working with Loco
+=================
+
+Loco shows all translation keys under three languages:
+
+* **English (source)** — keys are listed but remain “untranslated”
+* **French** — translated strings for French users
+* **Dutch** — translated strings for Dutch users
+
+Note: Don't add translations directly in the English column.
+This column simply represents the *key*.
+
+
+Pushing translations to Loco
+============================
+
+You can push local translations to Loco using:
+
+.. code-block:: bash
+
+    symfony console translation:push loco --locales=fr --locales=nl --force
+
+This will:
+
+* Upload all French and Dutch translation values from ``*.fr.yml`` and
+  ``*.nl.yml`` files
+* Ensures Loco stays in sync with local YAML files
+* Creates any missing keys in Loco
+
+
+Pulling translations from Loco
+==============================
+
+When translators update strings in Loco, developers can fetch updates with:
+
+.. code-block:: bash
+
+    symfony console translation:pull loco --locales=fr --locales=nl --force
+
+This will:
+
+* Download the latest French and Dutch translations
+* Overwrite the local YAML files with Loco’s content
+* Keep everything consistent across the team
+
+
+Adding new translation keys (Developer workflow)
+================================================
+
+1. Add a new key directly in the appropriate YAML file, for example::
+
+       chill-bundles/ChillPersonBundle/translations/messages.fr.yml
+
+   Example key::
+
+       person.form.submit: "Envoyer"
+
+2. Add Dutch translation as well if you can (otherwise leave empty to be translated within Loco later)::
+
+       person.form.submit: "Verzenden"
+
+3. Run a push to send the new key to Loco:
+
+.. code-block:: bash
+
+    symfony console translation:push loco --locales=fr --locales=nl --force
+
+4. The key will now appear in Loco for translation management.
+
+Note: English appears as “untranslated”, because it is merely the source language