Tutorial 4 : Internationalisation

Requirement

Please read the Tutorial 3 first.

Internationalize the application

Download this tutorial step.

I18n concepts

Internationalization (or i18n) with Kuix is achieve by using localized resources files. Kuix provides a static method that looks for a translation for a given label and return the result as a string. This method uses the device local to select the appropriate resource file and if it cannot be found, it uses the default one.

Resource files are (by default) in the /i18n directory and should comply with the following naming convention:

messages.en.properties
where "en" stands for the language string

Several "system" labels - like "Ok", "Cancel", etc. - have a default translation. So if you use some message box with buttons, you will have a default english translation for them.

The label translation method:

The following command, will make Kuix to look for a translation for the given label in a localized resource file or by default in /i18n/messages.properties. If an entry is found, it returns the translated text otherwise it is the string of the entry.

Kuix.getMessage("OK");

If you want to distribute your application in 2 languages - english and french for instance -, you will have to create at least 2 files : messages.fr.properties and a default english file messages.properties.

The translation file syntax

The syntax of the translation file is as simple as:

LABEL=translation

Create the labels and translate them:

create file messages.properties and set the following content:

YES=Yes
NO=No
OK=Ok
HELLOWORLD=Hello World!
ABOUT=About
EXIT=Exit
MORE=more...
CREDITS=This helloworld is powered by Kuix!
EXIT_CONFIRM=Are you sur you want to quit?

Create the file messages.fr.properties and set the following content:

YES=Oui
NO=Non
OK=OK
HELLOWORLD=Bonjour tout le monde !
ABOUT=A propos
EXIT=Quitter
MORE=plus...
CREDITS=Ce Helloworld a été créé avec Kuix!
EXIT_CONFIRM=Etes-vous sûr de vouloir quitter?

The 3 first labels are used for the popup windows and should work immediately. But we will need to reference the 3 last ones.

Your project structure must be now like this :

Edit the Frame to use the translation labels

This step is straigth forward. You just need to open the HelloWorldFrame class and replace the texts by their respective labels:

if ("about".equals(identifier)) {
    // display a popup message
    Kuix.alert(Kuix.getMessage("CREDITS"), KuixConstants.ALERT_OK);
    return false;
}
if ("exitConfirm".equals(identifier)) {
    // display a popup message
    Kuix.alert(Kuix.getMessage("EXIT_CONFIRM"), KuixConstants.ALERT_YES | KuixConstants.ALERT_NO, "exit", null);
    return false;
}

Reference a translated text in the XML file

Since it is not possible to call the Kuix.getMessage() method from the XML file, the fallowing syntax has been integrated to the parser so that you can reference a translated label directly:

%LABEL%

For performance considerations, variables cannot be used in the attribute but only from the XML values. As a consequence, if you want to use some translated text, you can use one of the following syntax:

• Any text alone is interpreted as a Text node:

  %LABEL%
  

• Any text in a Text node, is always associated to this node:

  <text>%LABEL%</text>    
  

• In a more general way, to set a node's attribute to a variable value, open a _ATTRIBUTENAME node and set its value between its opening and its closing tag:

  <text><_text>%LABEL%</_text></text>
  

Edit the XML to use translated labels

You should get something like:

<screen title="helloworld">
    <container style="layout:inlinelayout(false,fill);align:center">
        %HELLOWORLD%
        <picture src="logo_community.png" />
        <button onAction="about" shortcuts="1">%ABOUT%</button>
        <button onAction="exitConfirm" shortcuts="back|delete|0">%EXIT%</button>
    </container>
    <screenFirstMenu onAction="exit">%EXIT%</screenFirstMenu>
    <screenSecondmenu>
        %MORE%
        <menuPopup>
            <menuItem onAction="about">
                %ABOUT%
            </menuItem>
            <menuItem onAction="exitConfirm">
                %EXIT%
            </menuItem>
        </menuPopup>
    </screenSecondmenu>
</screen>

Start the international midlet

Translation parameters

Note that a translation label can contain one or more parameters that will be used in the translation. This feature is especially useful when you want to mix translated and untranslated texts in the same widget.

• The syntax in the translation file is given by the example below:

  VALUES=Values: {0} {1}
  

• In the XML file:

  %VALUES(female,male)%
  

The comma is the only valid parameter delimiter. Avoid using it in your parameters values.

• And finally in Java ME:

  String param1 = "female"; 
  String param2 = "male"; 
  Kuix.getMessage("VALUES", new String[] {value1, value2});
  

---

Go forward, add dynamic data display : Tutorial 5.