Isolating Locale-Specific Data

Backing a ResourceBundle with Properties Files

This section steps through a sample program named PropertiesDemo. The source code for the program is in PropertiesDemo.java.

1. Create the Default Properties File

A properties file is a simple text file. You can create and maintain a properties file with just about any text editor.

You should always create a default properties file. The name of this file begins with the base name of your ResourceBundle and ends with the .properties suffix. In the PropertiesDemo progam, the base name is LabelsBundle. Therefore, the default properties file is called LabelsBundle.properties. This file contains the following lines:

# This is the default LabelsBundle.properties file
s1 = computer
s2 = disk
s3 = monitor
s4 = keyboard

In the preceding file, note that comment lines begin with a pound sign (#). The other lines contain key-value pairs. The key is on the left side of the equal sign and the value is on the right. For instance, "s2" is the key that corresponds to the value "disk." The key is arbitrary. We could have called "s2" something else, like "msg5" or "diskID." However, once defined, the key should not change because it is referenced in the source code. The values may be changed. In fact, when your localizers create new properties files to accomodate additional languages, they will translate the values into different languages.

2. Create Additional Properties Files as Needed

To support an addtional Locale, your localizers will create a new properties file that contains the translated values. No changes to your source code are required, because your program references the keys, not the values.

For example, to add support for the German language, your localizers would translate the values in LabelsBundle.properties and place them in a file named LabelsBundle_de_DE.properties. Notice that the name of this file, like that of the default file, begins with the base name LabelsBundle and ends with the .properties suffix. However, since this file is intended for a specific Locale, the base name is followed by the language code (de) and the country code (DE). The contents of LabelsBundle_de_DE.properties is as follows:

# This is the LabelsBundle_de_DE.properties file
s1 = Computer
s2 = Platte
s3 = Monitor
s4 = Tastatur

The PropertiesDemo sample program ships with hree properties files:

LabelsBundle.properties
LabelsBundle_de_DE.properties
LabelsBundle_fr.properties

3. Specify the Locale

The PropertiesDemo program creates the Locale objects as follows:

Locale[] supportedLocales = {
    new Locale("fr","FR"),
    new Locale("de","DE"),
    new Locale("en","US")

Locale currentLocale = new Locale("fr","FR");

The calls to each of the Locale constructors specify a language code and a country code. These codes match the properties files created in the previous two steps. For example, the Locale created with the de and DE codes correspond to the LabelsBundle_de_DE.properties file.

4. Create the ResourceBundle

This is the step that shows how the Locale, the properties files, and the ResourceBundle are related. To create the ResourceBundle, invoke the getBundle method, specifying the base name and Locale:

ResourceBundle labels =
   ResourceBundle.getBundle("LabelsBundle",currentLocale);

The getBundle method first looks for a class file that matches the base name. If it can't find a class file, it then checks for properties files. In the PropertiesDemo program, we're backing the ResourceBundle with properties files instead of class files. When the getBundle method locates the correct properties file, it returns a PropertyResourceBundle object loaded with the key-value pairs from the properties file.

If a properties file for the specified Locale does not exist, getBundle selects a properties file that is the closest match. The following table identifies the properties file that the PropertiesDemo program selects for each Locale:

Locale Parameters	Properties File Loaded	Explanation
de DE	LabelsBundle_de_DE.properties	Exact match.
fr FR	LabelsBundle_fr.properties	LabelsBundle_fr_FR.properties does not exist so this is the closest match.
en US	LabelsBundle.properties	The default file is selected because the Locale parameters do not match.

Instead of invoking getBundle, you could have created the PropertyResourceBundle object by invoking its constructor, which accepts an InputStream as an argument. To create the InputStream you must to specify the exact name of the properties file by calling the FileInputStream constructor. Creating a PropertyResourceBundle by invoking getBundle is more flexible, because getBundle will search for the properties file that most closely matches specfied Locale.

5. Fetch the Localized Text

To retrieve the translated value from the ResourceBundle, invoke the getString method:

String value  = labels.getString(key);

The String returned by getString corresponds to the key specified. The String is in the proper language, provided that a properties file exists for the specified Locale. Since the keys do not change, the localizers add additional properties files at a later time. The call to getString need not change.

6. Iterate Through All the Keys

If you want to fetch values for all of the keys in a ResourceBundle, you need to invoke getKeys. This method returns an Enumeration of all the keys in a ResourceBundle. You can iterate through the Enumeration and fetch each value with the getString method. The following lines code, which are from the PropertiesDemo program, show how this is done:

ResourceBundle labels =
   ResourceBundle.getBundle("LabelsBundle",currentLocale);

Enumeration bundleKeys = labels.getKeys();

while (bundleKeys.hasMoreElements()) {
   String key = (String)bundleKeys.nextElement();
   String value  = labels.getString(key);
   System.out.println("key = " + key + ", " +
     "value = " + value);
}

7. Run the Demo Program

Running the PropertiesDemo program generates the following output. The first group of lines show the values returned by getString for different Locale objects. The program displays the last four lines when iterating through the keys with the getKeys method.

Locale = fr_FR, key = s2, value = Disque dur
Locale = de_DE, key = s2, value = Platte
Locale = en_US, key = s2, value = disk

key = s4, value = Clavier
key = s3, value = Moniteur
key = s2, value = Disque dur
key = s1, value = Ordinateur

Isolating Locale-Specific Data