Godot translation sync workflow

l10n-sync.md

Godot translations are managed on Weblate as 4 different components with 2 source repositories:

• https://github.com/godotengine/godot-editor-l10n
  • Editor: https://hosted.weblate.org/projects/godot-engine/godot/
  • Properties: https://hosted.weblate.org/projects/godot-engine/godot-properties/
  • Class Reference: https://hosted.weblate.org/projects/godot-engine/godot-class-reference/
• https://github.com/godotengine/godot-docs-l10n
  • Documentation: https://hosted.weblate.org/projects/godot-engine/godot-docs/

Editor / Properties / Class Reference

The source repository for these is https://github.com/godotengine/godot-editor-l10n. It serves as an intermediate place to keep all translations done via Weblate. After syncing updated strings from Weblate and new strings from Godot, we run make export to copy only the PO files with a high enough completion ratio to the main Godot repo. This export process also strips fuzzy strings or comments to keep the file size minimal.

Update process

The steps on Weblate need to be done by someone with admin permissions. The steps on godot-editor-l10n need to be done by the same person, who should have write permission on that repo and on godotengine/godot.

The goal is to retrieve the latest translations from Weblate, commit them in godot-editor-l10n, update POT files with latest Godot changes, export translations to Godot, and commit all this again. Then the Weblate git repository is hard reset on godot-editor-l10n to get the new strings and cleaned up history. Weblate uses an intermediate repository where translators work is committed directly, and to reduce churn we do this manual update process every once in a while.

Important

The reset on Weblate is a destructive operation, so make sure to follow the steps below thoroughly so all newly translated strings since the last sync are properly committed in godot-editor-l10n.

• Clone the Weblate git repository used for these components locally: https://hosted.weblate.org/git/godot-engine/godot-properties/
  • It's named godot-properties for historical reasons, but includes all 3 components. Name your local clone weblate-editor-l10n.
• Clone the main repository where we sync the translations manually: https://github.com/godotengine/godot-editor-l10n
  • Initialize the godot submodule with git submodule update --init.
• Go to the #repository tab on each of the 3 Weblate components (Editor, Properties, Class Reference.
• Press "Commit" on either of them to commit pending changes (it commits for all 3 components which share the same repository).
• Press "Lock" on all 3 components to prevent translators for pushing more changes while you're doing a sync.
• Pull the newly committed translations in your local weblate-editor-l10n clone.
• Copy Weblate translations to godot-editor-l10n. Assuming both clones are next to each other, go to godot-editor-l10n and do:

for component in classes editor extractable properties; do
  cp ../weblate-editor-l10n/$component/*.po $component/
done

• Check the git diff to make sure it looks as expected. In general, remember to check git diff after each stage as any mishap in these sync steps can lead to losing translators work.
• Check git status to see if new languages were added. If yes, check on Weblate that they include any translations. Sometimes users will just add the language on Weblate if it's missing, without actually being motivated enough to do the work. 0% complete translations that churn every time we update the POT files are just making the Git repo bigger for no reason. Sometimes, people also add regional language variants which may or may not be warranted, e.g. fr_FR vs fr - French doesn't have big enough regional variants to warrant making region-specific branches for hundreds of thousands of strings (at least not restarting from 0%). So you can simply delete the new PO files in that case instead of committing them. Check on #translation if in doubt.
• Commit changes with the message: Sync translations with Weblate.
• Update the godot submodule to the latest commit.
  • During early stages of development for the next feature branch, we keep the godot submodule on the latest stable branch, so we can provide updated translations in maintenance releases.
  • Around beta time, we switch back to master to add all the new and updated strings that translators should work on for the next feature release.
• Update all POT files for translation components with:

for component in classes editor extractable properties; do
  make -C $component update
done

• Merge the POT files update into their respective PO files with:

for component in classes editor extractable properties; do
  make -C $component merge
done

• Once it's done, export all updated translations to the godot submodule:

for component in classes editor extractable properties; do
  make -C $component export
done

• Optional: At this stage, it can be good to validate that the class reference translations aren't malformed and can be converted by doc/tools/make_rst.py. See below for details.
• In the godot submodule, commit the modified translations as Sync translations with Weblate. Push this commit directly upstream.
• In godot-editor-l10n, stage and commit everything as Merge and export translations for \<version\> branch.
• Push commits.
• On Weblate, on one of the 3 components, hit "Reset and discard".
  • This is a slow process, you can check the update progress on https://hosted.weblate.org/progress/godot-engine/godot-properties/?info=1
  • Once the update is done, unlock all 3 components, and notify that a sync was done on #translation

Validating class reference translations for make_rst.py

Translators often make mistakes in the class reference translations around BBCode markup, e.g. translating things like [constant ...] or [ClassName]. This can be validated before pushing the changes upstream by running make_rst.py, but it's a bit convoluted. Here is the process:

• After running make export to have the updated PO files in the godot submodule of godot-editor-l10n, build the engine from source in that submodule.
• Clone https://github.com/godotengine/godot-docs-l10n alongside godot-editor-l10n.
  • This is where we include the RST versions of the class reference for a selection of languages, as well as the Weblate translations for the docs (see update process below).
• From the godot submodule of godot-editor-l10n with a compiled binary, run ../../godot-docs-l10n/classref_export.sh.
• Check the output of that script if make_rst.py reports errors for any of the languages. ru and uk are known to have a lot of errors currently, but others can be kept error free.
• Either report the errors to translators on #translation, or fix them yourself in the main .po files in godot-editor-l10n, and re-run make update and make export. You can then re-run the above steps (including compiling Godot to get fixed translations) until it's error free.
• If you decide to fix them yourself, make sure to do all this work before pushing upstream and resetting the Weblate repo.

Documentation

TODO.