i18n

All WComponents which display text content to the user already support display of internationalised text. Adding internationalisation support to an application only involves a few steps.

• Configuring the resource bundle location.
• Creating the resource bundle files
• Setting the Locale
• Building the application UI
• Internal WComponents messages
• Limitations
• Theme Internationalization

Configuring the resource bundle location.

The configuration parameter bordertech.wcomponents.i18n.baseName must be set to the resource bundle base name for the application. The value of the parameter should be the location (in the application's class path) of the resource bundles. File suffixes for the resource bundles follows the standard resource bundle naming approach, using the Locale's string representation.

Creating the resource bundle files

Applications can place mappings in property files, or source them from other locations (such as a database) by extending the java.util.ResourceBundle class and implementing the necessary methods. The class should be named using the same conventions as for property files.

An example web application archive structure is shown below. In the example, the default internal configuration is used, and the configuration parameter bordertech.wcomponents.i18n.baseName has been set to "resources/i18n/example" in the wcomponents_app.properties file. The two languages shown in the example are "en" for English (all countries), which is implemented as a Java class, and "fr_CA" for Canadian French, which is provided in a property file. It is always a good idea to include a default property file for a "default" language to use when a specific language is not found.

MyApplication.war

 |__ ...
 |__ WEB-INF
      |__ classes
      |     |__ wcomponents_app.properties
      |     |__ ...
      |     |__ resources
      |          |__ i18n
      |               |__ example.properties
      |               |__ example_en.class
      |               |__ example_fr_CA.properties
      |               |__ ...
      |__ ...

Setting the Locale

If not specified, the default Java Locale is used to translate component text. Applications can set the Locale per-user by using the setLocale(Locale) method on the UIContext obtained from the UIContextHolder. This is typically performed in either:

• the application "login" action, where the user is known, and may have a stored language preference;
• for a pre-authenticated user, on first accesses the application, by overriding WApplication's preparePaintComponent method; or
• for unauthenticated users, as an explicit component (e.g. button or menu item) somewhere within the application UI.

Building the application UI

The easiest way to build an application for a single language is to hard-code the text / messages in the UI code. This approach is not suitable for an application delivered in multiple languages as it results in maintenance issues. Consider the code fragment and mapping below:

WButton saveButton = new WButton("Submit");

Submit=Soumettre

The application may have several buttons which have the English text "Submit" but each button may require a slightly different text when translated to other languages. This is not possible if the mappings are keyed from the text. The second problem occurs when the text changes. If the text is used as a key to look up the values it will need changing in the source and every resource property file where it is used.

A better approach is to use a unique key for each component.

WButton saveButton = new WButton("SAVE_CLIENT");

Parameterised text is supported using the standard MessageFormat syntax. Setter methods such as WText's setText accept varargs message arguments.

String name = "Joe Bloggs";

WText helloWorldText = new WText();
helloWorldText.setText("HELLO_NAME", name);

A simple English mapping for HELLO_NAME could be specified as:

HELLO_NAME=Hello {0}

Internal WComponents messages

The WComponents validators and some components emit messages for the user but only provide English text. Applications will need to internationalise these messages by providing mappings in their resource bundles. All internal WComponents message keys are prefixed with bordertech.wcomponents.message.

The full list of messages keys and default text is available as a gettext pot file in the wcomponents-i18n respository. Translators can use the pot file in a tool like Poedit.

Limitations

WComponents only supports the UTF-16 Basic Multilingual plane. All encoding and validation functions assume that characters will fit within a single Java "char".

Theme Internationalization

See Theme i18n for information pertinent to front-end i18n.