Translations

README.md

Agama and Translations

The Agama installer is actually a Cockpit plugin. Because Cockpit already supports translations it would make sense to check it and reuse the translation process (or some parts) to avoid reinventing the wheel.

See the Cockpit i18n documentation for more details.

Note: This document only cover the translations in the web UI, it is not about the localization of the target installed system!

Workflow

This document summarizes the Cockpit translation workflow. It looks good and it should fit the Agama use case well.

Code

Using translations in the code is very similar to using the usual GNU gettext functions.

const _ = cockpit.gettext;
var translated = _("Time");

See more details in the Cockpit locale documentation.

Generating POT File

The translatable texts are extracted from the source code using the usual xgettext tool. See the Makefile.am file.

That task is executed daily in a weblate-sync-pot.yml GitHub Action.

The generated POT file is uploaded to a separate cockpit-weblate GitHub repository. This repository works as a buffer between the Cockpit sources and the Weblate translation system so the main repository is not flooded with translation commits and pull requests.

Translating

For the translation process itself the Cockpit uses Weblate running on their own Fedora Weblate instance.

That is basically same what YaST already uses in the openSUSE Weblate instance.

Updating PO Files

The translated PO files need to be integrated back to the Cockpit sources.

There is a weblate-sync-po.yml GitHub Action which is run once a week and it copies the PO files from the intermediate cockpit-weblate repository to the main cockpit repository.

The files with less than 50% translations are filtered out. See the po-refresh script.

Then it opens a pull request with the changes and the developers manually merge it. The advantage is that this automation does not disrupt the release process, merging the pull request can be postponed if needed.

You can check an example pull request.

Building JS Files

The PO files are translated to the JSON data file during build using an esbuild plugin cockpit-po-plugin.js.

That PO plugin also supports Webpack builds so it should be easy to reuse it in Agama.

Changing Language

For changing the current language Cockpit displays a popup dialog with list of languages. Each language is displayed in its own language.

After selecting a language it sets a cookie and the local storage data with the selected language and triggers a full page reload

Cockpit does not use the preferred language set in the browser, it always falls backs to English when not set yet (e.g. at the very first run).

Alternatives

Alternatively we could use another framework for displaying the translated texts. For example i18next allows changing the language without full page reload and there is also a plugin for detecting the language from the browser. There are plugins for converting the Gettext files so switching the framework should not be difficult.

Proposed Actions

Here is summary of implementation steps to have translations support in Agama similar to Cockpit:

• Mark all translatable texts with _(), n_(), ... (use a wrapper?)
• Create a separate agama-weblate GitHub repository
• Extract the translatable texts to POT file, upload it to agama-weblate repo automatically (daily?)
• Register the repository in the openSUSE Weblate instance so the texts can be translated
• Merge back the translations using pull requests (run weekly?)
• Implement the language switcher in the Agama web UI (use the Cockpit support or i18next?)

cockpit_lang_selector.png