============================
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 <https://en.wikipedia.org/wiki/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 <https://en.wikipedia.org/wiki/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 <https://poedit.net/>`_.


--------------------------------
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 <https://en.wikipedia.org/wiki/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 <https://poedit.net/>`_.


-------------------------
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:

.. code-block:: console

    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):

.. code-block:: console

    make gettext
    sphinx-intl update
    sphinx-intl build