multi-language management

Website globalization enables companies to significantly increase the return on their existing investment into infrastructure, content development, engineering and overall marketing activities. The main goal of successful website globalization is to provide access to the site's content and functionality to visitors in other target markets and in their own languages. Oberon can reduce the complexity of multi-language site management and let you focus on the content. It provides an internal translation dictionary able to manage all label translations, included the form multiple selection items (sub-keywords). Oberon manages an unlimited number of languages; keywords are organized into an unlimited number of sections to reduce the access time. Each keyword or sub-keyword may have the related translation for several languages. The access to the dictionary is guaranteed both inside the trigger/method source code and the JSP pages: this allows to overcome the limitations of i18n translation files which are accessible only inside the application server. Moreover you can export and import translations in XML format.

Adding languages and creating sections

In this lesson we will see how to apply language translations to the web-application labels. In the previous lesson we have created a new web application with a menu structure: each menu item (command) has a label, we want now translate these labels for the specific user language.

For this purpose, Oberon provides an internal dictionary with UTF-8 charset. First, you have to define which languages you want to manage: to define a new language it is sufficient to add a translation for a single label. You can add how many languages you want and this doesn't require to translate all label for each defined language. If a label hasn't the corresponding translation for the user language it will be shown without translation.
Moreover, the Oberon dictionary is subdivided into sections; this reduces the translation search space and increases the overall performances.
To define a new language select the Add Item(s) command from the Dictionary menu and insert the first translation for the new language. You can use maximum 3 chars for the language code, if you use more than 3 chars it will be truncated.

Repeat the steps for all languages you want to manage. It is also possible to add new language or new section every time you need it using this tool.

You can see the result of the operations by opening the dictionary with the "Edit Dictionary Items" button. Select the section where you where you are going to operate from the left-bottom list (it contains all previously defined sections): you should see a column for each defined language.

Adding / Editing / Removing translations

It is possible now to add new labels or delete one or more labels in the table or edit the language translations (only for those already defined) into the selected section.

After you have inserted a label translation for the first language, you can add the translations for the others by compiling corresponding the table cells (and finally saving the changes).

The Oberon internal dictionary has many usages, in particular you can translate:

- labels for application menus
- the field range values ( key = field name and subkey = range value )
- any application-form label
- names of action and decision workflow-steps
- platform error/notification messages
- everything you need to use inside the application by keyword substitution <[section_Name,keyword]>

In addition, you can use the dictionary to store simple tables; for example if you need the ZIP codes for some countries, you can create a new section called "ZIP Codes", use the key as the country code (USA,FR,UK...), the subkey as ZIP code and the translation (for a virtual language "XX") to keep the city names. The dictionary OOQL commands will help you to manage this table and to perform queries for information retrieval.

Setting up a multi-language web application

It is very important to set the dictionary parameters into the main application menu. In particular, when a menu is set as application menu, you can find the dictionary features "dictionary_menu_section" and "dictionary_common_section" . These parameters identify the dictionary sections where the application can find translations for the menu/command labels and for the common labels respectively.
The best practice is to create a dictionary section for each application-module, but there are labels that are common for all modules (like the words: view, user, navigate, class, object and so on) so the common translations should be collected in a common section. If you want to put menu and common translations into the same section, set both feature values with the same section name.

Another parameter to set is the "use_browser_language" option inside the web.xml file. If this is set to "true", the application retrieves the language from the http-request and uses this for the label translations.

When you define languages into Oberon you should consider to use the standard ISO 639 codes:

http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

The browser language codes are defined according to this standard:

If you decide to employ the ISO codes for the Oberon dictionary or the "use_browser_language" option is set to false, you don't need a mapping. Otherwise, you have to add the correspondence mapping between the Oberon dictionary languages and the browser languages inside the application main menu features:

Features "application_Languages" and "browser_Languages" contain the lists of the Oberon dictionary languages and the respective browser languages separated by comma. The language mapping must respect the order in both lists.

When the "use_browser_language" option is set to false, the application uses the default user Oberon language defined in the user form, so if you login with the user1 or with the user2 you can see the difference when they have a different default language.

Differently, if "use_browser_language" is true, you can change the application language only if you select another language from your web browser options.

NOTE: If a label is not yet translated into the Oberon dictionary you can see the translation as soon as you add it, but when you change the translation text you can't see the effect until you reset the dictionary cache. For this purpose you can call the "dictionary-reload.jsp" page from the web-browser (e.g. http://<HOST>:<PORT>/oberon_sample/dictionary-reload.jsp)

Exporting / importing dictionary translations

Translations can be exported from one Oberon database and imported into another. These operations can be performed by OOQL commands or directly with the Context Design client. From version 1.5 you can find in the "Dcitionary" menu the following commands:

- export: extracts translations into a local file
- import: loads some translations from a local file

Language: list of language patterns to be exported
Section: list of section patterns to be exported
Keyword: list of keyword patterns to be exported
SubKey: list of sub-keyword patterns to be exported
Value: list of translation patterns to be exported

You can use the usual "*" and "?" wildcards to indicate "any number of characters" and "a single character" respectively inside a pattern and the comma (,) character between patterns to define the pattern list.

File: is the name of a new or existing file to which to write the export data.
XML: if activated, exports the data in xml format
Append: if activated, appends the export data to an existing file.

Language: list of language patterns to be imported
Section: list of section patterns to be imported
Keyword: list of keyword patterns to be imported
SubKey: list of sub-keyword patterns to be imported

You can use the usual "*" and "?" wildcards to indicate "any number of characters" and "a single character" respectively inside a pattern and the comma (,) character between patterns to define the pattern list.

File: is the path and name of the existing file from which to import the translations.
XML: sets the import file type as XML