1. Overview

1.概述

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.

幸运的是，我们可以依靠Java为我们提供的这个类，它可以帮助我们解决上面提到的所有问题。

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

简单地说，ResourceBundle使我们的应用程序能够从包含本地特定数据的不同文件中加载数据。

1.1. ResourceBundles

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的子类。PropertyResourceBundle和ListResourceBundle，我们可以在属性文件和java文件中互换地保存数据。

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

每个文件都必须有当地特定的名称和适当的文件扩展名，例如，ExampleResource_en_US.properties或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.

属性文件由PropertyResourceBundle表示。它们以区分大小写的键值对形式存储数据。

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

所有这些都是等价的，但第一个可能是在Java程序员中最流行的。值得一提的是，我们也可以在属性文件中加入注释。注释总是以#或！开始。

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.

首先，为了存储我们特定的语言数据，我们需要创建一个扩展ListResourceBundle并重写getContents()方法的类。类的名称约定与属性文件相同。

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

对于每个Locale,我们需要创建单独的Java类。

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.

与属性文件相比，Java文件有一个主要的优势，那就是可以容纳任何我们想要的对象–不仅仅是字符串。

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.

另一方面，每次修改或引入一个新的特定于本地的java类都需要重新编译应用程序，而属性文件可以在不需要任何额外努力的情况下进行扩展。

2. Use Resource Bundles

2.使用资源包

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.

首先，我们可以定义我们的Locale，除非我们不想使用默认的。

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.

之后，让我们调用ResourceBundle的一个静态工厂方法。我们需要将捆绑包名称及其包/目录和locale作为参数传递。

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.

还有一个工厂方法，如果默认的locale没有问题，它只需要一个bundle名称。一旦我们有了这个对象，我们就可以通过它们的键来检索值了。

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

3.选择适当的捆绑资源

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

如果我们想使用捆绑资源，那么了解Java如何选择捆绑文件就很重要。

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

让我们想象一下，我们工作的应用程序需要波兰语的标签，但你的默认JVM区域设置是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.

开始时，应用程序将在classpath中寻找适合你要求的locale的文件。它从最具体的名称开始，即包含一个平台、一个国家和语言的名称。

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.

我们应该记住，每个名字都代表.java和.properties文件，但前者优先于后者。当没有合适的文件时，会抛出一个MissingResourceException。

4. Inheritance

4.继承

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.

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

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

更重要的是，ListResourceBundles和PropertyResourceBundles不在同一个层次结构中。

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.

因此，如果在classpath中找到一个属性文件，那么键值对就只能从属性文件中继承。这条规则也适用于Java文件。

5. Customization

5.定制

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

我们在上面学到的都是关于ResourceBundle的默认实现。然而，我们有一个方法可以修改它的行为。。

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

我们通过扩展ResourceBoundle.Control并重写其方法来做到这一点。

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.

这个方法的目的是改变一种在classpath中选择文件的方式。我们可以看到，ExampleControl将只返回抛光的Locale，不管默认或定义的Locale是什么。

6. UTF-8

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之前，ListResourceBundles比PropertyResourceBundles还有一个优点。由于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:

让我们看看改变编码之前和之后的属性如何。

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

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

7. Conclusion

7.结论

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

BundleResource包含了我们开发一个多语言应用程序所需的大部分内容。我们所涉及的功能使得对不同地区的操作变得非常简单。

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.

我们还避免了硬编码值，允许我们通过简单地添加新的Locale文件来扩展支持的Locale，使我们的应用程序能够顺利地被修改和维护。

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

一如既往，样本代码可在GitHub上找到。