## 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 1. Select a folder in the CMS and create a document

Figure 2. Specify a name for the resource bundle.

Figure 2. Specify a name for the resource bundle.

### Assign a Unique ID

The editor presents a field to specify the resouce 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.

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.

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.

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

KeyThe 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 (<value set name>)For each value set, a field is present. Enter the desired value for that value set / locale.
DescriptionHere, 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.

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.

  1. In the _Content_ app, browse to and select the resource bundle containing the message you want to modify.

  2. Enter edit mode by clicking the _Edit_ button in the menu;

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

  4. When you have completed your changes, re-publish the document by clicking _Done_ in the menu, followed by _Publication_ and _Publish_.

  5. The changes you have made will become immediately available to all the pages using it.