TESTING AREA for teachers - real service at plus.tuni.fi
- TIE-99001
- 4. Module 1 - Introduction
- 4.6 Multilingual course (i18n)
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 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-toolsis a recent version that supports languagesMultilingual index has the
toctreeoption:caption: Select language**In
conf.pyvariablemaster_docis 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.