2_localization.md

Translation and localization (l10n) of Back In Time using Weblate

_{Feel free to open issues or contact the maintenance team on the mailing list if this text is difficult to understand or not helpful.}

Index

• Quick guide: Synchronize translations between Weblate and Microsoft GitHub
• Introducing the localization process
• Transfer translatable strings onto Weblate platform
• Transfer back translation from Weblate into Back In Time upstream repository
• Instructions for the translation process
• Setup Weblate project

That file does not describe how to use the GNU gettext utilities to localize software.

Quick guide: Synchronize translations between Weblate and Microsoft GitHub upstream repository

Warning

Do not follow this steps if you are new to this process! Please go to the next section and start reading from there.

The following steps are a quick reminder for maintainers of Back In Time. The goal is to synchronize the state of the ongoing translation at Weblate and the modified py-files in the upstream repository at Microsoft GitHub.

1. Press "Commit" in Weblate "Repository maintenance".
2. "Lock" the project in Weblate "Repository maintenance".
3. git: Start a new branch.
4. Download and integrate Weblate into the git repository via ./update_language_files.py weblate.
5. Check via git status or git diff. The po-files (not pot!) in common/po and the file common/languages.py should be modified.
6. Commit.
7. Scan py-files for modified source strings via ./update_language_files.py source.
8. Check via git status or git diff. The file messages.pot and all po-files should be modified.
9. Commit.
10. Optional: Check for redundant letters in "shortcut groups" via ./update_language_files.py shortcuts.
11. Create PR and merge into "dev".
12. Weblate "Repository maintenance":
    1. Go to "Danger zone" and click on "Reset and discard".
    2. "Unlock" the project.

Introducing the localization process in the Back In Time project

Some facts

• A translation platform (Weblate in this case) is not for developers but for the users. It's purpose is to make it easy as possible for contributors to translate strings without knowing technical details about code, Git or GNU gettext. The platform is not part of an automatic build pipeline and does not run the GNU gettext utilities for you.
• The Weblate instance on translate.codeberg.org do not support integration with external code hoster (state: May '23). This is not a restriction of Weblate itself but of Codeberg.org. The practical consequences are that it isn't possible to create pull request or to push directly (or automatically) from Weblate to Microsoft GitHub. This may change in the future.
• The GNU gettext system is used for localization. Strings in python files enclosed by _(...) are recognized as translatable.
• Despite Back In Time is separated into the two components common and qt the localization is not. All po and pot files are located in the folder common/po and used by the second component qt also.
• All actions should doable with the script update_language_files.py and there is no need to directly run one of the GNU gettext utilities. Some technical details are documented in the mentioned script.
• The current setup do not follow "modern recommendations" and may get optimized in the future.
• The "compilation" of po files into mo files is a separate step not described in this document. It is part of the install and build process.

Brief description of steps in the process

1. Scan all python files (in common and qt excluding test_*.py) for translatable strings and store them into the message template file common/po/message.pot.
2. Synchronize that message template file with the existing translations (common/po/*.po).
3. Commit and push the modifications into the development branch (e.g. dev).
4. The Weblate platform do pull that changes from our upstream repository into its own internal repository (manual triggered by maintainers or automatically).
5. Now the contributors can translate using our Weblate "Back In Time" project. There is also a translation landing page.
6. The translations on Weblate (as po files) need to be committed (manual or automatically) into the Weblate repository.
7. The po files with fresh translations are downloaded (via git clone) from the Weblate repository and copied into the BIT upstream repository.
8. Check the modifications in upstream and commit them into development or feature branch.

Step 1, 2, 7 and 8 are done via update_language_files.py which is a wrapper for GNU gettext utilities and Git tools.

Transfer translatable strings onto Weblate platform

Add or modify strings to translate. In this example the string Translate me please. is translatable because it is enclosed by _(...):

if __name__ = '__main__':
    print(_('Translate me please.'))
    startApp()

Run ./update_language_file.py with the argument source to scan get the new and modified strings into the message template file (common/po/messages.pot) and also update the language files (*.po).

$ ./update_language_files.py source
Updating PO template file "common/po/messages.pot" ...
  Execute "pygettext3 --verbose --output=common/po/messages.pot common/*.py qt/*.py"
Working on common/backintime.py
Working on common/password.py

...snipped...

Please check the result via "git diff".

Let's look into the modifications. The message template file include the new string now as a msgid.

diff --git a/common/po/messages.pot b/common/po/messages.pot
index 6b690204..e7bab701 100644
--- a/common/po/messages.pot
+++ b/common/po/messages.pot
@@ -15,6 +15,10 @@ msgstr ""
 "Generated-By: pygettext.py 1.5\n"


+#: common/backintime.py:1196
+msgid "Translate me please."
+msgstr ""
+
 #: common/config.py:95
 msgid "Disabled"
 msgstr ""

All language files are also update with that new string. Here the de.po file as an example:

diff --git a/common/po/de.po b/common/po/de.po
index 68dc7795..b6e07b50 100644
--- a/common/po/de.po
+++ b/common/po/de.po
@@ -19,6 +19,10 @@ msgstr ""
 "X-Generator: Weblate 4.17\n"
 "X-Launchpad-Export-Date: 2022-11-06 19:32+0000\n"

+#: common/backintime.py:1196
+msgid "Translate me please."
+msgstr ""
+
 #: common/config.py:95
 msgid "Disabled"
 msgstr "Deaktiviert"

In the end those changes need to arrive in the dev branch to get recognized by the Weblate translation platform. Create a Pull Request or commit/merge and push.

If the project at Weblate is correctly setup it does recognize the new commit automatically and update its internal git repository. See this in Manage / Repository maintenance section:

Looking into the list of languages there is one new (untranslated) string in German:

As an example the string get translated.

Go to the next section to see how to integrate the translation back to the upstream repository.

Transfer back translation from Weblate into Back In Time upstream repository

The starting situation is that some strings are translated by contributors on the Weblate platform. Go to Manage / Repository maintenance section. The counter for Pending changes not yet committed to the Weblate repository should be 1 or more. Click on Commit that counter goes back to 0 but now the Outgoing commits in the Weblate repository are increased. There is also a difference between the Last remote commit and Last commit in Weblate:

Go back to your local repository and run the known update_language_files.py script with weblate as argument:

./update_language_files.py weblate
Execute "git clone --no-checkout https://translate.codeberg.org/git/backintime/common /tmp/tmpbbv11b11".
Klone nach '/tmp/tmpbbv11b11' ...
remote: Enumerating objects: 353, done.
remote: Counting objects: 100% (353/353), done.
remote: Compressing objects: 100% (163/163), done.
remote: Total 353 (delta 177), reused 320 (delta 166), pack-reused 0
Empfange Objekte: 100% (353/353), 1.31 MiB | 5.41 MiB/s, fertig.
Löse Unterschiede auf: 100% (177/177), fertig.
Execute "git --git-dir /tmp/tmpbbv11b11/.git checkout dev -- common/po/*.po".
Please check the result via "git diff".

The script downloaded the po files with fresh translations directly from Weblate (via git clone) and copied them in the local repository. In result git diff shows that the German language file was updated with the translation:

diff --git a/common/po/de.po b/common/po/de.po
index b6e07b50..f2b73be4 100644
--- a/common/po/de.po
+++ b/common/po/de.po
@@ -7,7 +7,7 @@ msgstr ""
 "Project-Id-Version: Back In Time 0.9.5\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: 2023-05-04 16:31+0200\n"
-"PO-Revision-Date: 2023-05-02 21:26+0000\n"
+"PO-Revision-Date: 2023-05-04 14:59+0000\n"
 "Last-Translator: buhtz <c.buhtz@posteo.jp>\n"
 "Language-Team: German <https://translate.codeberg.org/projects/backintime/"
 "common/de/>\n"
@@ -21,7 +21,7 @@ msgstr ""

 #: common/backintime.py:1196
 msgid "Translate me please."
-msgstr ""
+msgstr "Übersetze mich bitte."

 #: common/config.py:95
 msgid "Disabled"

Just commit the changes to the repository.

Keep in mind: To make the translation appear in the running Back In Time the po files need be compiled to mo files. This is done in the build (packaging) and install process which is described elsewhere.

Instructions for the translation process

See Instructions about translation.

Setup Weblate project

The setup was done in 2023. This section is only for documentation of what was done at that time. For demonstration purpose in the screenshots the BIT upstream repository is not used but a fork of it.

First login into translate.codeberg.org which is the Weblate instance hosted by Codeberg.org. Use the plus sign in the top right corner to Add new translation project.

Insert the needed information's and press Save.

Weblate differentiate between Project and Component. One project can have several components. In the first place there is no Component. Press Add new translation component.

Insert the follow information's about the component.

Press Continue and wait until Weblate has scanned the repository. Weblate do recognize the structure of the repository and the location of the relevant files. Choose the second option with File mask common/po/*.po.

Modify nothing on the next screen. Just push Save and wait while Component is being updated....

Ignore the next page Community localization checklist and all the red signs on it. Everything is fine. Now looking into the Dashboard:

Clicking on the component the status of all languages is shown:

Finally a Webhook need to be setup. This enables Weblate to be automatically informed about new commits at the upstream repository. The Webhook need be installed, not on Weblate, but at the upstream repository Settings at Microsoft GitHub. Just use the Payload URL https://translate.codeberg.org/hook/gitea:

_{January 2024}