Internationalization

Internationalization (I18N) refers to the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.

For web applications, this is of particular importance because the potential users may be from around the world.

Gentics Portal.Node PHP uses YII i18n system but slightly changed for specific purposes

Yii provides support for I18N in several aspects:

In the following subsections, we will explain each of the above aspects.

1 Locale and Language

Locale is a set of parameters that defines the user’s language, country and any special variant preferences that the user wants to see in the user interface.

It is usually identified by an ID consisting of a language ID and a region ID.

For example, the ID en_US stands for the locale of English and United States.

For consistency, all locale IDs in Yii are canonicalized to the format of LanguageID or LanguageID_RegionID in lower case (e.g. en, en_us).

For a Yii application (as the portal is), we differentiate its target language from source language. The target language is the language (locale) of the user that the application is targeted at, while the source language refers to the language (locale) that the application source files are written in. Internationalization occurs only when the two languages are different.

Note: It’s better to leave English as a source language since it will be easier to find people translating from English to any other language.

2 Translation

The most needed I18N feature is perhaps translation, including message translation and view translation. The former translates a text message to the desired language, while the latter translates a whole file to the desired language.

A translation request consists of the object to be translated, the source language that the object is in, and the target language that the object needs to be translated to. In Yii, the source language is default to the application source language while the target language is default to the application language. If the source and target languages are the same, translation will not occur.

2.1 Message translation

Message translation is done by calling Yii::t(). The method translates the given message from source language to target language.

Translated messages are stored in a repository called message source.

In Gentics Portal.Node PHP all message sources are represented by *.php files.

Every module in common folder has its own translation files in folder messages. For each locale there is sub folder.

Clients can easily overwrite core message sources by coping them into custom folder.

For example:

To overwrite common/modules/comments/messages/de/core.php

copy it to

custom/modules/comments/messages/de/core.php

2.2 File Translation

File translation is mainly used when rendering a view. When calling one of the render methods in a controller or widget, the view files will be translated automatically.

For example, if the target language is zh_cn while the source language is en_us, rendering a view named edit would resulting in searching for the view file ModuleId/views/ControllerID/zh_cn/edit.php.

If the file is found, this translated version will be used for rendering; otherwise, the file ModuleId/views/ControllerID/edit.php will be rendered instead.

File translation may also be used for other purposes, for example, displaying a translated image or loading a locale-dependent data file.

3 How to overwrite translations

To change module string translation but not change modules functionality:

  1. Create the module dictionary folder hierarchy in /custom folder. For example: /custom/modules/comments/messages/
  2. Create dictionary file which you want substitute
  3. In configuration set:

'messages' => array(
    'customI18n' => true,
),