Localization

Aria 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

Aria 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. Aria 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 Page 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 Page it would be useful to show an example.

A basic page using a resource

 <Page resource="en">
   <Components>
     <Label x="10" y="130" w="400" h="30" content="GREETING"/>
  </Components>
 </Page>

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.

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.

Set the resource attribute to blank

 <Page resource="">
   <Components>
     <Label x="10" y="130" w="400" h="30" content="GREETING"/>
  </Components>
 </Page>

The default language can now be set in the startup.properties file with the following entry.

Setting the default application language

 Language=en

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.

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.

The modified Welcome page

 <Page class="org.formaria.langsample.Welcome" resource="">
   <Components>
     <Label name="testLbl" x="10" y="130" w="400" h="30" content="GREETING" opaque="true" style="Stripe"/>
     <Button name="language" x="10" y="180" w="400" h="30" content="Change Language" style="base"/>
     <Button name="continue" x="10" y="230" w="400" h="30" content="Next" style="base"/>
   </Components>
   <Events>
     <Event target="continue" type="ActionHandler" method="next"/>
     <Event target="language" type="ActionHandler" method="changeLang"/>
   </Events>
 </Page>

The two push buttons have ActionHandler events associated with them so the ` org.formaria.langsample.Welcome ' class needs to be created to implement these handlers, we can see this below:.

The implementing class for the Welcome page

 package org.formaria.langsample.Welcome;
 
 import org.formaria.aria.*;
 import org.formaria.langmgr.LanguageChooserDialog
 
 public class PosScreen extends Page {
 
   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 PageManager 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.

The NextScreen XML definition

 <Page resource="">
   <Components>
     <Label name="testLbl" x="10" y="130" w="400" h="30" content="BYE"/>
   </Components>
 </Page>

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:

• ARIA_SELECT_LANGUAGE,
• ARIA_CANCEL,
• ARIA_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 Aria Pro]

Aria includes an editor (The language editor.) 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 Aria'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

Aria'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 Aria the language strings are stored in properties files. These files must be encoded in an encoding that matches your applications encoding. Aria 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.

Locale specific properties

When a language resource bundle is loaded it is possible to set some locale specific to control how the text is loaded and rendered.

The EncodedLanguageResourceBundleLoader class attempts to load a file with the name .property_encodings to set these properties. The file can contain values for the encoding to be used to read the .properties file corresponding to the current language.

To install this resource bundle loader add the following to your code prior to loading any resource bundle:

Setup the resource bundle loader2

 currentProject.setResourceBundleLoader( new EncodedLanguageResourceBundleLoader( currentProject ));

Then, for each language a .property_encodings file can be created, so for example a language XX can have the following additional properties.

XX.property_encodings

 encoding=UTF16
 font_arial=NimSum
 font_arial10=NimSum;12