=======================================================================
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