Sometimes a template needs to render localized text that is not part of the content (for example when rendering descriptive information). As templates are meant to be independent of a specific language, a mechanism has been added to render localized texts by using a unique, symbolic name instead of the actual text in templates.

To be able to achieve this, every brick and theme package can provide these unique keys in form of one or more resource bundles placed in the src/l10n folder of the package. Resource bundles are Java Properties files that follow a certain naming pattern, for example:

This means according to the name of the file that you have a set of resource bundles named my-theme which provides localization for two different languages: "en" and "de" (represented as ISO 639-1 code by the suffix of the basename, see ISO 639-2 Language Code List). A set of resource bundles always needs a master resource bundle which is used as a fallback if no other localization is found. For our theme's and bricks this is the English localization. The resource bundles for other languages than the master are called the derived resource bundles.

To add a resource bundle to a theme, it has to be added to the theme configuration. See Section 6.2, “Theme Config”:

{
  "name": "my-theme",
  ...
  "l10n": {
    "bundleNames": [
      "MyTheme"
    ]
  }
  ...
}

All properties files contain pairs of keys and values where the key is the symbolic name used in the template and the value is the text localized for a concrete language. The identifiers used as a key are restricted to certain letters (for example, no spaces can be used). For more information about the syntax check Properties File Format. By default, the ThemeImporter assumes the properties files to be Latin-1 encoded. If you store them in a different encoding (like UTF-8), you must specify the encoding in the theme configuration. For details see Section 6.2, “Theme Config”. The master (in this case "en") properties file might look like this:

# this is the english properties file
button_close=Close
info=Info
search_results=There are {0} search results for the term "{1}"

While the derived "de" properties files might look like this:

# this is the german properties file
close=Schlie\u00DFen
search_results=Es gibt {0} Such-Ergebnisse für den Suchbegriff "{1}".

As you can see, the derived properties file does not contain all keys the master file has. This is okay as the lookup mechanism will always fall back to the master properties file in case the key was not found in the resource bundle of the concrete language.

Note

While it is okay to omit keys of a master resource bundle in a derived resource bundle, this does apply to the other way around. A derived resource bundle should never define a key the master resource bundle does not provide.

Resource bundles of bricks are aggregated and merged based on the dependencies added to the package.json of the theme. When including any brick just add the Bricks resource bundle name to your theme configuration and the localization of all bricks is added. For more information see Section 5.3, “Using Bricks”.

Key names are unique across sets of resource bundles of all packages. Avoid using the same key in different packages as long as you are not overriding a key assigned. In case the same key is used in multiple different sets of resource bundles the order in which the resource bundles are added in the theme config is important as the first assignment of the key determines the value. All following assignments are ignored. This also applies if (for whatever reasons) a key is defined multiple times in the same file but it will also log an error when importing the theme into the content repository. As the resource bundles of bricks are merged into a single resource bundle make sure that you use unique keys across all bricks, overriding existing keys in bricks is not supported.

After a message key is defined for different languages, it can be used in the template in two different ways using the FreeMarker facade described in Section 6.5.1, “CoreMedia (cm)”.

Both methods are wrappers for springMacroRequestContext.getMessage() of the Spring Framework and support optional arguments. Please also take a look at the official spring.ftl descriptions.

Note

When not using the Chapter 3, Web Development Workflow, make sure that you upload the theme to the content server when adding a new resource bundle to the theme config before using it in the template. Otherwise, the resource bundle will not be taken into account when accessing a key in the template.