i18n best practices

This page describes selected best practices within the context of i18n API.

Use message bundles

Provide a message bundle in your module. It makes translation easier. A translator can work with a plain text file and doesn’t need to touch the code. A message bundle is a collection of .properties files. Each file contains key-value pairs of translated user interface text such as labels and messages. The keys in all .properties files of the same bundle are identical but the values are language specific translations.

We recommend the following i18n filename patterns, for apps and modules, respectively:


Use Java locale notation for <locale>

Make sure the locale is correct. Magnolia follows the Java locale notation.

Bundle *.properties into ./<module-name>/i18n/

Keep your message bundles in the following folders:

  • src/main/resources/<module-name>/i18n/ (Maven module development) or in

  • <magnolia.resources.dir>/<module-name>/i18n/ (light development).

Use generic i18n keys

Whenever possible (see here for more details and restrictions), use generic, i.e. shorter i18n keys. The shorter the form, the more modules will exist where the key can be instantly reused.

Use UTF-8 encoding

Use UTF-8 character encoding in .properties files.

Separate message bundles

Create separate message bundles for user interface labels and template labels. Don’t store these two groups of text in the same properties files or message bundles. They are aimed at different audiences and have different localization requirements.

Example: Message files in the Travel Demo


DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.