Interazionalization (i18n)

This guide focus on the translation process of the documentation and of the source code. The system and the conventions used by both documentation and source code internationalization are the one used by the GNU gettext system. In particular on the root of the repository is present a file called freeports.pot with the updated list of the strings present in the source code, and under docs/build/gettext the files with the templates of documentation translatable content. Translators will mostly work with .po files ready to be translated. In a second time this files are compiled in a machine readable format with exstension .mo. So the .mo files are the one the actively contain the translation, but they are generated from the .po files.

Translation of the code

You can find a folder into src/freeports_analysis/locales whit different language folders. The id is the ISO 639 code of the language. In the folder of the language that you want to translate there should be a directory called LC_MESSAGES and a file called messages.po. This file contains all the text strings present in the source code. You can translate the strings using a text editor or using a specific program to translate .po files like for example Poedit.

Translation of the documentation

You can find a folder into docs/source/locales whit different language folders. The id identifyng the lang is the ISO 639 code of the language. In the folder of the language that you want to translate there should be a directory called LC_MESSAGES and a some .po files. This files contain all the text strings present in the source code. You can translate the strings using a text editor or using a specific program to translate .po files like for example Poedit.

Building the translations

For updating the translations the deploy mechanism is similar in the case of source code and documentation and is caraterized by three steps:

  • generate the .pot file(s) using the source code or the modified documentation

  • updating the .po files using the new .pot file(s)

  • compile .po files in .mo files

In the case of the source code the command to launch are:

pybabel extract src/freeports_analysis/ -o freeports.pot
pybabel update -i freeports.pot -d src/freports_analysis/locales/
pybabel compile -d src/freports_analysis/locales/

In the case of the documentation are (from inside the docs/ directory):

make gettext
sphinx-intl update
sphinx-intl build