Added i18n.md documentation (initial content)

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.