A Guide to the ResourceBundle

1. Overview

Many software developers encounter opportunities throughout their careers to develop multilingual systems or applications. These are usually destined for end-users from different regions or different language areas. This allows users to interact with the application in their preferred language or format.

Maintaining and extending these applications is always challenging. Modifying the application data should be as simple as possible, without requiring compilation. This is why we generally avoid hardcoding labels or button names.

ResourceBundle class is the most effective tool for managing localization in Java. In this tutorial, we’ll explore how the ResourceBundle works, its usage, and provide examples to show the functionality.

2. ResourceBundles

The ResourceBundle enables our application to load data from distinct files containing locale-specific data.

We should first know 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 an underscore symbol.

It’s important to append a country code if there’s already a language code, or a 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.

2.1. 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 are 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 !.

2.2. Java Files – ListResourceBundle

First, 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 a 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 the 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.

3. Using Resource Bundles

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

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 that only requires a bundle name if the default locale is fine. When 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 the values we want.

4. 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 that needs labels in Polish but your default JVM locale is Locale.US.

In the beginning, the application will look for files in the classpath suitable for the locale you ask for. It starts with the most specific name, which contains a platform, a country, and a 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.

5. Inheritance

Another advantage of the resource bundle concept is property inheritance. It means that key-value pairs included in less specific files are inherited by those that 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 mentioning, that there’s no fallback to the default locale bundle as far as property inheritance is considered.

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

5.1. Handling Key-Value Inheritance Across Property Files and Java Files

When a Java application looks for resource bundles (such as property files), it’ll only inherit key-value pairs from property files that it finds. This inheritance doesn’t extend to other types of resource bundles, such as ListResourceBundles.

In other words, Property inheritance works only between property files, but inheritance doesn’t occur from other types of resources like ListResourceBundle. Similarly, if Java files serve as resource bundles, they’ll follow the same inheritance rules.

Let’s consider the messages.properties file in our classpath:

greeting=Hello
farewell=Goodbye

And the messages_en.properties:

greeting=Hi
farewell=See you later

Now, we’ll create a CustomListResourceBundle and try to inherit from the property files :

public class CustomListResourceBundle extends ListResourceBundle {
    @Override
    protected Object[][] getContents() {
        return new Object[][] {
            { "customMessage", "This is a custom message." }
        };
    }
}

Let’s look at the test below, which shows when we try to load the CustomListResourceBundle, the properties from the PropertyResourceBundle are not inherited:

@Test
public void givenListResourceBundle_whenUsingInheritance_thenItShouldNotInherit() {
    ResourceBundle listBundle = ResourceBundle.getBundle("com.baeldung.resourcebundle.CustomListResourceBundle", Locale.ENGLISH);

    assertEquals("This is a custom message.", listBundle.getString("customMessage"));

    assertThrows(MissingResourceException.class, () -> listBundle.getString("greeting"));
}

The above test verifies that the ListResourceBundle doesn’t support inheritance from other resource bundle types. It throws a MissingResourceException when attempting to access keys that don’t exist in it.

6. 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 the 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 the 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.

7. UTF-8

For applications using JDK 8 or older versions, it’s worth knowing that before Java 9 ListResourceBundles had one more advantage over PropertyResourceBundles. As Java files can store String objects, they can 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).

To save characters that 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 is no longer in Java 9. JVM reads property files in UTF-8 encoding, and there’s no problem with using non-Latin characters.

8. Conclusion

In this article, we explored the ResourceBundle and how we can use it to create a multilingual application. BundleResource contains much of what we need to develop a multilingual application. The features we’ve covered simplify the manipulation of different locales.

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.