mirror of
https://gitlab.com/Chill-Projet/chill-bundles.git
synced 2025-11-29 07:04:34 +00:00
149 lines
4.1 KiB
ReStructuredText
149 lines
4.1 KiB
ReStructuredText
=======================================================================
|
||
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
|