chill-bundles/docs/source/development/translation_provider.md

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 centralises 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:

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
• Ensure Loco stays in sync with local YAML files
• Create any missing keys in Loco

Pulling Translations from Loco

When translators update strings in Loco, developers can fetch updates with:

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:

   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.