Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
Internationalization (i18n) and localization (L10n) are ways to adapt Magnolia to different languages and regional differences. Internationalization involves designing the system so that it is easy to accommodate new languages without programming. Localization is the process of adapting Magnolia to a particular region or language by adding locale-specific configuration and translating text.
Localization is supported on three levels:
The AdminCentral user interface for content authors is available in 16 languages: Chinese (China), Chinese (Taiwan), Czech, Dutch, English, French, German, Indonesian, Italian, Japanese, Norwegian, Portuguese, Portuguese (Brazil), Russian, Spanish and Swedish.
To set a user's language preference, go to Security and edit their profile. Select a language from the Language dropdown.
When the user signs into AdminCentral next time, the UI is displayed in the preferred language.
Supported languages are configured in Configuration
/server/i18n/system. Each language has a country and language property so you can define regional variations too, such as
zh_TW for traditional Chinese or
pt_BR for Brazilian Portuguese.
One of the languages is always a fallback language. If no target language content is found, the system displays content in the fallback language instead.
Labels for user interface elements such as dialogs, tabs and buttons are stored in a message bundle. The bundle is a collection of properties files inside a module JAR. You can retrieve a particular label from the properties file by referring to it with a key in the UI element's configuration. For example, the reference key
dialogs.paragraphs.content.stkTextImage.tabText.label matches a label for the "Text" tab in the Text and Image dialog. It is retrieved from the
message_en.properties file included in the Standard Templating Kit module:
dialogs.paragraphs.content.stkTextImage.label=Text and Image dialogs.paragraphs.content.stkTextImage.tabText.label=Text dialogs.paragraphs.content.stkTextImage.tabText.subtitle.label=Subheading
Translation of user interface text to another language is a community project coordinated by Magnolia International Ltd. Community volunteers choose a language to translate and work in Google Spreadsheets. Their contributions are built into the properties files that ship with the system. We trust enthusiastic users to do a better job translating the UI than a professional translator who is not familiar with the system. If you want Magnolia in your own language, contribute to this effort.
This level of internationalization adapts the authoring interface to support localized content entry. The default implementation adds a language dropdown in the top bar and displays a two-letter language identifier (en, ge, fr etc.) next to field labels in the content entry dialog.
Enabling i18n authoring support allows authors to write foreign-language or regionally targeted content. The relevant configuration node is
/config/server/i18n/authoring. Set also
true in the dialog definition for controls for which you want to enable localized content entry.
Once enabled, the top bar displays a language dropdown. Selecting a language from the dropdown defines the content entry language for components and properties on the page.
Dialogs reflect the choice by displaying an identifier (en, fr, de...) next to field labels. This makes it clear which language should be entered.
The language dropdown and the identifier are Magnolia default implementations. You can alternatively develop your own strategy for localized content entry. You could for example create a tab for each language in the dialog. If the number of supported languages is not very large, say 3 or 4, this might work fine. We opted for the field label strategy because it works well with a large number of languages and keeps UI changes minimal.
Magnolia supports UTF-8 character encoding for Unicode. UTF-8 is able to represent any character in the Unicode standard and it is backwards compatible with ASCII.
To set UTF-8 encoding in your web container configuration:
For Apache Tomcat, set
URIEncoding="UTF-8" in the
Connector section in
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" URIEncoding="UTF-8" useBodyEncodingForURI="true" />
For JBoss AS, add the following section in
domain.xml right after the
<system-properties> <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"/> <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/> </system-properties>
Next, enable Unicode support for content node and page names. Set the
magnolia.utf8.enabled property in
# Activate UTF-8 support to pages magnolia.utf8.enabled=true
This allows you to enter content node and page names using a variety of non-ASCII characters.
URLs are displayed using the same characters as the node name.
Sites built using STK templates identify the encoding as UTF-8 with an HTML meta element.
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
Al Arabiya an example of an Arabic language site built with Magnolia. The Arabic script is written from right to left a cursive style. The characters are included in UTF-8.
For dialogs you can define a
i18nBasename data node which determines the message bundle to use. Like above, the bundle contains properties files which have strings for dialog elements. Instead of entering text manually you can use a key. The key will be substituted by the value from the property file.
Here's an example of the Text and Image dialog definition with
i18nBasename. The description and label properties use keys instead of manually entered strings.
You also need to set
true on controls for which you want to enable localized authoring.
Similarly, you define an
i18nBasename in the template or component definition. You would then use a key in the template script.
Content level internationalization handles the storing of localized content in the JCR and serving it at a language-specific URL such as
mysite.com/de/welcome.html. This option is enabled by default. Language variations are stored in a single content hierarchy. You have the option to disable the localized content storage and create a separate site hierarchy for each locale instead.
Magnolia' ability to store multi-language content in a single JCR content node means that you only need a single site hierarchy. As long as your site content is reasonably similar from one language to another, this is the best option. You have fewer pages to manage and the system takes care of serving the correct language automatically.
A use case where a single hierarchy makes sense is a white-labeled product such as an insurance policy. The number of pages and paragraphs needed to describe the policy to customers is likely the same regardless of the customer's language or locale. Regional affiliate companies offering the same policy can enter content in their own language and serve it under their own brand.
However, if the number of pages and components differ greatly from one locale to another, you have the option to create separate site hierarchies. One site tree for English, another for German and so on. This effectively duplicates some pages but allows completely customized local content.
The configuration is in
/server/i18n/content or in the case of Extended Templating Kit in the site definition.
If you choose the one-site-hierarchy strategy, language specific variations of a paragraph are stored as separate properties of a single content node. In the example below, a Text and Image dialog was used to write component text in English, German and French. The system created
text properties for each language under the
02 paragraph node. Each property is suffixed with a language identifier:
_fr. Since English is the base locale on this site, no
_en identifier is used.
Localized content is served to visitors at a URL that identifies the locale:
Base locale, default language
Correspondingly, the HTML element on the public page identifies the language with standard
<!DOCTYPE html> <html xml:lang="en" lang="en" class="no-js">
Magnolia does not redirect visitors to the localized URL automatically. You need to configure this behavior on the web server. There are various strategies how you might want to do this. Note that these are not provided out-of-the-box:
The Content Translation Support module allows you to export and re-import page content in translation-friendly CSV and Excel formats.