Locating Locale-Specific Resources – Localization

Locating Locale-Specific Resources

A broad outline of the steps is given below to locate and create the resource bundle (and its parent bundles) returned by the getBundle() static method of the abstract class java.util.ResourceBundle for a specific locale. For the nitty-gritty details of locating resource bundles, we recommend consulting the Java SE API documentation for the java.util.ResourceBundle class.

Exactly which resource bundle (and its parent bundles) will be returned by the getBundle() static method depends on the following factors:

• The resource bundles included in the resource bundle family specified by its fully qualified base name in the call to the getBundle() method
• The specified locale in the call to the getBundle() method
• The current default locale of the application

For the explanation given below, assume that the default local is “en_US” and the following resource files (from Example 18.2) in the resource bundle family with the base name BasicResources reside in a directory named resources:

Click here to view code image

BasicResources.properties
BasicResources_no_NO.properties
BasicResources_fr.properties

Also assume the following call is made to the getBundle() method to retrieve the resource bundle (and its parent resource bundles) for the baseName bundle family and the specified locale:

Click here to view code image

ResourceBundle resources = ResourceBundle.getBundle(baseName, specifiedLocale);

Step 1: Create a list of candidate bundle names based on the specified locale.

The getBundle() method first generates a list of candidate bundle names by appending the attributes of the locale argument (specified language code, specified country code) to the base name of the resource bundle family that is passed as an argument. Typically, this list would have the following candidate bundle names, where the order in which the names are generated is important in locating resources:

Click here to view code image

baseName_specifiedLanguageCode_specifiedCountryCode
baseName_specifiedLanguageCode

For example, if the base name is BasicResources and the locale that is passed as an argument is “fr_CA” in the call to the getBundle() method, the list of candidate bundle names generated would be as follows:

BasicResources_fr_CA
BasicResources_fr

Note that more specific bundles are higher in this list, and more general ones are lower in the list. The bundle BasicResources_fr_CA is more specific than the bundle BasicResources_fr, as the former is only for France (French), whereas the latter is for all French-speaking countries.

A candidate bundle name in this list is a parent resource bundle for the one above it.

Step 2: Find the result bundle that can be instantiated in the candidate bundle list.

The getBundle() method then iterates over the list of candidate bundle names from the beginning of the list to find the first one (called the result bundle) for which it can instantiate an actual resource bundle.

Finding the result bundle depends on whether it is possible to instantiate a resource bundle class or load the contents of a property resource file into an instance of the PropertyResourceBundle class, where the resource bundle class or the property resource file has the same name as the candidate bundle name.

In our example regarding the “fr_CA” locale, the candidate resource name BasicResources_fr_CA in the list of candidate resource names does not qualify as a result resource bundle because it cannot be created based on any resource bundles in the resource bundle family BasicResources. Only the candidate resource name BasicResources_fr can be created and is the result resource bundle, as there is a resource bundle named BasicResources_fr.properties in the resource bundle family.

Once a result resource bundle has been found, its parent chain is constructed and returned (p. 1109). In our example with the “fr_CA” locale, the parent chain for the result source bundle named BasicResources_fr.properties is created and returned.

Step 3: If no result resource bundle is found in Step 2, the search for a result bundle is conducted with the default locale.

It is possible that no result resource bundle is found in the previous step. Only in that case is the search for a result resource bundle repeated with the current default locale (default language code, default country code). A new list of candidate bundle names is generated, which will typically include the following names, and is instantiated to find a result bundle name:

Click here to view code image

baseName_defaultLanguageCode_defaultCountryCode
baseName_defaultLanguageCode

In our example, this second step is not performed since a result resource bundle (BasicResources_fr) was found in the previous step.

Once a result resource bundle using the default locale has been found, its parent chain is constructed and returned (p. 1109).

Step 4: If no result resource bundle is found in Step 3 using the current default locale either, an attempt is made to instantiate the default resource bundle designated by baseName.

If successful, this instantiation of the default resource bundle is returned by the getBundle(baseName, specifiedLocale) method.

In our example, this step with the bundle name BasicResources is not performed since a result resource bundle (BasicResources_fr) was already found.

Step 5: If the steps above do not yield a result resource bundle, an unchecked java.util.MissingResourceException is thrown.

In our example, no exception is thrown since a result resource bundle (BasicResources_fr) was found in Step 2.