Making a module translatable

This page explains in four easy steps the general procedure that is to be followed in making your module or app translatable. We assume that you have read and are familiar with the basic aspects of internationalization.

Step 1: Create a message file

For your app or module, create a message file named <bundle-name>_<locale>.properties and save it to the /src/main/resources/<module-name>/i18n/ directory in the module structure. If the folder doesn’t exist, create it. For your app. Every app should have its own message bundle. So if your module deploys two apps, create two bundles.

Make sure that the filename corresponds to the following pattern:

Step 2: Add keys and translations to the file

Include the message keys and the translations in the .properties file. Below is an example pattern for an app named foobar-app with the subapps browser and foobar (a detail item editor). You may want to use this file as a template .properties file for your own custom content app.

# App name and icon app # Action bar sections
foobar-app.browser.actionbar.sections.preview.label=Preview # Actions
foobar-app.browser.actions.addProduct.label=Add foobar
#foobar-app.browser.actions.addFolder.label=Add folder
#foobar-app.browser.actions.editFolder.label=Rename folder
#foobar-app.browser.actions.deleteFolder.label=Delete folder
foobar-app.browser.actions.editProduct.label=Edit foobar
foobar-app.browser.actions.deleteProduct.label=Delete foobar
#foobar-app.detail.actions.cancel.label=Cancel changes # Editor foobar-app.label=Edit foobar
foobar-app.description=Define the foobar information # Edit dialog
foobar-app.foobar.jcrName.label=Foobar name
foobar-app.foobar.title.label=Foobar title

Before saving your .properties file, make sure that the <locale> part of the filename matches the language of the translation labels.

Step 3: Revise the messages in your bundle

For the translation to work, you must add key/value pairs for both the autogenerated keys and custom defined keys. For some standard components or sub elements such as the buttons Cancel'' and ``Save, you may rely on the already existing translations in message bundles of other Magnolia modules. In the above template code, such translations are on the commented-out lines 11, 12, 13, 16, and 17 (for more information about reusing existing keys, see Generic i18n keys).

Step 4: Check the outcome in the UI

Check the messages for all your dialogs and other elements of your app or module in the UI. Any change made to a *.properties is applied and visible instantly.


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.