¶ Babel
Babel includes a command-line interface for working with message catalogs, similar to the various GNU gettext tools commonly available on Linux/Unix systems.
¶ Weblate
Weblate is a centralized plateform for translations. A RERO project exists.
¶ Translations workflow
¶ Introduction
We're using weblate as a web service to help the translation process, through the hosted service of weblate: https://hosted.weblate.org/projects/rero_plus
For our needs, on Weblate, we have one project (named RERO+, with rero_plus as slug), with several components:
ng-core.rero-ils.rero-ils-public-search(from the projectrero-ils-ui).rero-ils-admin(from the projectrero-ils-ui).sonar.sonar-ui.
¶ The regular workflow
¶ From a developer point of view
With this workflow, developers only need to add translation markers in the source code's translatable strings, or, when necessary, add string in the manual translation file.
Testing the extraction to check the code is a good idea, though. But no files should be modified in the translation folders and subfolders (ie rero_ils/translations or projects/admin/src/assets/rero-ils-ui/admin/i18n).
¶ From the translation manager point of view
We do not use the automatic workflow through the GitHub webhook, to avoid conflicts.
¶ Push translations
Weblate 
Github (translations)
When translations have been updated on Weblate, we commit and push them to the Github translations branch. This is generally done before extracting new messages or right before a release but can be done at anytime during the sprint
- In the Weblate component, under
Manage,Repository Maintenance:Commitall changes andPush. - This creates a PR in the Github
translationsbranch.Rebase and mergethis PR.
¶ Prepare a release
Weblate 
Github (translations) Github (staging)
when all PRs from a Release-Candidate have been merged into staging, we need to extract the messages and push them to Weblate so that they can be translated.
- Ensure that all Weblate changes have been committed and merged to
upstream/translations(see push translations). - Lock the Weblate component so that no further changes are made.
- Switch to your local
translationsbranch and pull the changes fromupstream/translations. - Rebase this branch onto staging
git pull --rebase upstream staging. - On your local
translations, extract the messages and check that everything looks good.- Angular projects:
npm cito compile the project,npm run extract_messagesto extract the strings from the code to the master messages file. - Python projects:
poetry run python ./setup.py extract_messagesto extract the strings from the code to the master messages file.
- Angular projects:
- Update the catalog so that all langugage files are updated.
- Angular projects:
npm run update_catalog - Python projects:
poetry run python ./setup.py update_catalog
- Angular projects:
- Commit with message
translations: extract messages. - Push your local
translationsbranch to upstream withgit push upstream translations. - Unlock the Weblate component.
- Check on Weblate that the new strings have been added for translation.
- Inform the translation team that there are new translations available.
Weblate Github (translations) Github (staging)
When the translators have finished working on the release, we can push the changes from Weblate to translations, then to staging.
- Ensure that all Weblate changes have been committed and merged to
upstream/translations(see push translations). - Lock the Weblate component so that no further changes are made.
- Ensure that our local
stagingis up to date withupstream/staging. - Switch to your local
translationsbranch and pull the changes fromupstream/translations. - Rebase your
translationsbranch ontostaging:git rebase staging. - If there are multiple translation commits, sqash them into one with
git rebase -i HEAD~4(4 being the number of commits to sqash). See this section for details. - Switch to
stagingandgit rebase translations. - If everything went as expected, only your one translation commit has been added to the tree. Either push upstream (
git push upstream staging). If you want reviews, create a PR from thetranslationsbranch on thestagingbranch and merge it when validated. - Force-push your local
translationsbranch toupstream:translationsso thatstagingand translations are at the same commit. - In Weblate, use
Maintenance->Resetto force-sync Weblate and Github. - Unlock the Weblate component to allow translators to work.
¶ Commit sqashing
Weblate creates one commit per language when pushing changes. In order to limit the number of commits created by Weblate in the repositories, translation commits are sqashed into one before being pushed back to upstream/translations. To simplify this process, the commit message should look like the following template:
translations: translate vX.X.X
Translate-URL: https://hosted.weblate.org/projects/rero_plus/rero-ils/
# Adapt this link to the component
Co-Authored-by: Nicolas Prongué <n.prongue@outlook.com>
Co-Authored-by: Pascal Repond <pascal.repond@rero.ch>
# If needed, add all contributors that specifically participated to this particular commit (optional)
¶ Some weblate settings
- [component/settings/version control] Merge Style: rebase.
- [component/settings/version control] Age of changes to commit: 24 [hour].
- [rero_/#workflow] Source language: English (United States). This sets
en_USas the source language file, in order to avoid translating it. - [component/settings/files]: filter:
^(?!(en_US)$).+$(forng-core,public-search,admin). This is needed, as in our angular project, the source language file is the same as a translated language files. - [component/settings/files]: filter:
^(?!(messages)$).+$(forsonar-ui). The same as the precedent setting, but adapted to thesonar-uiconfiguration. - on each component, [addons]:
- automatic translations, suggest strings for non translated strings, use machine translations (deepl, weblate, weblate translation memory), with 80 thresold.
- squash git commits, per language, add contributors in the commit message, copy paste the regular commit message.
- only for JSON based component, customize JSON output, with 2 space for indentation.
¶ Troubleshooting
- If, for any reason, the github branch that has been define as a weblate corresponding branch (Composant settings, Version control, Repository branch), has been forced push, use the reset command either on the weblate web interface, or with the
wlcclient. - At leat once, changes couldn't be committed if the remote repository branch moved. Apparently weblate wait until the local branch is up to date with the remote branch before committing changes. Changes that aren't committed will be lost when the local branch is going to be updated. As a result, we may need a translation dedicated branch on the remote repository (github).
¶ Tips for the translators
- Have a look, even shortly to the [weblate documentation][https://docs.weblate.org]:
- Especially on [Translating using Weblate][https://docs.weblate.org/en/latest/user/translating.html].
- In each component, a language is the source code. It is in a darker green and has a specific icon: this language should not be translated, of course.
- On the language overview of each component, there are some links to strings grouped by status: translated, to be reviewed, needing actions, and so on. This is actually useful.
- In the same spirit, once a string is selected,
- on the right of the editor, you may have some information: on top a glossary, if any, and on the bottom links to the source code, if it can help to understand the context.
- below the left section, there are some tabs:
- nearby strings, which sometimes can help have a context,
- other occurences, which helps to be coherent,
- comment,
- machinery, which can provide automatic suggestions,
- other languages, to check how this string is translated in other
languages, - history.
