mirror of
https://gitlab.com/Chill-Projet/chill-bundles.git
synced 2025-12-18 16:15:43 +00:00
140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
# 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.
|