Fraggle: Erstentwurf

2024-05-06T18:24:16Z

Erstentwurf

Neue Seite

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 [https://symfony.com/doc/current/best_practices/i18n.html#translation-source-file-format|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

! Important to note: Always use [https://symfony.com/doc/current/best_practices/i18n.html#translation-keys|keys for translations] instead of content strings. Use descriptive placeholders e.g. "Hello %name%" instead of "Hello %1".

Translations are stored in <code>app/Resources/translations.messages.en.yml</code> contains all automatically extracted strings from the application, <code>constants.en.yml</code> 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
<nowiki>{{ 'your_module.your_context.your_key' | trans }}</nowiki>
over
{% trans %}your_module.your_context.your_key{% endtrans %}

You have to specify the <code>constants</code> domain if you need to create keys dynamically e.g.
<nowiki>{% for fieldNote in fieldNotes %}
...
<td>{{ ('field_notes.log_type.' ~ fieldNote.type) | trans({}, 'constants') }}</td>
...
{% endfor %}</nowiki>

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

=== Translate Strings in PHP Code ===
Just use the translator service e.g.
$this->get('translator')->trans('your_module.your_context.your_key')

=== Extract strings from Source and Templates ===
We use [https://github.com/schmittjoh/JMSTranslationBundle| JMSTranslationBundle] to extract strings from source and templates.

The bundle is configured in <code>app/config/config.yml</code>. To update <code>messages.en.yml</code> just login to your VM, <code>cd</code> to <code>/var/www/html/htdocs</code> and run
bin/console translation:extract en --config=app

This will add new keys and remove unused ones from <code>messages.en.yml</code>.

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

=== Copy Translations to and from Crowdin ===
==== Preparation ====
Make sure you have a file <code>.crowdin.yaml</code> in the <code>htdocs</code> directory and it contains the api key of the project. See [https://github.com/crowdin/crowdin-cli#split-project-configuration-and-user-credentials|crowdin-cli documentation] for details.

==== Download translations ====
<code>cd</code> to <code>/var/www/html/htdocs</code> and run
crowdin-cli --identity=.crowdin.yaml download

==== Upload translation source ====
<code>cd</code> to <code>/var/www/html/htdocs</code> and run
crowdin-cli --identity=.crowdin.yaml upload sources

== Import translations with Crowdin CLI V3 ==
! This function is not yet operable

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

=== Import ===
* Run <code>./psh.phar docker:crowdin-import</code>

[[Kategorie:Entwicklung]]
[[Kategorie:English pages]]

Translation Handling (Legacy) - Versionsgeschichte

Fraggle: Erstentwurf