A Guide to the ResourceBundle – ResourceBundle指南

最后修改: 2018年 3月 11日

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.

每个数据包的默认文件总是一个没有任何后缀的文件 – ExampleResource。因为有两个ResourceBundle的子类。PropertyResourceBundleListResourceBundle,我们可以在属性文件和java文件中互换地保存数据。

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

1.2.属性文件 – 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

! Labels

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

1.3. Java文件 – 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 {

    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.

此外,这个例子显示,我们可以使用getString(String key)getObject(String key)getStringArray(String key)来获得我们想要的值。

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:


cancelButton = cancel

continueButton = dalej

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.

Locale(“pl”, “PL”)检索的资源包将在结果中返回所有三个键/值。值得一提的是,就属性继承而言,没有回退到默认的locale bundle

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 {

    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.

由于仍有许多应用程序在使用JDK 8或更早的版本,值得知道的是,Java 9之前,ListResourceBundlesPropertyResourceBundles还有一个优点。由于Java文件可以存储字符串对象,它们能够容纳UTF-16编码所支持的任何字符。

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).

相反,PropertyResourceBundle默认使用ISO 8859-1编码加载文件,该编码的字符数比UTF-8少(给我们的波兰语例子带来问题)。

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.

为了保存超出UTF-8的字符,我们可以使用Native-To-ASCII转换器 – native2ascii。它通过将所有不符合ISO 8859-1的字符编码为native/uxxxx符号来进行转换。

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:




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.

幸运的是,这种不便在Java 9中不再存在。JVMUTF-8编码读取属性文件,而且使用非拉丁字符也没有问题。

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.