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.
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
:caption: Select language
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.
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.
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.
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.
git checkout master && git pull
cd .. && git add a-plus-rst-tools
If the previous log lines for your languages do not appear, check the following:
:caption: Select language**
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.
skip_language_inconsistencies = True
:caption: Select language