From 3c4a36b4dc6db2be2a77413ee8280d3fc937dbef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ladislav=20Slez=C3=A1k?= Date: Thu, 31 Aug 2023 16:26:30 +0200 Subject: [PATCH] Added i18n.md documentation (initial content) --- doc/i18n.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 doc/i18n.md diff --git a/doc/i18n.md b/doc/i18n.md new file mode 100644 index 000000000..2639e7b58 --- /dev/null +++ b/doc/i18n.md @@ -0,0 +1,128 @@ +# Internationalization (i18n) + +**Table of Contents** + +- [Internationalization (i18n)](#internationalization-i18n) + - [Translations](#translations) + - [The Workflow](#the-workflow) + - [Staging Translation Repository](#staging-translation-repository) + - [Synchronization](#synchronization) + - [Uploading Translatable Texts](#uploading-translatable-texts) + - [Downloading Updated Translations](#downloading-updated-translations) + - [Weblate Configuration](#weblate-configuration) + - [Plugins](#plugins) + +--- + +Internationalization (sometimes abbreviated as "i18n") is a process for +supporting different languages and locales in software. This documentation +describes how is that handled in Agama. + +Each Agama part (the web frontend, the D-Bus backend and the command line +interface) needs to solve this problem separately, see more details for each +part in the details below. + +## Translations + +For translation process Agama uses [Weblate](https://weblate.org/) tool running +at the [openSUSE](https://l10n.opensuse.org/) instance. + +## The Workflow + +The basic translation workflow looks like this: + +1. The translatable texts are marked for translation in the source code, usually + with the `_()` function or something similar +2. The translatable string are collected into a POT file which is uploaded to + the staging [agama-weblate](https://github.com/openSUSE/agama-weblate) GitHub + repository +3. The POT file is loaded by the Weblate into the + [agama](https://l10n.opensuse.org/projects/agama/) project +4. Translators then can translate the English texts into other languages +5. Weblate pushes back the translations in the PO files back to the + [agama-weblate](https://github.com/openSUSE/agama-weblate) repository +6. The translations in the PO files are regularly copied to the main repository + using pull requests +7. The PO files are processed during build so the translations can be used + later at runtime + +*Note: The Agama workflow is pretty similar to the [Cockpit localization]( +https://github.com/cockpit-project/cockpit/blob/main/doc/i18n.md) workflow, +we decided to use a similar approach here.* + +## Staging Translation Repository + +The special [agama-weblate](https://github.com/openSUSE/agama-weblate) +repository works like a buffer between the Agama sources and the Weblate tool. + +We do not want to spam the Weblate tool with every trivial change in the texts +and the other way round, we do not need to get dozen commits from the Weblate +every day with updated translations. This would be especially annoying +before releasing a new version where we might want to accept only unnecessary +changes to not break something at the very last minute. + +The agama-weblate repository uses webhooks to notify the Weblate instance +of any change. Changes in the repository should be visible in Weblate in matter +of seconds. + +## Synchronization + +The content between the main [agama](https://github.com/openSUSE/agama) and +the translation [agama-weblate](https://github.com/openSUSE/agama-weblate) +GitHub repositories is synchronized automatically using the GitHub Actions. + +### Uploading Translatable Texts + +Collecting and uploading the translatable texts is done by the +[weblate-update-pot.yml]( +https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-update-pot.yml) +GitHub action. + +- It checks out both `agama` and `agama-weblate` repositories +- It runs a script which extracts the translatable strings in the `agama` + repository into a POT file +- The POT file is copied to the `agama-weblate` repository and committed to + the GitHub repository + +This action is run daily, but it can be started manually if needed. +Go to the [weblate-update-pot.yml]( +https://github.com/openSUSE/agama/actions/workflows/weblate-update-pot.yml) +action detail and use the "Run workflow" option at the top of the page. + +The code compares the old POT file with the new one and if there is no change +besides the timestamps in the file it is not uploaded to `agama-weblate`. + +### Downloading Updated Translations + +The translations from the `agama-weblate` repository are merged back by the +[weblate-merge-po.yml]( +https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-merge-po.yml) +GitHub action. + +- It checks out both `agama` and `agama-weblate` repositories +- It copies the PO files from the `agama-weblate` to the `agama` repository +- It creates a pull request with the changes + +If there are no changes besides the timestamps in the PO files the pull request +is not created. + +## Weblate Configuration + +The [Agama Weblate](https://l10n.opensuse.org/projects/agama/) project defines a +separate translation component for each Agama part (the web frontend, the D-Bus +backend and the command line interface). + +For reading the translations it uses the [agama-weblate]( +https://github.com/openSUSE/agama-weblate) GitHub repository, but the browsing +the sources it uses the original [agama](https://github.com/openSUSE/agama) +repository. That means after clicking the source location link in the Weblate +you will see the correct source location in the other repository. + +### Plugins + +The Weblate components use the [msgmerge]( +https://docs.weblate.org/en/weblate-4.9.1/admin/addons.html#addon-weblate-gettext-msgmerge) +plugin which automatically updates all PO files to match the POT file. That +means after adding or updating any translatable text the changes are +automatically applied to all existing PO files and translators can translate +the new or updated texts immediately.