# 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`:

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

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

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

   ```yaml
   person.form.submit: "Envoyer"
   ```

2. Add Dutch translation as well if you can (otherwise leave empty to be translated within Loco later):

   ```yaml
   person.form.submit: "Verzenden"
   ```

3. Run a push to send the new key to Loco:

   ```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.