Chapter 16
Using Internationalization

by Eric Ries

• Introduction to Internationalization Here you'll find an introduction to the concepts of Internationalization and an overview of the techniques used to implement it.

• Advantages of Internationalization There are many advantages of Internationalization over traditional techniques that you will learn about.

• Internationalization classes In-depth coverage of the new Java classes for implementing Internationalization in Java is included.

Joe Programmer is a Java developer for Company X. His distributed sales application is a huge success in California, where his company is based, mainly because he follows good object-oriented design and implementation: keeping his objects portable, reusable, and independent. One day, Company X decides to start selling its product in Japan. Joe Programmer, who does not know Japanese, gets a Java-literate translator to go through his code and make all the necessary changes using some custom Japanese language character set that Joe doesn't really understand. But he happily compiles this Japanese-language version of his code and sends it off to Japan, where it is a big success. Encouraged by this result, Company X starts moving into other markets; France and Canada are next. To Joe's dismay, he finds that he has to maintain several completely different versions of his code because France and Canada, although they share a common language, have a completely different culture! Poor Joe now has five compiled versions of his code: an American English, Japanese, French, Canadian French, and Canadian English. Now, when he makes even the slightest change to his code, he has to make the same change five times, and then hire several translators to make language changes directly in the source code. Clearly, Joe is in an unacceptable situation.

What Is Internationalization?

In the previous scenario, Joe Programmer is said to have written a myopic program, one that is only suited to one locale. A locale is a region (usually geographic, but not necessarily so) that shares customs, culture, and language. Each of the five versions of Joe's program was localized for one specific locale, and was unusable outside that locale without major alteration. This violates the fundamental principle of OOP design, because Joe's program is no longer portable or reusable. The process of isolating the culture-dependent code (text, pictures, and so on) from the language-independent code (the actual functionality of the program), is called Internationalization. Once a program has been through this process, it can easily be adapted to any Locale with a minimum amount of effort. Version 1.1 of the Java language provides built-in support for internationalization, which makes writing truly portable code easy.

Java Support for Internationalization

Java 1.1 introduces several changes to the Java language which support internationalization. In the past, writing internationalized code required extra effort and was substantially more difficult than writing myopic code. One of the design goals of Java 1.1 was to reverse this paradigm. Java seeks to make writing internationalized code easier than its locale-specific counterpart. The changes introduced with Java 1.1 mainly affect three packages:

• java.util Introduces the Locale class. A Locale encapsulates certain information about a locale, but does not provide the actual locale-specific operations. Rather, affected methods can now be passed a Locale object as a parameter which will alter their behavior. If no Locale is specified, Java 1.1 supports a default Locale taken from the environment. This package also provides support for ResourceBundles, objects that encapsulate locale-sensitive data in a portable, independent way.

• java.io All of the classes in java.io which worked with InputStreams and OutputStreams now have corresponding classes which work with class Reader and Writer. Readers and Writers work like Streams, except they are designed to handle 16-bit Unicode characters instead of 8-bit bytes.

• java.text An entirely new package that provides support for manipulating various kinds of text. This includes collating (sorting) text, formatting dates and numbers, and parsing language-sensitive data.

The Locale class

A Locale object encapsulates information about a specific locale. This consists of just enough information to uniquely identify the locale's region. When a locale-sensitive method is passed a Locale object as a parameter, it will attempt to modify its behavior for that particular locale. A Locale is initialized with a language code, a country code, and an optional "variant" code. These three things define a region, although you need not specify all three. For example, you could have a Locale object for American English, California variant. If you ask the Calendar class what the first month of the year is, the Calendar will try and find a name suitable for Californian American English. Since month names are not affected by what state you are in, the Calendar class has no built-in support for Californian English, and it tries to find a best fit. It will next try American English, but since month names are constant in all English-speaking countries, this will fail as well. Finally, the Calendar class will return the month name that corresponds to the English Locale. This best-fit lookup procedure allows the programmer complete control over the granularity of internationalized code.

You create a Locale object using the following syntax:

Locale theLocale = new Locale("en", "US");

where "en" specifies English, and "US" specifies United States. These two-letter codes are used internally by Java programs to identify languages and countries. They are defined by the ISO-639 and ISO-3166 standards documents respectively. More information on these two documents can be found at:

http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

Currently, the JDK supports the following language and country combinations in all of its locale-sensitive classes, such as Calendar, NumberFormat, and so on. This list may change in the future, so be sure to check the latest documentation (see Table 16.1).

Table 16.1 Locales Supported by the JDK

Locale	Country	Language
da_DK	Denmark	Danish
DE_AT	Austria	German
de_CH	Switzerland	German
de_DE	Germany	German
el_GR	Greece	Greek
en_CA	Canada	English
en_GB	United Kingdom	English
en_IE	Ireland	English
en_US	United States	English
es_ES	Spain	Spanish
fi_FI	Finland	Finnish
fr_BE	Belgium	French
fr_CA	Canada	French
fr_CH	Switzerland	French
fr_FR	France	French
it_CH	Switzerland	Italian
it_IT	Italy	Italian
ja_JP	Japan	Japanese
ko_KR	Korea	Korean
nl_BE	Belgium	Dutch
nl_NL	Netherlands	Dutch
no_NO	Norway	Norwegian (Nynorsk)
no_NO_B	Norway	Norwegian (Bokmål)
pt_PT	Portugal	Portuguese
sv_SE	Sweden	Swedish
tr_TR	Turkey	Turkish
zh_CN	China	Chinese(Simplified)
zh_TW	Taiwan	Chinese (Traditional)

Programmers can also create their own custom Locales, simply by specifying a unique sequence of country, language, variant. Multiple variants can be separated by an underscore character. To create a variant of Californian American English running on a Windows machine, use the following code:

Locale theLocale = new Locale("en", "US", "CA_WIN");

Remember that methods that do not understand this particular variant will try and find a "best fit" match, in this case probably "en_US".

The two-letter abbreviations listed here are not meant to be displayed to the user; they are meant only for internal representation. For display, use one of the Locale methods listed in Table 16.2.

Table 16.2 Locale Display Methods

Method Name	Description
getDisplayCountry()
getDisplayCountry(Locale)	Country name, localized for default Locale, or specified Locale
getDisplayLanguage()
getDisplayLanguage(Locale)	Language name, localized for default Locale, or specified Locale
getDisplayName()
getDisplayName(Locale)	Name of the entire locale, localized for default Locale, or specified Locale
getDisplayVariant()
getDisplayVariant(Locale)	Name of the Locale's variant. If the localized name is not found, this will return the variant code.

These methods are very useful when you want to have a user interact with a Locale object. Here's an example of using the getDisplayLanguage() method:

Locale.setDefault( new Locale("en", "US") ); //Set default Locale to American English
Locale japanLocale = new Locale("ja:, "JP"); //Create locale for Japan
System.out.println( japanLocale.getDisplayLanguage() );
System.out.println( japanLocale.getDisplayLanguage( Locale.FRENCH ) );

This code fragment will print out the name of the language used by japanLocale. In the first case, it is localized for the default Locale, that has been conveniently set to American English. The output would therefore be "Japanese." The second print statement will localize the language name for display in French, which yields the output "Japonais." All of the Locale "display" methods use this same pattern. Almost all Internationalization API methods allow you to explicitly control the Locale used for localization, but, in most cases, you'll just want to use the default Locale.

Another thing to note in the above example is the use of the static constant Locale.FRENCH. The Locale class provides a number of these useful constants, each of which is a shortcut for the corresponding Locale object. A list of these objects is shown in Table 16.3:

Table 16.3 Locale Static Objects

Constant Name	Locale	Shortcut for
CANADA	English Canada	new Locale("en", "CA", "")
CANADA_FRENCH	French Canada	new Locale("fr", "CA", "")
CHINA SCHINESE PRC	Chinese (Simplified)	new Locale("zh", "CN", "")
CHINESE	Chinese Language	new Locale("zh", "", "")
ENGLISH	English Language	new Locale("en", "", "")
FRANCE	France	new Locale("fr", "FR", "")
FRENCH	French Language	new Locale("fr", "", "")
GERMAN	German Language	new Locale("de", "", "")
GERMANY	Germany	new Locale("de", "DE", "")
ITALIAN	Italian Language	new Locale("it", "", "")
ITALY	Italy	new Locale("it", "IT", "")
JAPAN	Japan	new Locale("jp", "JP", "")
JAPANESE	Japanese Language	new Locale("jp", "", "")
KOREA	Korea	new Locale("ko", "KR", "")
KOREAN	Korean Language	new Locale("ko", "", "")
TAIWAN TCHINESE	Taiwan (Traditional Chinese)	new Locale("zh", "TW", "")
UK	Great Britain	new Locale("en", "GB", "")
US	United States	new Locale("en", "US", "")

Packaging Locale-sensitive Data

The Locale class allows you to easily handle Locale-sensitive methods. However, most programs (especially applets and GUI-based applications) require the use of Strings, data, and other resources that also need to be localized. For instance, most GUI programs have "OK" and "Cancel" buttons. This is fine for the United States, but other locales require different labels for these buttons. In Germany, for instance, you might use "Gut" and "Vernichten" instead. Traditionally, information such as this was included in the source code of an application, which, as Programmer Joe found out earlier, can lead to many problems when trying to simultaneously support many localized versions of one program. To solve this problem, Java provides a way to encapsulate this data into objects which are loaded by the VM upon demand. These objects are called ResourceBundles.

ResourceBundles--Naming conventions ResourceBundle is an abstract class that must be extended in order to provide any functionality. ResourceBundles are loaded by a class loader by name, and must follow a very strict naming convention in order to be loaded properly. This is best illustrated by example. Say you have a class called LabelBundle which extends ResourceBundle and contains the names of all GUI labels you use in an application. The class called LabelBundle provides default information, while LabelBundle_fr provides French labels, LabelBundle_ge_GE provides German labels, and LabelBundle_en_US_MAC provides Macintosh-specific American English labels. You request a ResourceBundle using the following static method:

ResourceBundle getResourceBundle(String baseName, Locale locale, ClassLoader loader)

This method uses the specified ClassLoader to search for a class that matches baseName, plus certain attributes of the specified Locale. There is a very specific search pattern that is used to find the "closest match" to the Bundle you request:

bundleName + "_" + localeLanguage + "_" + localeCountry + "_" + localeVariant 
bundleName + "_" + localeLanguage + "_" + localeCountry 
bundleName + "_" + localeLanguage           
bundleName + "_" + defaultLanguage + "_" + defaultCountry + "_" + defaultVariant 
bundleName + "_" + defaultLanguage + "_" + defaultCountry 
bundleName + "_" + defaultLanguage 
bundleName

In our example, if you request the baseName LabelBundle with a fr_FR_WIN (French language, France, Windows platform) Locale, the getResourceBundle() method will perform the following steps:

1. Search for the class LabelBundle_fr_FR_WIN, which fails because you have defined no such class.

2. Search for the class LabelBundle_fr_FR, which also fails because you did not define a France-only Bundle.

3. Search for class LabelBundle_fr. This succeeds, and returns the class with this name. However, if this search had failed (if you had not supplied a French-language Bundle), the search would have continued, using the language, country, and variant codes supplied in the default Locale.

Creating ResourceBundles Now that you understand the naming convention used with ResourceBundles, take a look at how they are created. The simplest form of ResourceBundles extends the ResourceBundle class directly, and then overrides one method:

Object handleGetObject(String key)

This method returns an Object that corresponds to the specified key. These keys are internal representations of the content stored in the ResourceBundle, and should be the same for all localized versions of the same data. An extremely simple version of your LabelBundle might be defined as follows:

class LabelBundle extends ResourceBundle {
   public Object handleGetObject(String key) {
      if( key.equals("OK") )
         return "OK";
      else if( key.equals("Cancel") )
         return "Cancel";

      // Other labels could be handled here

   return null; // If the key has no matches, always return null
   }
}

Other versions of the same bundle might return values translated into different languages. You can see, however, that this method of handling key-value pairs is very inefficient if you have more than a few keys. Luckily, Java provides two subclasses of ResourceBundle which can make life easier: ListResourceBundle and PropertyResourceBundle.

ListResourceBundles use an array of two-element arrays to store the key-value pairs used above. All you have to do is override the default getContents() method, like this:

class LabelBundle extends ListResourceBundle {
   static final Object[][] labels = {
      {"OK", "OK"},
      {"Cancel", "Cancel"},
      ("AnotherKey", "Another Value"}
      //More key-value pairs can go here
   };

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

You could also provide your own similar functionality using a Hashtable, but that's only worthwhile if you want the contents to change dynamically over time.

PropertyResourceBundles are created as needed from predefined "property" files stored on disk. These are usually used for system-wide settings, or when large amounts of data need to be stored in a key-value pair. PropertyResourceBundles are built from files with the same name as the corresponding class file, but with the .properties extension instead. To implement the LabelBundle_de_DE class, you might provide a file called LabelBundle_de_DE.properties with the following content:

OK=Gut
Cancel=Vernichten
AnotherKey=This value has a lot of text stored within it. Of course, it really ought to be translated into German first...

Contents are always specified in the form "key=value" and are assumed to be Strings (although they can be cast into other appropriate objects). This functionality is based on the java.util.Properties class. See Chapter 33 for more information on the java.util package.

NOTE: Although the examples given here all deal with String objects, ResourceBundles can store Objects of any type, including Dates, Applets, GUI elements, or even other ResourceBundles!

String str = "This is a line of text. It contains many words, sentences, and formatting."
TextBoundary byWord = TextBoundary.getWordBreak();
int from, to;
from = byWord.first();
while( (to = byWord.next()) != DONE ) {
   System.out.println( byWord.getText().substring(from, to) );
   from = to;
}

ClassLoader loader = this.getClass().getClassLoader();

import java.util.*;
import java.lang.*;
import java.text.DateFormat;

class InternationalTest extends Object {

public static void main(String args[]) {String lang = "", country = "", var = "";

   try {
      lang = args[0];
      country = args[1];
      var = args[2];
   } catch(ArrayIndexOutOfBoundsException e) {
      if( lang.equals("") ) {
         System.out.println("You must specify at least one parameter");
         System.exit(1);
         }
   }

   Locale locale = new Locale(lang, country, var);
   Locale def = Locale.getDefault();

   System.out.println( "Default Locale is: "+ def.getDisplayName() );
   System.out.println("You have selected Locale: "+locale.getDisplayName() );
   System.out.println("Default language, localized for your locale is: " +
            def.getDisplayLanguage( locale ) );
   System.out.println("Default country name, localized: " +                          locale ) );

   ClassLoader loader = null;

   ResourceBundle bundle = null;
   try {
      bundle = ResourceBundle.getResourceBundle( "TestBundle", locale, loader );
   } catch( MissingResourceException e) {
      System.out.println( "No resources available for that locale." );
   } finally {
         System.out.println( "Resources available are: ");
         System.out.println(" r1: " + bundle.getString("r1") );
         System.out.println(" r2:" + bundle.getString("r2") );
   }

   DateFormat myFormat = DateFormat.getDateTimeFormat(DateFormat.FULL, DateFormat.FULL, locale);
   Calendar myCalendar = Calendar.getDefault( locale );
   System.out.println("The localized date and time is: " + 
            myFormat.format( myCalendar.getTime() ) );

   }
}