Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
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) 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.
.propertiesfiles. 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
.propertiesfile. 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.
Example: English messages in the
app-contacts-message_en.properties message file in the Contacts module ( Git )
# 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:
If you don't have apps in your module, use this file name pattern:
<locale> is a combination of language and country. Magnolia follows the Java locale notation.
Example: Message files in the Contacts module. (Git)
|Simplified Chinese (China)|
The basename reflects the location of a message bundle inside a webapp using the Java notation for directories.
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:
Technically, a message bundle is just a properties file that gets loaded form either
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.
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.
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.
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:
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-5652Getting issue details...
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.