My first translation

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. See Language configuration for more information about the internationalization (i18n) mechanism that makes apps and modules translatable.

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.

Option1: 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 http://git.magnolia-cms.com/git/modules/app-tutorial.git

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

Option 2: Install the Magnolia bundle

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

Install the Magnolia bundle on your computer. Choose the Community Edition or Enterprise Edition.
Download the magnolia-app-tutorial JAR file from Nexus.
Install the App Tutorial module on your Magnolia instance. Follow standard module installation instructions

Create German messages

A message bundle (resource bundle in Java) 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 files of the same bundle are identical but the values are language specific translations. A message bundle must contain at least one .properties file. The files are named after the language (locale): <bundle-name>_<locale>.properties, for example app-pages-messages_en.properties. Every Magnolia module should provide its own message bundle. If a module installs several apps, each app should have its own message bundle.

The Products app already has English messages: app-products-messages_en.properties. This file is the basis for translating the app to other languages.

app-products-messages_en.properties

# App name and icon
products.app.label=Products
products.app.icon=icon-items

# Action bar sections
products.browser.actionbar.sections.root.label=Products
products.browser.actionbar.sections.folder.label=Folder
products.browser.actionbar.sections.product.label=Product
products.browser.actionbar.sections.preview.label=Preview

# 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
products.detail.actions.save.label=Save changes

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

# Edit dialog
products.product.label=Product
products.product.jcrName.label=Product name
products.product.fileUpload.label=Photo
products.product.photoCredit.label=Photo credit
products.product.photoCredit.description=Name of the photographer or copyright holder.

Option 1: To create German messages in an IDE:

Go to /resources/mgnl-i18n in the module source files.
Copy the English message file to a new file app-products-messages_de.properties. Your folder hierarchy should look like this:

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

Go to <CATALINA_HOME>/webapps/magnoliaAuthor/WEB-INF/classes.
Create a mgnl-i18n folder.
Copy the English message bundle to a new file app-products-messages_de.properties in the mgnl-i18n folder.
Restart Magnolia.

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-products-messages_de.properties

# App name and icon
products.app.label=Produkte
products.app.icon=icon-items

# Action bar sections
products.browser.actionbar.sections.root.label=Produkte
products.browser.actionbar.sections.folder.label=Ordner
products.browser.actionbar.sections.product.label=Produkt
products.browser.actionbar.sections.preview.label=Vorschau

# 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.label=Produkt
products.product.jcrName.label=Name
products.product.fileUpload.label=Bild
products.product.photoCredit.label=Fotograf
products.product.photoCredit.description=Name des Fotografen oder Urhebers.

Icons

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 .

Actions

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.

en

products.browser.actions.deleteFolder.label=Delete folder

de

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

ja

products.browser.actions.deleteFolder.label=削除されたフォルダ

zh_CN

products.browser.actions.deleteFolder.label=已删除的文件夹

Test the translation

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.
On a local Magnolia bundle, go to Dev > Dev Tools and reload i18n properties files.

Set a user's language preference to German, log in as that user, and 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.

Page tree