How to Localize an application
From WebRatio WebML Wiki
|
|
|
Contents |
Introduction
WebRatio provides a built-in functionality for the localization of Web applications. The localization is based on the use of keys instead of terms for all the static elements in the applications (such as labels, Units and Page Titles, etc.). WebRatio permits to define several locales providing the translation of each key in every language defined. At runtime, the keys in the applications are replaced with the terms provided for a particular locale. With this structure of keys and related terms it's possible to realize a Web application without concerning the particular languages the application must support, due to the complete separation between the Web Model and the locales management.
Localized applications
In order to realize a localized application it's necessary to check the Localized property. It's possible to define as localized an entire Site view, an Area or only a Page. Defining a Site View or an Area as localized means that every pages contained is localized.
Once the Localized property is checked, every term in the application is turned into a key and it's necessary to provide a translation of every term in all the locales needed for the application. At runtime the translation for every key is searched in proper properties file.
In the two images above it's possible to see what happens in a generated application once it's defined as localized. All the terms defined in the Web models (such as field labels, Unit titles, etc.) are transformed in keys used to retrieve the locale terms. In this example the terms are not provided, as stated by the "???" surrounding the keys. It's possible to note that the localization functionality has no impact on the dinamic contents displayed (such as text retrieved from the database).
In order to make the localization works properly it's necessary to define all the desired locales and the translation of the keys.
The Localization Window
The definition of locales is performed through the localization window. To access the localization window press the Localize button in the menu or right-click on an element and select Localize.
The localization window permits to add, delete and modify all the locales defined for an application.
The localization window is structured as follow:
- in the left panel all the defined locales are listed
- in the right panel there are all the keys used in the Web model, whit the corresponding term in the selected locale, grouped in sections listed on the left (inherited by the Web model structure)
- at the bottom we can choose to define for every locale the messages or the patterns
Defining new locales
By default the first locale defined is English [United States]. The default locale is the locale used when there is no locale corresponding for the particular language used by an user. It's always possible to change the default locale in every moment. To add a new locale:
- Right-click on the Locales root node and select "Add Locale".
- The "Locale Selection" window is displayed. In this window we can choose the ISO Language and ISO Country codes defining the new locale.
Once the new locale is added it's possible to define all the localized messages and patterns.
Messages
Once the new locale has been created, it's possible to select each key and insert it's translation in the current locale.
If a key is in the model has been written for a locale, we can use it for the localization, without providing the message (since it will be just alike the key). Just right click on the key and select "Set Default Messages", in this way, the key will be used as message.
WebRatio provides default messages for several keys such as error messages and scrolling links.
Custom Messages
Whenever it's needed to provide a localized message concerning an element not present in the Web model, such as an empty unit message, we need to add a Custom key to the default set of keys present. To add a Custom key, right click on the Custom label and select "Add Custom Key" or "Add Custom Keys"(1). Here we can define both the key and the message related (2).
From now on the Custom key can be used in every locale.
Patterns
Besides messages it's possible to define pattern related to the locale for the visualization of data types such as boolean, date, etc.
In this page it's possible to express the pattern to render every datatypes whitin a locale.
Application Resources properties file
In the generated application, every locale is stored in a properties file that contains all the couples key/message for a specific locale. These files are in <application folder>/WEB-INF/classes/, named ApplicationResources_<ISO Language code>_<ISO Country code>.properties. Here's an excerpt from the ApplicationResources_en_US.properties file of the ACME project:
...
Offer\ of\ the\ day=Offer of the day
Offers=Offers
OID=OID
password=password
Password=Password
photo=photo
...
Runtime behavior
At runtime, when a user access the localized application, the ISO Language and Country codes are retrieved from the request (the ones set as default in the user's browser) and stored in the LanguageISOCtxParam and CountryISOCtxParam Context Parameters respectively.
When the user access a page, the application searches for the application resources properties file corresponding to the locale identified by the ISO codes contained in the Context Parameters. If there isn't a corresponding locale, the default locale is loaded and all the keys contained in the page are substituted with the corresponding message of the selected locale. In this way the application uses the appropriate local for every user.
Change current locale at runtime
In many case the default Country and Language ISO Code set in the browser used to retrieve the locale are different from the ones of the desired locale of the user. It's possible to give to the user the possibility to explicitly choose the desired locale among all the locales defined. All is need is a Set Unit that changes the LanguageISOCtxParam and CountryISOCtxParam Context Parameters with the one chosen by the user.
Changing the Context Parameters causes the application to load the desired locale, changing all the messages.
