A Guide to the ResourceBundle

1. Overview

Many software developers, during their professional careers, face an opportunity to develop multilingual systems or applications. These’re usually destined for end-users from different regions or different language areas.

It’s always challenging to maintain and extend these applications. An ability to operate with various localization specific data at the same time is usually crucial. Modification of the application data should be as simple as possible with no need for recompilation. That’s why we generally avoid hardcoding label or button names.

Luckily, we can bank on Java that provides us with this class, which helps us to solve all the problems mentioned above.

Simply put, the ResourceBundle enables our application to load data from distinct files containing locale-specific data.

1.1. ResourceBundles

The first thing we should know is that all files within one resource bundle must be in the same package/directory and have a common base name. They may have locale-specific suffixes indicating language, country, or platform separated by underscore symbol.

It’s important that we may append country code if there’s already language code, or platform if language and country codes are present.

Let’s look at example file names:

• ExampleResource
• ExampleResource_en
• ExampleResource_en_US
• ExampleResource_en_US_UNIX

The default file for each data bundle is always one without any suffixes – ExampleResource. As there are two subclasses of ResourceBundle: PropertyResourceBundle and ListResourceBundle, we can interchangeably keep data in property files as well as java files.

Each file must have a locale-specific name and a proper file extension, for example, ExampleResource_en_US.properties or Example_en.java.

1.2. Property Files – PropertyResourceBundle

Property files are represented by PropertyResourceBundle. They store data in the form of case sensitive key-value pairs.

Let’s analyze a sample property file:

# Buttons
continueButton continue
cancelButton=cancel

! Labels
helloLabel:hello

As we can see, there’re three different styles of defining key-value pairs.

All of them are equivalent, but the first one is probably the most popular among Java programmers. It’s worth to know that we can put comments in property files as well. Comments always start with # or !.

1.3. Java Files – ListResourceBundle

First of all, in order to store our language-specific data, we need to create a class that extends ListResourceBundle and overrides the getContents() method. The class name convention is the same as for property files.

For each Locale, we need to create separate Java class.

Here is a sample class:

public class ExampleResource_pl_PL extends ListResourceBundle {

    @Override
    protected Object[][] getContents() {
        return new Object[][] {
          {"currency", "polish zloty"},
          {"toUsdRate", new BigDecimal("3.401")},
          {"cities", new String[] { "Warsaw", "Cracow" }} 
        };
    }
}

Java files have one major advantage over property files which is a possibility of holding any object we want – not only Strings.

On the other hand, each modification or introduction of a new locale-specific java class requires recompilation of an application whereas property files can be extended without any additional effort.

2. Use Resource Bundles

We already know how to define resource bundles, so we’re ready to use it.

Let’s consider the short code snippet:

Locale locale = new Locale("pl", "PL");
ResourceBundle exampleBundle = ResourceBundle.getBundle("package.ExampleResource", locale);

assertEquals(exampleBundle.getString("currency"), "polish zloty");
assertEquals(exampleBundle.getObject("toUsdRate"), new BigDecimal("3.401")); 
assertArrayEquals(exampleBundle.getStringArray("cities"), new String[]{"Warsaw", "Cracow"});

Firstly, we can define our Locale, unless we don’t want to use the default one.

After that, let’s call a static factory method of ResourceBundle. We need to pass the bundle name with its package/directory and the locale as parameters.

There’s also a factory method which only requires a bundle name if the default locale is fine. As soon as we have the object, we can retrieve values by their keys.

Additionally, the example shows that we can use getString(String key), getObject(String key), and getStringArray(String key) to get values we want.

3. Selecting the Proper Bundle Resource

If we want to use a bundle resource, it’s important to know how Java selects bundle files.

Let’s imagine that we work with an application which needs labels in Polish but your default JVM locale is Locale.US.

In the beginning, the application will look for the files in the classpath suitable for the locale you ask for. It starts with the most specific name, that is, one containing a platform, a country, and language.

Then, it goes to more general. If there is no match, it falls back to the default locale with no platform check this time.

In case of no match, it will try to read the default bundle. Everything should be clear when we look at the order of selected file names:

• Label_pl_PL_UNIX
• Label_pl_PL
• Label_pl
• Label_en_US
• Label_en
• Label

We should keep in mind that each name represents both .java and .properties files, but the former takes precedence over the latter. When there’s no suitable file, a MissingResourceException is thrown.

4. Inheritance

Another advantage of the resource bundle concept is property inheritance. It means that key-values pairs included in less specific files are inherited by those which are higher in the inheritance tree.

Let’s assume that we have three property files:

#resource.properties
cancelButton = cancel

#resource_pl.properties
continueButton = dalej

#resource_pl_PL.properties
backButton = cofnij

Resource bundle retrieved for Locale(“pl”, “PL”) would return all three keys/values in the result. It’s worth to mention, there’s no fall back to default locale bundle as far as property inheritance is considered.

What is more, ListResourceBundles and PropertyResourceBundles aren’t in the same hierarchy.

So if a property file is found in the classpath then key-value pairs are inherited only from property files. The same rule applies to Java files.

5. Customization

All we’ve learned above was about the default implementation of ResourceBundle. However, there’s a way we can modify its behavior.

We do this by extending ResourceBoundle.Control and overriding its methods.

For example, we can change the time of keeping values in cache or determine the condition when the cache should be reloaded.

For a better understanding, let’s prepare a short method as an example:

public class ExampleControl extends ResourceBundle.Control {

    @Override
    public List<Locale> getCandidateLocales(String s, Locale locale) {
        return Arrays.asList(new Locale("pl", "PL"));
    }
}

The purpose of this method is to change a manner of selecting files in the classpath. As we can see, ExampleControl will return only polish Locale, no matter what the default or defined Locale is.

6. UTF-8

Since there’re still many applications using JDK 8 or older versions, it’s worth to know that prior to Java 9 ListResourceBundles had one more advantage over PropertyResourceBundles. As Java files can store String objects, they are able to hold any character supported by UTF-16 encoding.

On the contrary, PropertyResourceBundle loads files by default using ISO 8859-1 encoding, which has fewer characters than UTF-8 (causing problems for our Polish language examples).

In order to save characters which are beyond UTF-8, we can use the Native-To-ASCII converter – native2ascii. It converts all characters that aren’t compliant with ISO 8859-1 by encoding them to \uxxxx notation.

Here’s an example command:

native2ascii -encoding UTF-8 utf8.properties nonUtf8.properties

And let’s see how properties look like before and after a change of encoding:

#Before
polishHello=cześć

#After
polishHello=cze\u015b\u0107

Fortunately, this inconvenience exists no longer in Java 9. JVM reads property files in UTF-8 encoding, and there’s no problem in using non-Latin characters.

7. Conclusion

BundleResource contains much of what we need to develop a multilingual application. The features we’ve covered make manipulation of different locales pretty straightforward.

We also avoid hardcoding values, allowing us to expand the supported Locales by simply adding new Locale files allowing our application to be smoothly modified and maintained.

As always, the sample code is available in over on GitHub.