Chapter 12 ■ Localization

The getDefault() method in Locale returns the default locale object set in the JVM. The next statement uses methods to get information related to the country. The difference between the getCountry() and

getDisplayCountry() methods is that the former method returns the country code (which is not very readable for us), and the latter returns the country name, which is human readable. The country code is a two or three letter code (this code comes from an international standard: ISO 3166).

The behavior of getLanguage() and getDisplayLanguage() is similar to getting country details. The language code consists of two or three letters, and this code comes from another international standard (ISO 639).

There was no variant in this locale, so nothing got printed when you used the getVariant() and getDisplayVariant() methods. However, for some other locale, there could be variant values, and those values would get printed for that locale. The variant could be any extra details such as operating environments (like MAC for Macintosh machine) or name of the company (such as Sun or Oracle).

Other than these, you also have less widely used methods such as getScript(), which returns the script code for the locale.

Resource Bundles

In the last section, we discussed the Locale class and the way to get details of the default locale and the list of available locales. How do you use this locale information to customize the behavior of your programs? Let’s take a simple example of greeting someone: in English, you say “Hello,” but if the locale is different, how do you change this greeting to say, for example, “Ciao” if the locale is Italy (and Italian)?

One obvious solution is to get the default locale, check if the locale is Italy and print “Ciao.” It will work, but this approach is neither flexible nor extensible. How about customizing to other locales like Saudi Arabia (Arabic) or India (Hindi)? You have to find and replace all the locale specific strings for customizing for each locale; this task will be a nightmare if your application consists of thousands of such strings spread over a million lines of code.

In Java, resource bundles provide a solution to this problem of how to customize the application to locale-specific needs. So, what is a resource bundle? A resource bundle is a set of classes or property files that help define a set of keys and map those keys to locale specific values.

The abstract class ResourceBundle provides an abstraction of resource bundles in Java. It has two derived classes: PropertyResourceBundle and ListResourceBundle (see Figure 12-1). The two derived classes provide support for resource bundles using two different mechanisms:

(abstract class)

Figure 12-1.  ResourceBundle and its two derived classes

366

Chapter 12 ■ Localization

•The PropertyResourceBundle Class: This concrete class provides support for multiple locales in the form of property files. For each locale, you specify the keys and values in a property file for that locale. For a given locale, if you use the ResourceBundle.getBundle() method, the relevant property file will be automatically loaded. Of course, there is no magic in it; you have to follow certain naming conventions for creating the property files, which we’ll discuss in the section dedicated to discussing property files. You can use only Strings as keys and values when you use property files.

•The ListResourceBundle Class: For adding support to a locale, you can extend this abstract class. In your derived class, you have to override the getContents() method, which returns an Object [][]. This array must have the list of keys and values. The keys must be Strings. Typically the values are also Strings, but values can be anything: sound clips, video clips, URLs, or pictures.

Let’s take a quick look at the methods supported by the ResourceBundle abstract class. Table 12-2 summarizes the important methods of this class. We’ll now discuss localization support using these two derived classes of

ResourceBundle.

Table 12-2.  Important Methods in the ResourceBundle Abstract Class

Using PropertyResourceBundle

If you design your application with localization in mind using property files, you can add support for new locales to the application without changing anything in the code!

We’ll now look at an example using resource files and it will become clear to you. Let’s start with a very simple program that prints “Hello” to the user. This program has three property file resource bundles:

1.The default resource bundle that assumes the English (US) locale.

2.A resource bundle for the Arabic locale.

3.A resource bundle for the Italian locale.

367

Chapter 12 ■ Localization

As discussed above, property files define strings as key value pairs in a file. Here is an example of a classpath that can be mapped to an actual path in your machine: classpath = C:\Program Files\Java\jre7. Property files will usually contain numerous such key value pairs, with each such pair in separate lines, as in the following:

classpath = C:\Program Files\Java\jre7 temp = C:\Windows\Temp

windir = C:\Windows

In the case of localization, you use property files to map the same key strings to different value strings. In the program, you’ll refer the key strings, and by loading the matching property file for the locale, the corresponding values for the keys will be fetched from the property files for use in the program.

The naming of these property files is important (you’ll see why soon) and below is the content of these bundles. To keep this example simple, there is only one key-value pair in these property files; in real-world programs, there could be a few hundred or even thousands of pairs present in each property file.

D:\ > type ResourceBundle.properties Greeting = Hello

D:\ > type ResourceBundle_ar.properties Greeting = As-Salamu Alaykum

D:\ > type ResourceBundle_it.properties Greeting = Ciao

As you can see, the default bundle is named ResourceBundle.properties. The resource bundle for Arabic is named ResourceBundle_ar.properties. Note the suffix _ar, indicating Arabic as a local language. Similarly, the resource bundle for Italian is named ResourceBundle_it.properties, which makes use of the _it suffix to indicate the Italian as the associated language with this property file. Listing 12-3 makes use of these resource bundles.

Listing 12-3.  LocalizedHello.java

import java.util.*;

public class LocalizedHello {

public static void main(String args[]) {

Locale currentLocale = Locale.getDefault(); ResourceBundle resBundle =

ResourceBundle.getBundle("ResourceBundle", currentLocale); System.out.printf(resBundle.getString("Greeting"));

}

}

There are two options to run this program in the desired way:

•Option I: Change the default locale in the program by calling the setDefault() method:

Locale.setDefault(Locale.ITALY);

368

Chapter 12 ■ Localization

This option is not recommended since it will require changing the program to set the locale.

•Option II: Change the default locale when invoking the JVM from the command line

(if you’re invoking the JVM from an IDE, provide the command line arguments to the JVM in the IDE settings):

D:\ > java -Duser.language = it -Duser.region = IT LocalizedHello

Let’s try the program by setting the locale with Option II (passing arguments to the command line when invoking the JVM).

D:\ > java LocalizedHello Hello

D:\ > java -Duser.language=it LocalizedHello Ciao

D:\ > java -Duser.language=ar LocalizedHello As-Salamu Alaykum

As you can see, depending on the locale that you explicitly set (Italian or Arabic in this example), or the default locale (US English in this example), the corresponding property file is loaded and the message string is resolved.

 If you forget to create property files or they are not in the path, you will get a

MissingResourceException.

In the program, first you get the current locale in the statement.

Locale currentLocale = Locale.getDefault();

After that, you load the resource bundle that starts with the name ResourceBundle and pass the locale for loading the resource bundle.

ResourceBundle resBundle = ResourceBundle.getBundle("ResourceBundle", currentLocale);

Finally, from the resource bundle, you look for the key “Greeting” and use the value of that key based on the loaded resource bundle.

System.out.printf(resBundle.getString("Greeting"));

Using ListResourceBundle

Support for a new locale can be added using ListResourceBundle by extending it. While extending the ListResourceBundle, you need to override the abstract method getContents(); the signature of this method is

protected Object[][] getContents();

369

Chapter 12 ■ LoCaLization

Note that the keys are Strings, but values can be of any type, hence the array type is Object; further,

the method returns a list of key and value pairs. As a result, the getContents() method returns a two-dimensional array of Objects.

Listing 12-4 shows an example of extending the ListResourceBundle, which is supposed to return the largest box-office movie hit for that particular locale. It defines a resource bundle named ResBundle. Since the name of the class does not have any suffix (such as _it or _en_US), it is the default implementation of the resource bundle. When looking for a matching ResBundle for any locale, this default implementation will be used in case no match is found.

Listing 12-4. ResBundle.java

import java.util.*;

// default US English version

public class ResBundle extends ListResourceBundle { public Object[][] getContents() {

return contents;

}

static final Object[][] contents = {

{"MovieName", "Avatar" },

{"GrossRevenue", (Long) 2782275172L }, // in US dollars

{"Year", (Integer)2009 }

};

}

Now, let’s define a ResBundle for the Italian locale. You give the class the suffix _it_IT. The language code it stands for Italian and the country code IT stands for Italy. See Listing 12-5.

Listing 12-5. ResBundle_it_IT.java

import java.util.*;

// Italian version

public class ResBundle_it_IT extends ListResourceBundle { public Object[][] getContents() {

return contents;

}

static final Object[][] contents = {

{"MovieName", "Che Bella Giornata" },

{"GrossRevenue", (Long) 43000000L }, // in euros

{"Year", (Integer)2011 }

};

}

As you can see, the implementations for ResBundle and ResBundle_it_IT are similar except for the values mapped to the keys. Now how do you know if your resource bundles are working or not? Listing 12-6 loads ResBundle for both default and Italian locales.

370

Chapter 12 ■ Localization

Listing 12-6.  LocalizedHello2.java

import java.util.*;

public class LocalizedHello2 {

public static void printMovieDetails(ResourceBundle resBundle) { String movieName = resBundle.getString("MovieName");

Long revenue = (Long)(resBundle.getObject("GrossRevenue")); Integer year = (Integer) resBundle.getObject("Year");

System.out.println("Movie " + movieName + "(" + year ")" + " grossed " + revenue );

}

public static void main(String args[]) {

//print the largest box-office hit movie for default (US) locale Locale locale = Locale.getDefault(); printMovieDetails(ResourceBundle.getBundle("ResBundle", locale));

//print the largest box-office hit movie for Italian locale locale = new Locale("it", "IT", ""); printMovieDetails(ResourceBundle.getBundle("ResBundle", locale));

}

}

It prints the following:

Movie Avatar (2009) grossed 2782275172

Movie Che Bella Giornata (2011) grossed 43000000

It loaded the default and Italian resource bundles successfully. However, there are problems with this output. The value 2782275172 is a US dollar value and the value 43000000 is in Euros. Moreover, the numbers are printed without commas, so it is difficult to make sense of these figures. These values need to be localized as well, and we’ll revisit this topic in the last section of this chapter.

Now, consider the following statement from this program:

Long revenue = (Long)(resBundle.getObject("GrossRevenue"));

This statement returns the value mapping to the key named GrossRevenue in the resource bundle. You have defined it as an integer object in the classes ResBundle and ResBundle_it_IT—so it worked. If you cast the types incorrectly, you’ll get a ClassCastException.

Furthermore, note that the keyname is case sensitive and the key name should exactly match—or else you’ll get a

MissingResourceException. For example, in this statement, if you mistype GrossRevenu instead of GrossRevenue as the key name, the program will crash with this exception:

The Exception in the thread "main" java.util.MissingResourceException: Can't find resources for bundle ResBundle, key GrossRevenu

371