Multilingual course (i18n)¶

Main questions:: How to create a course that is available in multiple human languages?
Topics?: RST, A-plus RST tools
Difficulty:: You need to first master course creation in one language. Technically, there are no additional difficulties in multiple languages.

This chapter describes the document structure and compilation for including course material in multiple human languages (implementing exercises in multiple programming languages is a different challenge). This approach is recommended for courses that aim to use identical study units and grading in all language versions.

Structure¶

The different language versions reside in a single git repository as adjacent RST trees. Each language has its own RST index that works the same as in a single language course. It lists the course modules for one language in a toctree-directive. In a multilingual course, there is an additional multilingual super index that lists the languages of the course. A multilingual RST index may look like this:

Ignored course title
====================

.. toctree::
  :maxdepth: 1
  :caption: Select language

  Finnish <index_fi>
  English <index_en>

The above index includes a title, maximum tree depth, and link names so that it compiles into sensible HTML for non A-plus use. However, the only A-plus requirements are that the index includes a toctree that has the option :caption: Select language.

The links are to the the different RST language indexes that must include the course title and the toctree of the course modules in that language. Furthermore, the RST file names must have a language postfix (such as _en). The first language is considered the default language of the course. The default language is selected if an A-plus student has not selected another supported language as her or his preference.

Content constraints

Each language must have an identical number of modules, identical number of chapters in each module, and exercises in each chapter that have identical keys. Furthermore the visibility, point, and group configuration must be identical to default language or omitted completely to use implicit defaults.

In other words, each language must have the same content entries that provide the same course points. If the internationalization design breaks these constraints then A-plus project recommends to create separate course instances for the different internationalizations.

Compilation¶

The A+ RST tools detects a multilingual course and compiles it accordingly. Near the end of the RST compilation the tools should log similarly to:

Detected language tree.
Traverse document elements to write configuration index (fi).
Traverse document elements to write configuration index (en).
Joining language tree to one index.

Git submodule

To check the current submodule version change into the submodule directory, e.g. cd a-plus-rst-tools and see git status. The latest version of the submodule is generally available via git checkout master && git pull. To save the currently checked out submodule version return to the parent repository and stage the change, e.g. cd .. && git add a-plus-rst-tools. Then create a commit and push it to the remote repository.

If the previous log lines for your languages do not appear, check the following:

Course submodule a-plus-rst-tools is a recent version that supports languages
Multilingual index has the toctree option :caption: Select language**
In conf.py variable master_doc is set to your multilingual index RST file

While joining languages the compilation halts in an error if any previously mentioned course constraints are broken. In the development stage it can be useful to include conf.py variable skip_language_inconsistencies = True. That flag enables compilation of broken constraints. Warnings are generated that help to fix any inconsistencies and the compiled course represents default language where problems exist.

Recap¶

Question 1

How does A-plus RST tools recognize a multilingual course?

Course includes multiple RST indexes

Course includes RST file postfixes, e.g. document_en.rst

Course includes RST index with :caption: Select language

Question 2

Which of the following scenarios break the language content constraints?

Course has 3 modules in English and 2 in Spanish.

Course skips one text only chapter in English that exists in the default Finnish variation.

Course defines 3 points exercise in English and 4 point exercise in Chinese in the corresponding chapter using the same exercise key.

Course defines 3 points exercise in default language English and does not configure points for the corresponding exercise in Chinese.

Course supports larger groups in the default language exercises than in Finnish that has presumably less students.