20 Localization
Carousel includes the ability to render an application in different national languages and allows the user to change the language with relative ease and provides built-in tools to assist the translator in localizing an application.
The translation mechanism
Carousel uses Java's resource bundles mechanism for translation of text. Whenever a page is constructed the component factory attempts to translate the text belonging to each component as it is constructed.
The resource bundles are property files that contain a list of keys and strings. Carousel uses the text or content of each component as the key and attempts to look to the key in the resource bundle.
The resource bundle for each page can be specified in the page XML by including a ' resource ' attribute in the XPage element. The attribute names the resource bundle to be used for the page.
Like most files the resource bundle is loaded by the project and it maintains a list of resource bundles. When a page is being constructed and components are added via the component factory in the normal way the component factory obtains a reference to a resource bundle and looks up the translations for whatever text is required.
Therefore when specifying the content for a component via XML or Java, the text for a multilingual application should be the key text for the string in the resource bundle. Once this is done you will need do very little more to translate an application.
Choosing the language
If this resource tag for a page is specified using an evaluated attribute the resource bundle can be configured dynamically throughout the application lifecycle. Alternatively an application can explicitly change the resource bundle used by the component factory to force a change in languages.
Whatever mechanism is used to change the resource bundle, the pages must be reloaded in order to effect the change in languages. It is also a good idea to prompt the user for the language selection.
Setting the resource attribute for a page
In order to show the mechanisms involved in setting the language for an XPage it would be useful to show an example.
Code Sample 20-1 - A basic page using a resource
|
|
This file shows that the resource attribute is set to "en" so the en.properies file will have to reside in the resource directory. The contents of that file are.
Code Sample 20-2 - The en.properties file
GREETING=Hello
BYE=Goodbye
|
When run, the application will start with the page containing the text 'Hello' which is read from the en.properties file.
In order to set an application wide language without having to reset the language on each page set the resource attribute to blank for each of the pages which need to be translated. This is an important point which can cause confusion. The resource attribute must not be removed but left blank in order for this to work.
Code Sample 20-3 - Set the resource attribute to blank
|
|
The default language can now be set in the startup.properties file with the following entry.
Code Sample 20-4 - Setting the default application language
|
|
Now if a new language is required its a simple matter of creating the resource file for the language and specifying it in the startup.properties. So if French, for example, is to be the default language, create the following properties file.
Code Sample 20-5 - The fr.properties file
GREETING=Bonjour
BYE=Au Revoir
|
Set the ' Language ' startup property to ' fr ' and the first page will read ' Bonjour '.
Changing languages in the application
Of course, it is not sufficient to set the startup language and leave it at that. The application needs to be able change language according to the requirements of the user. To illustrate this the previous example can be extended.
Change the first page to include a button to change language and also to proceed to a new page.
Code Sample 20-6 - The modified Welcome page
|
|
The two push buttons have ActionHandler events associated with them so the ' com.xoetrope.langsample.Welcome ' class needs to be created to implement these handlers, we can see this below:.
Code Sample 20-7 - The implementing class for the Welcome page
package com.xoetrope.langsample.Welcome;
import net.xoetrope.xui.*;
import net.xoetrope.langmgr.LanguageChooserDialog
public class PosScreen extends XPage {
public void changeLang()
{
saveBoundComponentValues();
LanguageChooserDialog chooser =
new LanguageChooserDialog(
project.getStartupParam( "Language" ));
chooser.pack();
chooser.showDialog( this, null );
String language = chooser.getSelectedLanguage();
if ( language != null ) {
// Set the startup parameter for subsequent pages.
project.setStartupParam( "Language", "en" );
//Unload all of the cached pages
pageMgr.reset();
// reload the current page or reset/reinitialize the page if necessary.
pageMgr.showPage( "Welcome" );
updateBoundComponentValues();
}
}
public void next()
{
pageMgr.showPage("NextScreen");
}
}
|
The changeLang method sets the new language, then clears the cached pages in the XPageManager and finally reloads the Welcome page. The method uses a LanguageChooserDialog , but this dialog is optional and you can use other means to identify the desired language just as well.
The next() method is switching pages to the NextScreen page so that also needs to be created.
Code Sample 20-8 - The NextScreen XML definition
|
|
This page refers to the other key in the resource files. In order to test the functionality set the Language property in the startup file to fr and start the application. The first screen will read Bonjour . Click the continue button to get to the next screen and it will read Au Revoir .
Now restart the application and this time click the Change Language button. The text will change from Bonjour to Hello . Click the continue button again and the text on the next page reads Goodbye .
It is now a simple matter of replacing the functionality described with a list of languages or country flags for the user to set the language.
Localizing the Language Chooser
The language chooser itself can be localized so that the button texts and captions can be presented in the current language. The language chooser uses the very same method for localization as described above and uses three language keys:
CAROUSEL_SELECT_LANGUAGE,
CAROUSEL_CANCEL,
CAROUSEL_OK .
To localize the dialog just add the translations for these three keys to your language file.
Scanning a project with the language editor
[This is a feature of Carousel]
Carousel includes an editor ( "The Language Editor" on page 193) that allows translators to easily work with translations. This editor is covered in detail in a separate chapter.
One of the key aspects to working with the language editor and with localization in general is to prepare the resource bundles for translation. Rather than forcing the application developer to constantly interact with the localization facilities Carousel's language editor provides a means of scanning an application for text. Using this option all pages within the project are scanned and any text that is not already part of the translation setup is added to the list of strings for translation.
Distribution of language files
Carousel's language files are largely standalone and can be distributed on an individual basis so that the download for one user is not burdened with language files that may be of little or no use to an individual. Language files may also be swapped for branding and customization reasons or whenever a new or updated translation becomes available.
Encoding issues
The issue of character encoding inevitably arises when working with localized files. In Carousel the language strings are stored in properties files. These files must be encoded in an encoding that matches your applications encoding. Carousel by default uses UTF8 encoding and this should be sufficient for most language. The default encoding is controlled by a startup parameter, DefaultEncoding , which can be changed manually if needed.
Another significant issue you may have when working with localized files is the patchy support for character encodings in some editing tools. Some editors claim to save in a particular encoding but for one reason or another fail to do so consistently. Therefore we recommend testing all the tools your localization team uses prior to doing a full scale localization.
If you were logged in you could rate this article or add a comment.
