Repository Resource Bundles

This page explains repository resource bundles in Bloomreach Content. It covers their purpose, usage in the product, and how to implement them in custom plugins.

Repository resource bundles provide translations for strings defined through repository configuration. Typical use cases include:

Translating document type names, field names, and field hints
Translating image set names and field names
Translating validator feedback messages

Repository resource bundles are one of several sources for CMS UI translations. For more information, see CMS UI localization.

Bootstrapping

Import repository resource bundles using the configuration management system. You can export them with the auto-export plugin. To import a resource bundle, define it in YAML as shown below:

definitions:
  config:
    /hippo:configuration/hippo:translations/myproject:translations
      jcr:primaryType: hipposys:resourcebundles
      /channelmanager:
        jcr:primaryType: hipposys:resourcebundles
        /awesomecomponent:
          jcr:primaryType: hipposys:resourcebundles
          /en:
            jcr:primaryType: hipposys:resourcebundle
            name: value
            workshopPeriod: The workshop starts on ${startday} and ends on ${endday}.
    /hippo:configuration/hippo:translations/hippo:types/myproject:book:
      jcr:primaryType: hipposys:resourcebundles
      /en:
        jcr:primaryType: hipposys:resourcebundle
        myproject:title: Book title
      /nl:
        jcr:primaryType: hipposys:resourcebundle
        myproject:title: Boek titel

This example loads resource bundles for the document type myproject:book and for a project-specific section used by a custom plugin. You can place resource bundles at any depth in the configuration tree.

Using Resource Bundles in Code

To use translated labels in Wicket code, use the org.hippoecm.frontend.l10n.ResourceBundleModel helper class. The following example loads the translation for the key name for the current user's locale. This matches the custom plugin example in the Bootstrapping section:

final String bundleName = "myproject:translations.channelmanager.awesomecomponent";
final String key = "name";
final Label label = new Label("label-wicket-id", new ResourceBundleModel(bundleName, key));

If the label is missing due to a configuration or coding error, ResourceBundleModel returns ???key??? to provide visual feedback during setup. Refer to the ResourceBundle rules for more details.

ResourceBundleModel retrieves data using the LocalizationService. You can also access the LocalizationService directly. The following example retrieves the English resource bundle for the same custom plugin:

final String bundleName = "myproject:translations.channelmanager.awesomecomponent";
final String locale = "en";

final LocalizationService localizationService = HippoServiceRegistry.getService(LocalizationService.class);
if (localizationService != null) {
    final ResourceBundle bundle = localizationService.getResourceBundle(bundleName, locale);
    if (bundle != null) {
        // ...
    }
}
// …

Using Variables

In Wicket, you can substitute variables in translated strings by providing parameters. The following example demonstrates this approach:

Map<String, String> parameters = new HashMap<>();
parameters.put("startday", "Monday");
parameters.put("endday", "Wednesday");

ResourceBundleModel model = new ResourceBundleModel
                                .Builder("myproject:translations.channelmanager.awesomecomponent", "workshopPeriod")
                                .parameters(parameters)
                                .build();

This model will contain the string: "The workshop starts on Monday and ends on Wednesday."

When using the LocalizationService and a ResourceBundle directly, pass the parameters as a second argument:

String string = bundle.getString(key, parameters);

Conventions

Product-provided resource bundles follow these conventions:

The # character separates a label from a sublabel, typically for document field hints. For example, the “blog” feature in Essentials defines hints for fields such as myproject:accounts#hint.
The = character separates a label from subvalues. For example, the resource bundle for hippostd:date includes keys like hippostd:dayofweek=1.