Localizing J2EE Web Applications

"Standardize when possible, localize when necessary." That's probably the only principle I remember from an International Marketing course I took over 10 years ago – and definitely the only one I've ever applied!

To successfully compete overseas, you'll need to localize your J2EE application. Whether your customers live in Africa, Asia, Europe or South America, they'll prefer to work with a GUI that's presented in their native language.

Localization Strategies

Developers who couldn't design a system to save their life localize their J2EE application through duplication. They copy and paste every single page and translate them, thereby creating two separate applications. As I'm sure you've already guessed, I'm not advocating this strategy.

What I am recommending, and what I've been using for the past few years, is a library called the "JSP Standard Tag Library", more commonly known as JSTL.

JSP Standard Tag Library (JSTL)

JSTL, an open source Java solution maintained by the Jakarta Project, encapsulates the core functionality common to many Web applications. One of those common tasks is I18N. (For those not familiar with the term I18N, it's a standard abbreviation for "internationalization", which starts with the letter I, ends with the letter N, and contains a total of 18 letters.)

The I18N custom tag library contains tags that help manage the complexity of creating localized J2EE applications. All it requires is a servlet container that supports the JSP specification version 1.1 or higher.

The steps required to get up and running with the JSTL library are very straightforward:

1. Copy the tag library JAR file (jstl.jar) to the WEB-INF/lib subdirectory of your Web application.
2. Copy the tag library descriptor file (fmt.tld) to the WEB-INF subdirectory of your Web application.
3. Add the following taglib element to your Web application deployment descriptor in WEB-INF/web.xml:

<taglib>
  <taglib-uri>http://jakarta.apache.org/taglibs/jstl</taglib-uri>
  <taglib-location>/WEB-INF/fmt.tld</taglib-location>
</taglib>

From there, you can use the tags in your JSP pages by simply adding the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/jstl" prefix="fmt" %>

Setting the Language of Choice

The first thing you'll want to do in your application is determining the user's language of choice. While you can read the language from the browser's settings, this method is usually not recommended. Although it's the easiest alternative from a developer's perspective, most users are not aware that they can change their language setting through the options menu. It's therefore not very user friendly.

The preferred alternative is having a hyperlink right in the JSP page that allows the user to click and select his language of choice. In order to do that, all you need to do is hardcode the supported languages in your JSP page, along with their respective locales. As soon as someone clicks on the hyperlink, you can set the session locale to the language of choice.

Let's illustrate with an example. You are currently reading this article in English. If this site supported French, it could simply have a "French" (or "Français") hyperlink on one of its menus. By clicking on the "Français" hyperlink, the page would post to a servlet that would set the session locale to "fr", which is the standard two-digit string representing the French language. From then on, every single request would use this session locale to generate its pages.

Resource Bundles

Once the JSTL library is integrated in your J2EE application, you can start assembling "resource bundles", which are nothing more than property files that contain translated text strings. These files, which must be stored in your Web application archive under WEB-INF/classes , contain a list of key/value pairs such as demonstrated in the next example:

# This is a resource bundle called "system.properties"

heading.title = Welcome to
application.name = My Web Site
instructions = Please fill out this form to find an article.
criteria.name = Name:
criteria.author = Author:
button.search = Search
button.clear = Clear

The above example creates a file called "system.properties". This default file represents the catch-all language because it is not associated to a specific locale. It's therefore only used when the JSTL library cannot associate a resource bundle with the session locale that the user requested.

Mapping Locales to Bundles

To map a resource bundle to a specific locale, you simply need to append the bundle's name with the two-digit suffix that represents the valid locale. For example, to create a French bundle, you would create a file called "system_fr.properties". This bundle would look like the following:

# This is a French resource bundle called "system_fr.properties"

heading.title = Bienvenue à
application.name = mon site Web
instructions = Veuillez remplir cette forme pour trouver un article.
criteria.name = Nom:
criteria.author = Auteur:
button.search = Recherche
button.clear = Effacer

Note that only the values in system_fr.properties were translated. The keys were left intact. Translating the keys would obviously break the page since JSTL refers to that key to find the correct string to display.

Initializing the Bundles

Once the bundles are stored under WEB-INF/classes , you can then declare and initialize them in your JSP pages and replace any hard coded string with an fmt action, such as demonstrated in the following example:

<fmt:setBundle basename=”system” var=”myBundle” />
<fmt:message key=”heading.title” bundle=”${myBundle}” />
<fmt:message key=”application.name” bundle=”${myBundle}” />

The JSTL library will automagically grab the translated strings from the resource bundles depending on the session locale. Since system.properties is the catch-all language, the GUI would display "Bienvenue à mon site Web" to all its French users and "Welcome to My Web Site" to anyone else.

Supporting Two Varieties of the Same Language

Need to support two varieties of the same language? Say British and American English? No problem.

The properties files can be appended with up to three suffixes to represent a language, country, and dialect (in that respective order). You can therefore store system_en_us.properties and system_en_gb.properties under WEB-INF/classes to support both American and British English.

Useful Hints

I've been using JSTL for a few years now. If you're familiar with taglibs in general, you'll have no problem integrating JSTL to your J2EE application. However, there are 3 hints I'd like to give you before you start using it.

Hint #1

A space in the key is interpreted by JSTL as an equal sign. In other words, the entry:

application.name = My Web Site

is equivalent to:

application.name My Web Site

It's therefore important that the keys in your properties file do not contain any space characters. That being said, if you insist on including spaces in your keys, you can escape them with the "\" character.

Hint #2

An end of line signifies that the value is terminated, and JSTL assumes that the next line contains a new key. For example:

instruction = Please fill out this form
to find an article.

is interpreted by the JSTL library as two key/value pairs. The first key is "instruction" and holds the value "Please fill out this form", and the second key is "to" and holds the value "find an article."

If you want to break a value over several lines, make sure you escape the end of line using the "\" character such as demonstrated in the following example:

instruction = Please fill out this form \
to find an article.

Hint #3

When writing or loading dictionaries to/from a stream, the ISO 8859-1 character encoding must be used. In other words, you can't save a file containing Chinese characters in UTF-8 format and load it in the JSTL library. You must first convert it from UTF-8 to ISO 8859-1.

Various tools exist to convert files from one encoding to another, including my favorite, "native2ascii". Make sure you run your property files through such a converter before loading them in JSTL.

In Summary…

That's it for this article. And if there's only one thing that you remember today, please let it be the following statement: If you want to translate your J2EE Web application, use JSTL, not copy and paste!

---

This article was originally published on www.developerhub.com.