Translation workflow

Translation workflow for cgeo/WhereYouGo

Introduction

cgeo/WhereYouGo uses English as source language. Thus all new strings need to be implemented in English language (typically in /src/main/values/string*.xml). For localization into other languages we make use of Crowdin as a collaboration platform for contribution of translations. This integration provides the localized strings back into to the cgeo/WhereYouGo repository (typically to /src/main/res/values-<android_language_code>/string*.xml). Additionally arbitrary other files of the repository could optionally be included (such as changelogs, etc.) for localization. This is not in use at this moment.

This wiki article describes the workflow from/to Crowdin as well as the needed related actions on the cgeo/WhereYouGo repository on Github. The last chapter describes the technical setup of the integration between our Github repository and Crowdin for future reference.

Crowdin project details

Crowdin project homepage

The Crowdin translation project can be found here: https://crowdin.com/project/whereyougo

Contributors can create an account on Crowdin (free of charge) or authorize with their Github account to get access. Every crowdin member can contribute translations to WhereYouGo without further need of approval as WhereYouGo is listed as a public project on Crowdin (refer to role model explained below).

Role model on Crowdin

Role	Description	Assignment
Translator	Default role for all contributors. Translators can provide translations to all languages	Assigned to all Crowdin users by default. Single users could be blocked in case of abuse.
Proofreader	Proofreader have the permission to validate translations.	Need to be manually assigned by the Crowdin project owner. Can be assigned per language (preferred mode) or for all languages.
Owner	Owners have full control of the Crowdin project. They can administrate all settings, provide translations, set proofreadings for all languages.	Can be assigned/invited by other owners.

Important:

As only proofread translations will be contained in the sync workflow from Crowdin (project setting) this is the quality gate for incoming translations into the project. Therefore proofreaders should be carefully selected.

Sync Workflow

For all automated actions described below, Crowdin is configured to use the Github user cgeo-ci-bot.

New source files to Crowdin

New strings added into the files /src/main/values/strings.xml , /src/main/values/string_mapsforge.xml and /src/main/values/string_pref.xml will automatically be fetched by Crowdin on each commit to the master branch of the cgeo/WhereYouGo repository (a max. 10 minute delay might apply). After being fetched by Crowdin the source strings will be visible in the project and available for translation without need of any manual action.

The according configuration is stored in config.yml in the root directory of the master branch and can be changed in case of need to include more files and/or directories. Alternatively it is possible to use an GUI based configuration approach in the Crowdin project settings, which will then push a new config.yml to our repository.

New translations from Crowdin

Crowdin will push all new proofread translation to the branch l10n_master of the cgeo/WhereYouGo repository once every 24 hours (configurable in the Crowdin project settings). Individual commits will be created by Crowdin for each file and language changed. Additionally a pull request will be automatically created to merge l10n_master into master. Subsequent translations coming in at a later point of time will be added to l10n_master and therefore also added to the existing open pull request.

The pull request needs to be reviewed and merged manually by a member of the team. In order to minimize the amount of commits on our master branch, the pull request should be squashed during merge (Github UI function).

Important:

After merging the changes of l10n_master into master the l10n_master branch needs to be deleted, to allow Crowdin to recreate it on the next push event based on current state of master and base the commits against the most current state (including the already merged translations). The deletion of the l10n_master branch can be done easily during merge via the Github UI directly after merging the pull request (a delete button is shown).

How to setup Crowdin integration

This chapter provides a short description of how the integration between Github and Crowdin was configured for this project for future reference. Individual members/contributors do not need to establish such integration individually.

Prerequisites:

• Access to a suitable Github user which will later be used to read/write to the Github repository. Ideally this should be a dedicated account for such purposes. (here: cgeo-ci-bot)
• Access to a Crowdin account, which has owner privileges on the Crowin project (here: Lineflyer)

Actions on Github:

• In order to start the integration the Github user needs to have owner privileges on the repository. Crowdin will only allow setting up an integration for the repository owner. Therefore cgeo-ci-bot needs to be declared as member of the c:geo organization temporarily until the setup is completed.
• An access token for the user cgeo-ci-bit has to be generated in the Github user settings. This will be used on Crowdin to establish the communication link.

Actions on Crowdin:

• The integration can be set up in Project Settings - Integrations on Crowdin. Select the option to use an access token and provide the user access token derived for cgeo-ci-bot.
• Choose the cgeo/WhereYouGo repository and select the branch master for integration
• Configure source file patterns (the details can be found in file crowdin.yml which is created based on this input)
• Configure ignore patterns (the details can be found in file crowdin.yml which is created based on this input)
• Configure destination file patterns (the details can be found in file crowdin.yml which is created based on this input) using the %two-letters-code% placeholder to separate the languages onto the directories and the placeholder %original-file-name%. Remark: For support of certain language codes and dialects (e.g. Portuguese and Brazilian) a language mapping needs to be configured on Crowdin during this step to map the %two-letters-code% of a specific language to a custom code as expected by Github/Android.
• Configure XML settings to translate content, but not translate attributes and not use content segmentation.
• Define the desired push period under advanced settings
• Save and finalize the configuration
• Crowdin will automatically commit the needed config.yml to the repository and start synchronizing

Final steps:

• Check that l10n_master branch, the commits and the pull request are created as soon as there are new (proofread) translations on Crowdin
• After the integration setup has been completed cgeo-ci-bot has to be again converted to an outside collaborator to remove the admin privileges on Github.