The application uses jsgettext from BerliOS for internationalization that allows translations in the view using .po files. The .po files must be compiled into .js at development time using a jsgettext script.

Preparing the environment

First of all, we need to install PoEdit to perform the translations, and perl to compile the .po files:

#!bash

sudo apt-get install perl liblocale-po-perl poedit

How to update the translations

To update the translations we use the PoEdit application. The first thing to do is go to "File > Catalog Manager > New". Add a name to the project like "GoraExplorer" and Browse the folder src/main/webapp/resources/i18n.

It should show something like:

The existing languages are already configured, but when a new language is created, it is necessary to configure the keywords to detect texts to translate. On the language translation window at "Catalog > Properties > Original keywords" must be configured as:

#!

_:1
_:1c,2
_n:1,2
_n:1,2,4c
_x:1c,2

Once the translations are done, it is needed to execute the script src/main/webapp/resources/i18n/generate_js.sh to compile the .po files into .js.

ExtJS integration

ExtJS has an own localization system that relies on texts overrides. It has some files that can be configured in a static way (and from URL parameter) that translates some validation messages, and configures the numeric and dates format. However, it lacks an internationalization system that allows word inflections, translations from counters, contexts for translation or a default language fallback when there is no translation. This is why gettext/jsgettext was chosen.

GoraExplorer has been designed to mark the translation texts with the methods (js) _(text), _(context, text), _n(singular_text, plural_text, quantity [,context]) and _x(context, text).

The text written as key for translation is the default translation (english). When a translation exists, it is shown, and if there isn't any, the key is used as fallback.

ExtJS lacks the support for any external internationalization systems, so some code has been modified. At runtime, the Manifest of the application is modified at Ext.beforeLoad (index.html) so the bootstrap will import:

• The file resources/i18n/<language>.js, which contains the translations for the chosen language. The file could not exist.
• The file resources/js/i18n.js, which defines the function _(), _n() and _x(). If the language does not exists, it notifies the user.
• The file from ExtJS core ext/classic/locale/overrides/<language>/ext-locale-<idioma>.js with the localization for the language.

This way of bootstrapping the internationalization is a must to have the translation system initialized before any other application file based on a dynamically chosen language.

The language is saved in the LocalStorage at the key user-language, so it is local to the browser.

Translation loading process

The manifest is modified at runtime so the bootstrap will load the followin files in order:

• resources/i18n/<language>.js: defines a global js variable json_locale_data with all the translations for defined for a given language.
• resources/js/i18n.js: instantiates a Gettext instance with the information at json_locale_data and defines the translation functions _(), ...
• Loads the js files of Ext JS
• Loads the file resources/js/bigTranslations.js responsible for the translations of big static texts existing in DIVs, like welcome-text at index.html.

Add a new language

To add a new language, the steps are:

• Add visually the language to the language combo at view/settings/Language.js. The value of iconCls will be used as language code and for the name of the localization from ExtJS core files.
• Add the flag image to sass/etc/flagIcons.scss.
• Add the .po file of the language to resources/i18n/
• Configure in the .po file the search folders:
• • app
• • classic/src/
• • resources/js/bigTranslations.js
• Configure the .po file to use the keyworks shown at the beginning of this guide.
• Compile the translations .po into .js with the generate_js.sh script.