matrix-docker-ansible-deploy/i18n/README.md

Internationalization

Translated documentation files are published and maintained in translations/ directory.

Currently, we support translation of:

• Markdown files found at the top level project directory
• Markdown files found in the docs directory (this is where the bulk of the documentation is)
• this current document in the i18n directory

💡 For readers' sake, we only publish translations in a new language when the translation progresses beyond a certain threshold (requiring that at least the project README and core installation guides are translated).

Organization of this i18n directory is as follows:

• PUBLISHED_LANGUAGES: a list of languages that we publish translations for (in the translations/ directory)
• .gitignore: a list of files and directories to ignore in the i18n directory. We intentionaly ignore translated results (translations/<language> directories) for languages taht are still in progress. We only publish translations in a new language when the translation progresses beyond a certain threshold.
• justfile: a list of recipes for just command runner
• requirements.txt: a list of Python packages required to work with translations
• translation-templates/: a list of English translation templates - strings extracted from Markdown files
• locales/: localization files for languages
• translations/: translated documents for published languages (see PUBLISHED_LANGUAGES and publish translations in a new language)

Guide for translators

This project uses Sphinx to generate translated documents.

For details about using Sphinx for translation, refer this official document as well.

For now, translations are handled manually by editing .po files in the locales/<language> directory. In the future, we plan on integrating with Weblate to allow for translating from a web interface.

(Recommended) Using the uv package manager and just command runner

If you have the uv package manager and just command runner installed, you can use our justfile recipes to easily manage translation files and build translated documents.

The recipes will use uv to auto-create a Python virtual environment in the .venv directory and install the required Python packages (as per requirements.txt) to it.

Preparation

Make sure you have the uv package manager and just command runner installed.

Translation

Recommended flow when working on a new language (replace <language> with the language code, e.g. bg):

• Update the locale files for your language: just sync-for-language <language> (internally, this automatically runs just extract-translation-templates to make sure the translation templates are up-to-date)

• Use an editor to translate the files in the locales/<language> directory

• Build translated documents: just build-for-language <language>

• Preview the result in the translations/<language> directory

• Commit your changes done to the locales/<language> directory

• If you have progressed with the translation beyond a certain threshold, consider Publishing translations in a new language

Using any other package manager and manual scripts

If you cannot use uv and/or just, you can:

• manage Python packages in another way (pip, Poetry, etc.)
• manage translation strings and build translated documents manually by invoking scripts from the bin directory

Preparation

virtualenv and pip

• Create a Python virtual environment in the .venv directory: virtualenv .venv
• Activate the virtual environment: source .venv/bin/activate
• Install the required Python packages using pip: pip install -r requirements.txt

Translation

Recommended flow when working on a new language (replace <language> with the language code, e.g. bg):

• Ensure the English translation templates (translation-templates/) are extracted: ./bin/extract-translation-templates.sh

• Update the locale files for your language: ./bin/sync-translation-templates-to-locales.sh <language>

• Use an editor to translate the files in the locales/<language> directory

• Build translated documents: ./bin/build-translated-result.sh <language>

• Preview the result in the translations/<language> directory

• Commit your changes done to the locales/<language> directory

• If you have progressed with the translation beyond a certain threshold, consider Publishing translations in a new language

Publish translations in a new language

To publish prebuilt documents translated in a new language to the translations/<language> directory:

• add its language code to the PUBLISHED_LANGUAGES file
• whitelist its translations/<language> directory by adding a !translations/<language> rule to the .gitignore file

💡 Leave a trailing new line at the end of the PUBLISHED_LANGUAGES file.