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)
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.
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.
Make sure you have the uv package manager and just command runner installed.
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 runsjust 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
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
- 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
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
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.