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.

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

How does A-plus RST tools recognize a multilingual course?
Which of the following scenarios break the language content constraints?
Posting submission...