Chapter 15
Localization and Internationalization

I would like to thank Felix Torre for assisting in the development of support for localization (l10n) in JMatter, and Marco Meschieri for meticulously going through the codebase to extract captions and other text so that they could be localized. This chapter documents the current support for l10n in JMatter.
The basic requirement is to be able to deploy a single application to a diverse population, in any of a combination of languages. For example, we may have both English-speaking and French-speaking users.
Fundamentally, JMatter resorts to one aspect of the Java language that was designed for localization: the notion of resource bundles. JMatter uses property-file based resource bundles. Multiple properties files are created. Each follows a certain convention to designate what language and locale it corresponds to, by combining a base name with a suffix.
Look at the Sympster demo application for example. You will find three files: locale-metadata.properties, locale-metadata_fr.properties, and locale-metadata_es.properties. So each suffix, _fr or _es, is a language designation: the former is the code for the French language, while the second designates Spanish. Resource bundles imply a specific hierarchy for retrieving values for specific keys in these property files: we check the computer's specific language and country. Let's say we're in Canada, where the language is fr and the country is CA. The system will look for the file locale-metadata_fr_CA.properties, falling back to the more generic _fr file, and finally, falling back to the most generic property file.
There exist two sets of locale-metadata files. The first set is located in jmatter/resources/app. In this file you'll find localization strings that apply to the framework in general. The second set of locale files are project-specific. So in your project, in the resources/ subdirectory, you'll find the second set of locale-metadata files
JMatter defines keys for retrieving all the labels and text rendered on the login dialog box. Here is how they're specified in the _fr resource bundle:
# Login Dialog
# ===============================
logindlg.lbl.username=Nom D'utilisateur:
logindlg.lbl.pwd=Mot de passe:
logindlg.msg.login=Entrez S'il vous plait..
logindlg.msg.failed_auth=Mauvais credentiaux; Essayez encore une fois..
logindlg.msg.user_locked=Votre compte est verouille;  
   Contactez l'administrateur svp..
JMatter also defines a convention for specifying type labels, command labels, and field labels that are shared by all applications:
# JMatter Global Localization Entries
# ===================================
Command.SaveAndClose=Sauve et Ferme
ComplexType.New=Fait Nouveau
User.username=Nom d'utilisateur
User.password=Mot de passe
Here we see that generic commands, shared by all types, are specified as Command.<commandname>. Generic type commands are specified using the key ComplexType.<commandname>. Other type commands and type fields are likewise specified using the key: <typename>.<fieldname - commandname>. When dealing with aggregate fields, you can use a multiple dot notation, as in Speaker.contact.homePhone (see below).
You can specify a localization for a field across multiple types shared in a base class by simply using the base class name in the field path. For example (French):
 AbstractComplexEObject.createdOn=Crée a la date
Here are some application-specific label designations for French, for the Sympster application:
# Application-Specific Localization Example Entries
# =================================================
Speaker.AddTalk=Ajoute Une Presentation
Speaker.contact.homePhone=Telephone Maison
Note also that plural designations can be provided. The key is simply the plural name for the type in English.
Here in the USA I can test how my application might look to a French speaker by revising the locale on my system, or by forcing a locale through a system property, as illustrated by the run target in build.xml:
 <target name="run" description="run app" depends="genhbm">
   <java classname="${main.class}" classpathref="class.path"
         fork="true" maxmemory="192m">
    <!-- to test localization, uncomment this..
     <sysproperty key="user.language" value="fr" />
Uncomment the <sysproperty> line and set its value accordingly. We've included a couple of snapshots of the resulting localized application (figures 15.1 and 15.2).
Figure 15.1: Login dialog localized for French
Figure 15.2: Partially localized Sympster Application (French)
We see a number of the commands now use French captions. The speaker is called a Presenteure, the field name becomes Nom and title becomes titre. Not all the text appears in French simply because I didn't provide a full list of values for all commands and fields. The figures don't show how the context menus also become localized. Open becomes Ouvre, etc..

15.1  States

When dealing with state machines, as we saw for example in the IssueMgr demo application, the state names can also be localized. For example, here's how the state names for issues are localized to French in IssurMgr's locale-metadata_fr.properties file:

15.2  Generic UI Localization

The user interface also has elements that need to be localized. For example Java Swing defaults to a resource bundle named "uidefaults" to pick up translations for tooltips such as a window's "minimize" button tooltip. JMatter will automatically load custom ui defaults specifications from the file jmatter/resources/app/uidefaults_??.properties. For example, the figure below shows some hebrew translations for ui defaults loaded by JMatter (the file name is uidefaults_iw.properties):
Figure 15.3: UI Defaults Localization (e.g. Hebrew)

15.3  Right-To-Left

JMatter will work with languages that have non-latin alphabets, and ones that are right-to-left such as Hebrew or Arabic. Check out the Sympster demo-app in Hebrew for example. In the USA, you can simply override the locale by uncommenting this line in the Sympster build file:
<sysproperty key="user.language" value="he" />
Following are a couple of screenshots.
Figure 15.4: Hebrew Login Dialog
Figure 15.5: Sympster Localized for Hebrew

15.4  Summary

Localization support in JMatter is by no means complete or exhaustive. For example, at the moment support for the proper date and currency formats for different locales needs work. We hope that future versions will flesh out this support completely.