Update translations

Translating messages

On UNCode, there are two places where messages need to be translated, this is the main repository, where the frontend is located, and the containers repository, there the submissions are assessed and the feedback is generated. In this guide you will see how to translate and update the messages in both repositories.

Introduction

UNCode already supports internationalization (i18n), that means that frontend messages can be translated in several languages. Currently we support 5 languages: Spanish (es), English (en), German (de), French (fr) and Portuguese (pt). However, not all messages and texts are translated for all languages as this must be done manually. To manage i18n, UNCode uses pybabel, and more exactly, the function gettext, to do the corresponding translations.

Four steps are necessary to translate a string or a message:

1. Mark strings as translatable.
2. Extract strings to create a .po file.
3. Translate the extracted strings (manually).
4. Compile the translated strings into a .mo file.

First off install python babel:

sudo apt-get install python-babel

Translate messages in the frontend

1. Mark strings as translatable

To help in this process, UNCode globally installs the function _() that can be used to mark strings as translatable, being available across all python and template files (html) in the frontend package (INGInious repository). Please mark all the strings that are displayed in the frontend.

Marking strings in python files

You do not need to import anything, you can just start using the function _(). In the next example, two strings are marked as translatable.

print(_("Hello"))
a = _("world")

Marking template files (HTML)

This function _() is also available in template files, due to the way these files are rendered and the capacity to use python code in these files. In the next example, a string is marked as translatable using the $: functionality before calling the function (this is exclusive of webpy).

<a id="trials-circle-tab" data-toggle="tab" href="#trials-circle">
    $:_("Trials and Best Grade")
</a>

2. Extract marked strings

The way i18n works in pybabel, is that a .po file is created for each available language on UNCode, with the corresponding extracted messages. These files are located in inginious/frontend/i18n/, where there is a specific folder for each language available.

Thus, to extract the messages, pybabel is used. To ease this process, we have created an script located in utils/pybabel. There you will find a python script called i18n.py. To extract and update the .po messages run the next command:

python3 utils/pybabel/i18n.py --actions extract --repo-path ./ #Set the correct repo-path

Where the --actions flag points out to extract and update the messages, and the --repo-path you have to set the path where the INGInious repository is located. After this, you should see the .po files for each language.

3. Translate the extracted strings

If you open one of those .po files, it will have the messages you have added to UNCode (check that you correctly marked the messages). All messages are paired with a msgid and msgstr, which indicates the id of the message and the translation for that message in the specific language. Then, you have to add the value for msgstr, this is done manually for all added/modified messages. In the next example, the translation of 'file upload' in Spanish is 'enviar archivo', thus, when a student sets their language in Spanish, they will see the translation, rather than the message in English.

#: inginious/frontend/task_problems.py:118
msgid "file upload"
msgstr "enviar archivo"

Save the file and go to the next step.

4. Compile translated strings

The final step is to compile your text-based .po file into a binary .mo file, which ensures that translation occurs smoothly. Run next command to update the binary files.

python3 utils/pybabel/i18n.py --actions compile --repo-path ./ #Set the correct repo-path

Notes

Make sure to do this every time a pull request is done in the main repository, just to make sure everything is up to date. In case you did not change/add any message, run next command to extract and compile the messages at the same time.

python3 utils/pybabel/i18n.py --actions all --repo-path ./ #Set the correct repo-path

Translate messages in the containers

Go to the INGInious-containers documentation to see how to translate the messages within the containers, which is basically the same as in the frontend.