Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

In this tutorial you translate an app to another language. You will create a file that contains translated user interface text, then load the file in Magnolia. Don't worry if you are not a developer. You don't need a development environment for this tutorial – all you need is language skills.

Install the Products app

In this tutorial we work with the Products app that was introduced in My first content app. The app is installed by the App Tutorial module. If you are a developer, clone the app-tutorial project in Git. If you don't have a Java development environment, install the Magnolia bundle on your computer instead.

Option 1: Clone the app-tutorial project in Git

Choose this option if you know how to work with a Magnolia project and Git. Clone the app-tutorial repository in Git:

git clone

Import the project into your IDE. Here's what the project looks like in IntelliJ IDEA:

Note that besides messages in English, it already contains also a i18n file with messages for Spanish.

Option 2: Install the Magnolia bundle

Choose this option if you don't have a Java IDE.

  1. Install Magnolia on your computer.
  2. Download the magnolia-app-tutorial-1.4.8.jar file from Nexus.
  3. Install the App Tutorial module on your Magnolia instance. Follow standard module installation instructions

Create German messages

To translate the Products app to German, we will use the file:, which contains messages for English.
 # App name and icon

# Action bar sections

# Actions
products.browser.actions.addProduct.label=Add product
products.browser.actions.addFolder.label=Add folder
products.browser.actions.editFolder.label=Rename folder
products.browser.actions.deleteFolder.label=Delete folder
products.browser.actions.editProduct.label=Edit product
products.browser.actions.deleteProduct.label=Delete product
products.detail.actions.cancel.label=Cancel changes

# Editor 
products.label=Edit product
products.description=Define the product information

# Edit dialog
products.product.jcrName.label=Product name
products.product.title.label=Product title
products.product.description.label=Product description
Option 1: To create German messages in an IDE:

  1. Go to /src/main/resources/app-tutorial/i18n in the module source files.
  2. Copy the English message file to a new file Your folder hierarchy should look like this:

Option 2: To create a German message file in your local Magnolia bundle:

  1. Go to  <magnolia.resources.dir>
  2. Create a <module-name>/i18n/ subfolder, in this case the app-tutorial/i18n/ subfolder.
  3. Copy the English message bundle to a new file in the i18n subfolder.

    └── webapps
        └── magnoliaAuthor
            └── app-tutorial
                └── i18n

Translate the text

Open the German message file and translate the English text into the target language. Here is an example and some translation tips.
# App name and icon

# Action bar sections

# Actions
products.browser.actions.addProduct.label=Neues Produkt
products.browser.actions.addFolder.label=Neuer Ordner
products.browser.actions.editFolder.label=Ordner umbenennen
products.browser.actions.deleteFolder.label=Ordner löschen
products.browser.actions.editProduct.label=Produkt bearbeiten
products.browser.actions.deleteProduct.label=Produkt löschen

# Editor
products.label=Produkt bearbeiten
products.description=Product-Informationen spezifizieren

# Edit dialog
products.product.photoCredit.description=Name des Fotografen oder Urhebers.


The i18n mechanism allows you to define locale-specific icons for apps and actions. Use your knowledge of the target culture to decide if this is necessary. If a symbol is unusual or difficult for readers of the target language to understand, you may want to change it.

For example, the Roman-alphabet question mark ? is mirrored in Arabic ؟. You need to decide if mirroring the help icon  for Arabic users is necessary .


In English, we recommend to use short action verbs that are easy to understand:

  • Add product
  • Add folder

When translating actions, follow any convention that is typical in the target language. For example, in German it is more common to use a noun phrase:

  • Neues Produkt
  • Neuer Ordner 

See: Naming action bar elements

Special characters

Save your .properties file with UTF-8 encoding. This ensures that Magnolia reads special characters correctly. UTF-8 is a very extensive character set that supports a variety of languages.

products.browser.actions.deleteFolder.label=Delete folder
products.browser.actions.deleteFolder.label=Ordner löschen

Test the translation

To see the messages translated to German, you must be logged in as a user with language preferences set to German. See setting an editor's language preference.

Reload the .properties file to see the changes in Magnolia:

  • In an IDE:
    1. Update the running project's resources. For example, in IntelliJ IDEA you can do this with  Run > Run > Update resources.
    2. In Magnolia, go to Dev > Dev Tools and reload i18n properties files.
  • In a Magnolia setup using a local message bundle:
    The translated messages should be available and seen in the Products app immediately after saving the .properties file. The icon and the label for the Products app in AdminCentral will be updated after relogging to the session. If running a pre-5.4.7 version of  Magnolia, reload the messages by going to Dev > Dev Tools and pressing the reload button in the top left corner of the workspace.

Verify that all user interface text in the Products app is translated correctly:

Contribute your translations to Magnolia

Have you translated a Magnolia app? Join the Internationalization effort. Send us the translated .properties files. We will add them to the product.