Course Localization

Localization and internationalization (i18n) are one of the strongest tools in order to achieve Course’s availability.

Usage

Localize configuration

Let’s take a look at course’s configuration file. If you are not familiar with it’s syntax, you can check related documentation page.

Tip

Starter template for building your own localized course can be found in separate i18n-example-course repository.

The most current implementation of localization in it4kt-builder adds another root-level key in course configuration:

course:
  title: Course name
  acronym: CN

translations:
  languages: [sk, en, ru]
  fallback: sk

This root-level key supports two nested keys:

languages - A list of all available languages. In order to use some language it has to be supported by it4kt-builder itself.

Note

Currently, we fully support Slovak and English languages. However, Russian support is in progress.

First language from list acts like a default language for course building process during every conversion run.
fallback - Nullable field, which if set, acts like a fallback whenever target language file translation couldn’t be found.

Tip

If you would like to translate your course into other languages, that weren’t mentioned, I strongly encourage you to contribute to this project.

There are also some other strings in configuration file, which needs to be translated, right? In current version of i18n in it4kt-builder, an user has the ability to translate values for following keys: title, acronym, url. And how it’s done? Easily!

course:
  title:
    sk: Názov kurzu
    en: Course Name
    ru: Название предмета
  acronym:
    sk: NK
    en: CN
    ru: CN

translations:
  languages: [sk, en, ru]
  fallback: sk

folders:
  - path: lectures
    title:
      sk: Prednášky
      en: Lectures
      ru: Лекции
  - path: labs
    title:
      sk: Cvičenia
      en: Labs
      ru: Упражнения
    type: scenario
  - path: assignments
    title:
      sk: Zadania
      en: Assignments
      ru: Задания

links:
  - title: Moodle
    url:
      sk: https://moodle.fei.tuke.sk
      en: https://moodle.fei.tuke.sk/en
      ru: https://moodle.fei.tuke.sk/ru

As you can see I’ve forgot to replace Moodle’s link title. I’ve made it on purpose to show you that you don’t have to translate string from configuration, if it doesn’t need to be translated. In this case a link with “Moodle” title is going to be created for every language.

Localize content

We’ve decided to use language suffix for language processing. For example, your index.md is going to be index.en.md for english translation. You can also provide translation suffixes for static files like images, videos, etc.

How it works?

From i18n architectural decision: During file localization, the file translation flow can be simply described using following priority order:

Search for file with suffix of currently parsed language (with en language set we are searching for index.en.md).
Search for fallback language file if set (with sk fallback language we are searching for index.sk.md).
Search for default language file (searching for file without any suffix e.g. index.md).
If no file has been matched until now, skip file.

Note

Basically, I wasn’t able to find any edge case, where these rules are not sufficient enough. Even when it seems like you cannot find the right combination, you can still take advantage of renaming that specific file while providing a target language postfix only and you will get an unique file for target language.

These rules means that user has the ability to exclude files from conversion completely or force fallback file to take a place in conversion instead. We’ve also decided that every file in conversion process is able to be translated including images, in-app video and audio.

Contribution Guide

The language contribution should be easy process, which consists of providing a translations for strings, that are used across it4kt-builder. Generally, there are a few translation files and tokens, which need to be edited.

it4kt-builder:
  - it4kt -
    - translations.yml
    - themes
      - anyTheme
        - translations.yml

On the upper directory structure tree view you can see basic translations files in it4kt-builder. Each of them should contain strings like:

sk:
  courseOverview: Prehľad predmetu
  courseObjectivesOverview: Zoznam všetkých cieľov
  objectivesOverviewTitle: Prehlad cieľov predmetu
  ...
en:
  courseOverview: Course Overview
  courseObjectivesOverview: Course objectives list
  objectivesOverviewTitle: Overview of subject objectives
  ...
ru:
  courseOverview: Беглый взгляд на курс
  courseObjectivesOverview: Список целей курса
  objectivesOverviewTitle: Обзор предметных целей
  ...

The point here is to define your new language key and then add translation for every single key-value pair. So if you’re about to add a Czech translation, then translations file should looks like on the following example:

sk:
  courseOverview: Prehľad predmetu
  courseObjectivesOverview: Zoznam všetkých cieľov
  objectivesOverviewTitle: Prehlad cieľov predmetu
  ...
en:
  courseOverview: Course Overview
  courseObjectivesOverview: Course objectives list
  objectivesOverviewTitle: Overview of subject objectives
  ...
ru:
  courseOverview: Беглый взгляд на курс
  courseObjectivesOverview: Список целей курса
  objectivesOverviewTitle: Обзор предметных целей
  ...
cz:
  courseOverview: Přehled předmětu
  courseObjectivesOverview: Seznam všech cílů
  objectivesOverviewTitle: Přehled cílů předmětu

When you’re finished with translations string, then there is a last step in order to completize a new translation. It is required to add a new keywords for each of existing elements in XML format and Kpimark.

To add these keyword you will need to take a look at:

For XML, look for translation strings in it4kt-builder/it4kt/xsl/localization.xsl folder.
For Kpimark, all tokens are located in it4kt-builder/it4kt/kpimark/tokens.

Look for keywords and add your language translation carefully there. Once it’s finish you should test your fork of it4kt-builder project and then you can submit new Merge Request.