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

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

   Error rendering macro 'artifact-resource-macro'

   com.sun.jersey.api.client.ClientHandlerException: java.net.NoRouteToHostException: No route to host (Host unreachable)

    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: app-products-messages_en.properties, which contains messages for English.

 # 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.title.label=Product title
products.product.image.label=Photo
products.product.description.label=Product description

1. Go to /src/main/resources/app-tutorial/i18n in the module source files.
2. 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:

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  app-products-messages_de.properties in the i18n subfolder.

   <CATALINA_HOME>
   └── webapps
       └── magnoliaAuthor
           └── app-tutorial
               └── i18n
                   ├── app-products-messages_de.properties
                   ├── app-products-messages_en.properties
                   └── app-products-messages_es.properties

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
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.

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

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

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

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.
     
• 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.