Multi-Lingual Support for XPage Controls via Properties Files

01/26/2011 05:00 AM by Chris Toohey

While working on Remote Console HD, I thought I would heed the advice of a friend from the community and look into providing language skins for my apps. Of course, there are absolutely tried and tested methods for doing this using traditional IBM Lotus Notes Domino Development techniques... but with .Properties File Resources, it's infinitely easier with XPages!

The idea is simple: Field/Input labels, View Column Headers, and any in-app content would have a translation that could be applied across the application. In other words, the Readers Field for Remote Console HD would have an English label (Restrict to), a Spanish label (Limitar a los), or even a German label (Beschränken auf).

Again, certainly techniques available using traditional Design Elements for something like a label (Computed Text looking up a Language Profile is most common...), but when you get into View Column Headers, it gets really tricky.

XPage Controls, however, don't fall victim of such limitations.

Jeremy Hodge recently wrote an excellent article on using .Properties files to create Global Variables for your XPage apps, and it was that article that inspired the technique I used for my own localization of Remote Console HD.

To start, I created a new File Resource named language.properties, with the following content:

[line numbers below have been added for reference purposes, and not part of the text added to the .Properties File Resource]

Lines 18, 19, 24, and 27 above contain the escaped unicode characters for ñ, ó, ä and ü respectively. A complete list of unicode characters [which you'll need to reference in order to truly go multi-lingual] can be found at http://en.wikipedia.org/wiki/List_of_Unicode_characters.

Once you have created your .Properties File, you can add it as a Resource to your XPage.

Once you have selected Add\Resource Bundle... from the XPage Resources section of the XPage Properties Pane, you will select your .Properties File and define a Resource Bundle Name (which acts as a variable declaration for use in your XPage).

Added to the XPage, you can now reference any value in the .Properties File via the following syntax:

... or, for a less-confusing way to put it:

Fairly straight forward from here really. Let's take a look at a demo block of labels for Remote Console HD:

With some CSS, we get the following:

Taking this technique one step further, we can use the Default Language Option defined in the language.properties File:

From here, the Lotus Professional who purchased their copy of Remote Console HD would only need to change the .Properties File Resource [which could even be done programmatically via Java] language value from EN to SP to change all labels, view column titles, and all other content wired to the language.properties Resource Bundle.

You could even provide a user profiling facility in the application to allow for individual language preferences, or base the leveraged name/value pairs on a UI Trigger:

Here we have a simple comboBox Control that performs a Partial Refresh on the uitrigger_elements panel Control, which is wired to the value of said comboBox Control. The logic here is pretty simple: If the languagepicker comboBox value is blank, use the Resource Bundle's default language designation, otherwise use the language defined by the comboBox.

Combine this with the .Properties Resource Bundle read/write capabilities available vi a Java (which I believe Jeremy is working on a follow-up to the previously-mentioned article that inspired this one illustrating a Java read/write/save example for Resource Bundles), and you can really get a feeling for the awesome potential of this technique.

You can view a demo of this technique in action now at http://guru.gbs.com/demo/demo.nsf/babelfish.xsp, and a huge thanks to Jeremy Hodge, who not only inspired this article but who also helped me figure out the need to escape unicode special characters.