Java Internationalization: An Overview

Note: As recently as JDK 1.1.6, Locale.setDefault() causes a security exception in applets, so you might want to avoid this call in applets. As a workaround, instead of relying on the default locale, you can explicitly pass a Locale object to every locale-sensitive object you use. It's inconvenient, but it's a relatively easy fix to implement, especially if you're creating applets. You don't need to worry about the problem in applications, because you have more security rights on the local machine.

There are two additional methods that might interest you. They are getISO3Language and getISO3Country. When creating Locales, you always use the two letter ISO codes, but if you want to see them, you can use these methods to retrieve ISO's three letter codes for the same information.

After declaring the Locale as the core of Java internationalization, it might sound contradictory to say that this class doesn't do a lot on its own. A Locale's power comes from the classes that use it. In a Java application, each locale-sensitive object is responsible for its own locale-dependent behavior. A Locale object doesn't enforce this behavior, it simply acts as an indicator to other objects. Those objects are then responsible for using the Locale appropriately. By design, locale-sensitive classes are independent of each other. That is, the set of supported Locales in one class does not need to be the same as the set in another class. In practice, however, the current JDK 1.1.6 provides support to a single, shared set of locales.

In traditional operating systems and localization models, one locale setting is active at a time. You programmatically set the locale. Thereafter, all locale-sensitive functions use the specified locale selection. The specified locale is active throughout the application as a global locale. It changes when there is another global locale activation via a setlocale or similar call. Java technology, however, treats locales a little differently. A Java application can have multiple locales active at the same time. That is, it's possible to use a French date format and a U.S. number format in the same application. Nothing limits you from creating truly multicultural and multilingual Java applications.

Numbers

What number does 1,234 represent? Of course, the answer depends on locale. In the U.S, this string of digits represents one thousand two hundred and thirty four. However, in France this represents one and two hundred thirty four one-thousandths. Significant difference? Absolutely! Imagine you're a chemical manufacturer that just received an order for 1,234 kilograms of a certain chemical. Your interpretation of this number will definitely affect your sales quotas for the month.

Numbers are represented differently around the globe. When an application shows a number to the user, it must represent that number in a way that is sensitive to the cultural expectations regarding decimal point symbol, group separators, number of digits after the decimal, and leading zeros.

The java.text.NumberFormat class performs locale-specific formatting for both general purpose numbers. To instantiate a NumberFormat object, use the factory method getInstance, which returns a NumberFormat object suitable for your default locale. You can, of course, ask for an object with a specific locale in mind. To specify a locale other than your default, use getInstance(Locale locale).

If you are curious about what locales are supported, you can use the class method getAvailableLocales. This method returns an array of Locales.

Formatting a number couldn't be easier. Call the instance methods format(long number) or format(double number) to produce a String object that's suitable for displaying to the user. Other methods allow you to customize the format by turning various options on or off.

Currency

Each locale has its own preferences for currency symbols, negative amount format, leading zeros, group separators, decimal point symbol, and currency symbol position. Currency and numbers have a lot in common. In fact, they even use the same basic format class, NumberFormat, to instantiate new objects.

Although you still use NumberFormat, you call a different factory method to get a currency format object, getCurrencyInstance. This method will return a currency format object for the default locale. You can use this factory method just like you used the number factory method; call getCurrencyInstance(Locale locale) to specify a specific locale. Again, use the format method to produce a user visible String object. The currency formatter will handle all the details of selecting the correct currency symbol, placing that symbol in the string, and applying grouping rules. Also, like the number formatter, you can override several options to customize the format.

Date

A date helps to uniquely identify a point in time. Like other locale-sensitive structures, dates have many representation details. You must consider long and short date formats as well as date separator symbols. You have to worry about whether the year is displayed before the day and month or after. Again, the Java class libraries accommodate these needs.

The java.text.DateFormat class provides the getDateInstance method that creates a formatter for your default locale. The format method works in the same way as the other format methods covered so far, and applies the specific format rules for your chosen locale.

Calendar

The java.text.Calendar class is closely related to Date, and lets you extract year, month, week, and day information from a Date. You won't use Calendar directly. Instead, use getCalendarInstance to get a calendar object for your locale. The Gregorian style calendar is the only one provided at this time; however, you can create your own by subclassing Calendar.

Resource Bundles

This internationalization feature of the JDK provides a mechanism for separating user interface (UI) elements and other locale-sensitive data from the application logic in a program. Separating locale-sensitive elements from other code allows easy translation. It allows you to create a single code base for an application even though you may provide 30 different language versions. Although you might be predisposed to think of text only, remember that any localizable element is a resource, including buttons, icons, and menus.

The JDK uses resource bundles to isolate localizable elements from the rest of the application. The resource bundle contains either the resource itself or a reference to it. With all resources separated into a bundle, the Java application simply loads the appropriate bundle for the active locale. If the user switches locales, the application just loads a different bundle.

Resource bundle names have two parts: a base name and a locale suffix. For example, suppose you create a resource bundle named MyBundle. Imagine that you have translated MyBundle for two different locales, ja_JP and fr_FR. The original MyBundle will be your default bundle, the one used when others cannot be found, or when no other locale-specific bundles exist. However, in addition to the default bundle, you'll create two more bundles. In the example these bundles would be named MyBundle_ja_JP and MyBundle_fr_FR. The ResourceBundle.getBundle method relies on this naming convention to search for the bundle used for the active locale.

The java.util.ResourceBundle class is abstract, which means you must use a subclass of ResourceBundle. The JDK provides two subclasses: PropertyResourceBundle and ListResourceBundle. If these don't meet your needs, you can create your own subclass of ResourceBundle.

PropertyResourceBundle

The PropertyResourceBundle is the most convenient bundle to use. To use this bundle, create a property file that contains key/value pairs in the form <key>=<value>. List each key/value pair on the same line of the file, and separate each pair with a new-line character. The following figure shows an example of PropertyResourceBundle.

# MyResource.properties
# <key>=<value>
TEXT_NOT_FOUND=The file could not be found.
TEXT_HELLO=Hello, world!
TEXT_WARNING=
  There are {0} warnings in the file {1}.
TEXT_INSERT_PAPER=Please insert more paper.
TEXT_DISREGARD=
  Please disregard the man behind the {0}.

// MyResource.java
import java.util.ListResourceBundle;

public class MyResource 
  extends ListResourceBundle {

    public Object[][] getContents() {
        return contents;
    }

    public static Object[][] contents = {
      { "TEXT_NOT_FOUND", 
        "The file could not be found." },
      { "TEXT_HELLO", 
        "Hello, world!" },
      { "TEXT_WARNING", 
        "There are {0} warnings in the file{1}." },
      { "TEXT_INSERT_PAPER", 
        "Please insert more paper." },
      { "TEXT_DISREGARD", 
        "Please disregard the man behind the{0}." },
    };
}