Versions Compared

Version Old Version 3 New Version Current
Changes made by

mirsch

Sam

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Image ModifiedImage Modified Image Modified

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.

Info

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


Note

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)

Warning

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 

Code Block
languagexml
linenumberstrue
{{ 'your_module.your_context.your_key' | trans }}

over

Code Block
languagexml
linenumberstrue
{% trans %}your_module.your_context.your_key{% endtrans %}

...


You have to specify the constants domain if you need to create keys dynamically e.g.
 Code Block
languagexml
linenumberstrue
{% 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.
 Code Block
languagephplinenumberstrue
$this->get('translator')->trans('your_module.your_context.your_key')
Extract strings from Source and Templates
We use JMSTranslationBundle to extract strings from source and templates.
...
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  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
 Code Block
languagebash
crowdin-cli --identity=.crowdin.yaml download
Upload translation source
cd to /var/www/html/htdocs and run
 Code Block
languagebash
crowdin-cli --identity=.crowdin.yaml upload sources

Import translations with Crowdin CLI V3
(warning) Not yet operational
Setup
  1. Get your personal access tokens from https://crowdin.com/settings
  2. 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"
  3. Install Crowdin CLI version 3: https://support.crowdin.com/cli-tool/
Import
  1. Run ./psh.phar docker:crowdin-import