Wiki
Clone wikiGoraExplorer / Internationalization
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 variablejson_locale_data
with all the translations for defined for a given language.resources/js/i18n.js
: instantiates a Gettext instance with the information atjson_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, likewelcome-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 toresources/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 thegenerate_js.sh
script.
Updated