Translation Handling (Legacy)

We use crowdin for easy crowdsourced translation management of Opencaching.

If you are not a developer but want to help translate Opencaching just head over to https://crowdin.com/project/opencaching and start translating to your language.

Development Workflow and Info

We use the Translation component of the Symfony Framework to translate strings in the application. Have a look at the Symfony Book for more details. A short introduction follows below.

Against Symfony Best Practice we decided to use YAML instead of XLIFF for the following reasons:

lot easier to read and write
You have to use the text and not the key in the “source” tag of the xlf file, otherwise the translator will not see any hint (e.g. variables) what to translate except the key, which makes it impossible to translate. Symfony can handle this situation by using the key from the “resname” attribute of “trans-unit” tag, but the PHPStorm Symfony Plugin will not recognize this and marks the key as “missing translation”.
Crowdin shows the key as “Context” if you use YAML but it does not for XLIFF

Always use keys for translations instead of content strings. Use descriptive placeholders e.g. "Hello %name%" instead of "Hello %1".

Translations are stored in app/Resources/translations. messages.en.yml contains all automatically extracted strings from the application, constants.en.yml contains strings which can not be extracted from source or templates because they are generated dynamically. (See example below)

Do not manually edit other languages than *.en.yml and do not add them to the git repository. They are managed by crowdin an will be overwritten.

Translate Strings in Twig Templates

We prefer

{{ 'your_module.your_context.your_key' | trans }}

over

{% trans %}your_module.your_context.your_key{% endtrans %}

You have to specify the constants domain if you need to create keys dynamically e.g.

{% for fieldNote in fieldNotes %}
	...
	<td>{{ ('field_notes.log_type.' ~ fieldNote.type) | trans({}, 'constants') }}</td>
	...
{% endfor %}

and add your keys manually to constants.en.yml because they can not be extracted automatically and would be removed from messages.en.yml on the next extraction.

Translate Strings in PHP Code

Just use the translator service e.g.

Extract strings from Source and Templates

We use JMSTranslationBundle to extract strings from source and templates.

The bundle is configured in app/config/config.yml. To update messages.en.yml just login to your VM, cd to /var/www/html/htdocs and run

This will add new keys and remove unused ones form messages.en.yml.

After this you have to edit messages.en.yml and add the english text to the key (the bundle tags the new keys with # FIXME to find them easily)

Copy Translations to and from Crowdin

Preparation

Make sure you have a file .crowdin.yaml in the htdocs directory and it contains the api key of the project. See crowdin-cli documentation for details.

Download translations

cd to /var/www/html/htdocs and run

Upload translation source

cd to /var/www/html/htdocs and run

Import translations with Crowdin CLI V3

Not yet operational

Setup

Get your personal access tokens from https://crowdin.com/settings
Store your token to the environment variable CROWDIN_PERSONAL_TOKEN
Example for fish: set -Ux CROWDIN_PERSONAL_TOKEN your_token
Example for bash (in ~/.bashrc): export CROWDIN_PERSONAL_TOKEN="your_token"
Install Crowdin CLI version 3: https://support.crowdin.com/cli-tool/

Import

Run ./psh.phar docker:crowdin-import