Internationalization (I18n)

Introduction

CircuitVerse as an online learning platform aims at providing facilities and services for rich learning experience to our users in English as well as in their own native language.

Internationalization, also abbreviated as I18n, is a process of abstracting the strings out of application in form of keyed dictionaries (we use .yml file format) and having their translations in the desired language so that the platform can be represented in multiple languages.

Internationalization and localization of CircuitVerse primary and secondary platforms aims at creating a flexible I18n infrastructure in such a way that creating, editing, modifying, and managing translations in all the CircuitVerse platforms can be done in an easier way.

For more information about I18n in Rails refer to the official documentation describing Rails I18n API, Here.

Overview

Framework used

We use rails-i18n gem which is shipped with Ruby on Rails by default. It is an easy to use and extensible framework for translating Rails platform into multiple languages.

Framework API provides basic two functions along with rich set of attribute readers and writers for general use case of I18n in Rails -

• t() for translation of strings
• l() for localization of Date and Time objects

Translation Directory and file format used

All the translations are Placed in config/locale folder using YAML as a translation file format.

YAML are highly readable data serialization files providing data storage in the form of key-value pairs . They are also widely used as configuration files including storage of translation files in the Rails community.

Structure of YAML file, Locale specific YAML files and Nesting

We name the YAML file belonging to the particular language by the locale name of the language (en.yml, hi.yml). Locale names are standard acronyms defined for each language according to the ISO 639-1 standards.

For English language locale is en. Contributor can visit curated list of locale along with their language names, Here

• Creating locale specific YAML files -

  • Every file must start with locale as top level key/namespace
  • All the keys present inside the file shall be nested inside the top level locale key using one tab space.

  Example -

  config/locale/en.yml (Locale file holding translations for English language)

    en:
      key1: "string1"
      key2: "string2"
      .
      .
      .

  Top level namespace should be declared carefully, as using top level key, right YAML file is served by Rails I18n.

• Rails I18n support further nesting of keys

  • For managing translations in better way nesting of keys is an important concept to be used

  Example -

  config/locale/en.yml

  en:
    key1: "string1"
    key2: "string2"
    key3:
        key4: "string4"
        key5: "string5"

  key1 and key2 are present at toplevel namespace and key4, key5 are nested inside key3, all keys are nested in en: which is required.

General Usecase of translation function

Translations in YAML files are stored in form of key-value pairs as shown above, keys are passed into the translation function and it will match the key passed to the keys present in locale specific YAML file and will return the string.

Example -

# accessing top level key
t('key1')
# accessing nested key using dot operator
t('key3.key4')

Here the translation function will search for the respective key in a locale specific YAML file according to the current language set by the user and will return the string.

Rails initial Setup for I18n

Locale setup

Locale currently can be setup using two ways as follows -

• Using HTTP Language Header (locale value is set using browsers language)
• Taking locale value from user (through Form or using Language Switcher)

Support for Nested Directory Structure

Managing all locales just using top level directory structure is very inconvenient, as a solution Rails I18n allows us to use load_path to structure translation directory according to our needs.

config.I18n.load_path += Dir[Rails.root.join('config','locales', '**', '*.{rb,yml}')]

Configuring translation load path using appropriate wildcards leads in search for required files present at root of config/locale (eg. config/locale/en.yml).

If key to be searched not found in files present in config/locale at its root, then searching will jump into nested folders for finding required translation files and keys resulting in flexible translation directory structure (eg. config/locale/any_folder/any_yml_file).