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 also 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  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
            └── modules
                └── 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


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.

To test the translation:

  1. Change the language preference in your user account to Deutsch. See Setting an editor's language preference.
  2. Logout of AdminCentral and login again.
  3. Open the Products app to view the German labels.

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.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))