Manage resource bundles

Introduction

Goal

Use resource bundles to manage all your locale-specific messages in a single place.

Background

Resource bundles are collections of key-message pairs organized by locale. They simplify the creation of localized applications by allowing you to conveniently store all locale-specific messages in a single place from which they can be retrieved by programs and pages using locale-independent keys. This strategy enables you to decouple program code from locale-specific information and to store multiple locales inside a single container: the resource bundle itself.

Resource bundles can be created and edited in the Content application using the content editor, similar to editing regular documents.

Create a resource bundle document

In the Content application, navigate to a folder that supports resource bundles. Because resource bundles inherently include localization data across multiple locales, it is recommended that you create resource bundles outside of the scope of a specific locale (i.e. inside an "untranslated" folder). The default "administration" folder is an appropriate folder for creating resource bundle documents.

👍
Because resource bundles are used to manage data centrally, you may want to keep them inside a folder with restricted access rights.

In the folder's action menu (which appears when you hover over the folder), select New resource bundle... (Figure 1). A dialog pops up, asking to specify a Name. (Figure 2).

Figure 1. Select a folder in the CMS and create a document

Figure 2. Specify a name for the resource bundle.

Assign a unique ID

The editor presents a field to specify the resource bundle's ID and two green "+" buttons: one to add a value set or locale, and one to add a new key-values set (Figure 3). You must to assign an ID to the resource bundle, which is unique within the content repository. Consider using reverse domain name notation, for example "com.bloomreach.demo.MyResourceBundle".

Figure 3. Resource bundle editing template.

Add value sets

Typically, a value set represents all values for a specific locale inside the resource bundle. You add a value set by clicking the green "+" button near Manage value sets. The Value Set Add Dialog appears (figure 4), where you can specify the name of the value set. We recommend using valid locale names such as "nl" (Dutch) or "en_US" (American English).

Figure 4. Dialog panel for adding Value Sets.

Add resources

A resource is a set composed of a key, multiple values (one for each value set) and a description. Click the green "+" button in the lower part of the editing template to open the Resource Add Dialog (figure 5).

Figure 5. Dialog window to create and update a resource.

Field	Description
Key	The key should be a name that is used to retrieve a localized resource from the resource bundle, unique within the resource bundle. As the UI sorts the resources alphabetically by key, using a systematic notation approach for the key helps keeping semantically related keys together. For example, keys related to the site's search mechanism could be called "search.results", "search.box.placeholder", "search.box.button_label" etc.
Value ([default])	This is the value used if no locale has been specified or if the requested locale is not specified as a value set. You may want to use the language most common for your project.
Value ()	For each value set, a field is present. Enter the desired value for that value set / locale.
Description	Here, you can specify additional information relevant for this key. It will be shown when hovering over the question mark icon in the resource bundle editor (See figure 6).

Figure 6. The resource bundle editor after having added some resources.

Publish the resource bundle

In order to be able to use the resource bundle in your site, you need to publish it. In the editor menu, select Done. The menu will change to reflect the actions available after editing. Select Publication, then Publish. Your resource bundle is now available for use in your live site(s).

Modify and update a resource bundle

You can edit an existing resource bundle using the editor in the Content application. Once the updated resource bundle is re-published, changes will immediately be applied to pages using it without a need to re-deploy.

In the Content app, browse to and select the resource bundle containing the message you want to modify.
Enter edit mode by clicking the Edit button in the menu;
You can now perform the following operations:
1. Add and remove value sets/locales by using the "+" and "x" icons in Manage Value Sets.
  Note: when you add a locale, remember to set a value for every existing key by clicking on the edit button in the corresponding line.
2. Add and remove keys by clicking the remove icon ("x") in the Actions column;
3. Change the values for an existing key by clicking the edit icon in the Actions column.
When you have completed your changes, re-publish the document by clicking Done in the menu, followed by Publication and Publish.
The changes you have made will become immediately available to all the pages using it.