Internationalization basics

This page explains basic internationalization (i18n) concepts in Magnolia. The concepts help you understand the other language pages in this section.

Internationalization (i18n) and localization (L10n)

Internationalization (i18n) and localization (L10n) are ways to adapt Magnolia to different languages and regional differences. Internationalization involves designing a system where it is easy to accommodate new languages without programming. Localization adapts Magnolia to a particular region or language by adding locale-specific configuration and translating text.

Message bundle

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.

Best practice

Provide a message bundle in your module. It makes translation easier. A translator can work with a plain text file and doesn't need to touch code.

Example: English messages in the app-contacts-message_en.properties message file in the Contacts module ( Git )

app-contacts-messages_en.properties

# App
contacts.app.label=Contacts
contacts.app.icon=icon-people
contacts.chooseDialog.label=Contacts chooser

# Subapps
contacts.browser.actionbar.sections.root.label=Contacts
contacts.browser.actionbar.sections.deletedContact.label=Deleted contact
contacts.browser.actionbar.sections.deletedFolder.label=Deleted folder
...

The message files are stored in a mgnl-i18n directory inside the module.

If you have apps in your module, use this file name pattern:

app-<app name>-messages_<locale>.properties

If you don't have apps in your module, use this file name pattern:

module-<module name>-messages_<locale>.properties

where <locale> is a combination of language and country. Magnolia follows the Java locale notation.

Example: Message files in the Contacts module. (Git)

Locale	Message files
German	`app-contacts-messages_de.properties`
English	`app-contacts-messages_en.properties`
Spanish	`app-contacts-messages_es.properties`
Japanese	`app-contacts-messages_ja.properties`
Simplified Chinese (China)	`app-contacts-messages_zh_CN.properties`

Basename

The basename reflects the location of a message bundle inside a webapp using the Java notation for directories.

Example

You have the following files in your webapp:

src/main/resources/info/magnolia/module/templatingkit/messages_en.properties
src/main/resources/info/magnolia/module/templatingkit/messages_de.properties 
src/main/resources/info/magnolia/module/templatingkit/messages_es.properties

These files together build a message bundle available in English, German and Spanish. The locale specific part _en and the suffix .properties at the end of the file name are ignored.

The basename for this bundle is:

info.magnolia.module.templatingkit.messages

Key

Technically, a message bundle is just a properties file that gets loaded form either java.util.PropertyResourceBundle or java.util.Properties. A properties file must contain key-value pairs:

<key> = <translated value>

In Magnolia documentation we often use the term key to mean a key-value pair.

A key must be unique within a bundle. See about the naming of keys and where they should be unique.

Unicode and UTF-8 encoding

UTF-8 is the dominant character encoding for the World Wide Web. Magnolia supports UTF-8 character encoding for Unicode. UTF-8 can represent any character in the Unicode standard and is backwards compatible with ASCII.

Best practice

Magnolia requires everyone to use UTF-8 character encoding in .properties files.

Character encoding in JCR

The Java Content Repository (JCR) will store values in whatever format you provide. Magnolia always ensures that all values are UTF-8 encoded.

In the past it was necessary to ensure that the underlying persistence layer such as Oracle or MySQL database charset was set to UTF-8. This is no longer necessary.

Character encoding in message bundles

Java classes read .properties files of message bundles from the file system. Depending on the implementation of these stream reading classes, Java allows you to set the encoding in which the files are read.
Magnolia's i18n framework assumes that files in message bundles are UTF-8 encoded (see DefaultMessageBundlesLoader , DefaultMessagesImpl ).

If you open some older properties files in some of the Magnolia modules you will find keys like this:

standard-templating-kit/magnolia-module-standard-templating-kit/src/main/resources/info/magnolia/module/templatingkit/messages_cs.properties

link.readon = P\u0159e\u010d\u00edst

This file contains Unicode entities or Java Unicode Character Representations. When you use Unicode entities to encode special characters, it doesn't matter what encoding your file is stored in or read by the Java class.

However, the above is a legacy practice that is no longer necessary. Since MAGNOLIA-5652 - Getting issue details... STATUS you don't have to use Unicode entities, just make sure your properties files are UTF-8 encoded. The above snippet from the bundle with basename info.magnolia.module.templatingkit.messages can be written like this:

link.readon = Přečíst

Use ISO-8859-1 with JSP

Message bundles for JSP templates are read by standard JSTL mechanism which reads files with ISO-8859-1 encoding by default. Save your properties files with ISO-8859-1 encoding or use Unicode entities when working with JSP. If you cannot use Unicode entities, avoid using the same message bundle for JSP and Freemarker scripts. JSP can be forced to explicitly use UTF-8 encoding when reading properties files. Watch MAGNOLIA-5909 for resolution.

Page tree