13.3. ResourceBundles and MessageCatalogs

ResourceBundles [1] are Java classes for grouping localizable resources. The class also provides methods for finding the appropriate ResourceBundle based on a Locale and for retrieving resources from it by performing a lookup based on a key.

A ResourceBundle has a base name and optionally an associated Locale. A base name is a namespace used to group resources. A ResourceBundle without an associated Locale is the default ResourceBundle for that base name. If a ResourceBundle for a particular Locale hierarchy is not found, the ResourceBundle with no associated Locale is used. These are used to store resources that are common across all Locale instances.

The Locale hierarchy is simply the mechanism that is used to fall back from very specific Locales to more generic ones. For example, from en_US_WIN95, the hierarchy falls back to en_US and then to en and finally to the empty Locale.

Typically, one base name is used per application. That is, all resources for an application or service are grouped in the same ResourceBundle. In cases where this is not convenient, different base names can be used.

An example of the normal use of ResourceBundles is the notes application. The base name it uses is com.arsdigita.notes.NotesResources. It groups all its localizable resources into that ResourceBundle. On the other hand, the places service uses multiple base names, since it maintains a large amount of data, which may not be needed by all developers. For example, a developer might just want to translate the names of countries into a particular language, and not require any other place data. Therefore, the places service divides its resources into different base names, including com.arsdigita.places.CountriesResources, com.arsdigita.places.USStatesResources and so on.

It is recommended that you use PropertyResourceBundle [2] to store static resources. Static resources remain the same for the lifetime of the running server. This includes strings on WUI elements (such as form labels, page titles, and error messages) and names of objects that do not change frequently (such as country and city names).

For example, PropertyResourceBundles might appear as follows for a HelloWorld application, in English, Spanish, and French:

For dynamic resources, the MessageCatalog class is provided. Dynamic resources are those that change while the server is running. Most of these have to do with user-contributed content, where a user can be an administrator of the site or a regular user. For example, if the Categorization service was internationalized and application users were to be allowed to create categories, the application could allow the user to create a category and name it in more than one language, or mark the category name for translation into the different languages that the application supports. Since this kind of data is hard to maintain in PropertyResourceBundles, it is stored it in database-backed MessageCatalogs.

A MessageCatalog is simply a way to store ResourceBundles in the database. To use them, you create a MixedResourceBundle . This inherits from Java's ResourceBundle and combines a PropertyResourceBundle and a MessageCatalog, which have the same base name, into one. It does this by reading the PropertyResourceBundle from the file system and the MessageCatalog from the database.

No code goes into a MixedResourceBundle; all the code is in the superclass itself. A MixedResourceBundle for the notes application might appear as follows:

package com.arsdigita.notes;

import com.arsdigita.globalization.MixedResourceBundle;

public class NotesResources_en_US extends MixedResourceBundle {}

	Note
	This MixedResourceBundle is for the base name com.arsdigita.notes.NotesResources and the Locale en_US. This stems from the ResourceBundle name and indicates the Locale associated with the ResourceBundle. In this case, this ResourceBundle should contain resources in American English.