Language

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:

• System: Controls how the user interface (dialogs, fields, messages) adapts to different languages and locales.
• Authoring: Supports localized content entry.
• Content: Handles the storing and serving of localized content in the JCR.

System

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.

Authoring

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

Unicode

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 conf/server.xml:

<Connector port="8080" protocol="HTTP/1.1" 
       connectionTimeout="20000" 
       redirectPort="8443"
       URIEncoding="UTF-8"
       useBodyEncodingForURI="true" />

For JBoss AS, add the following section in standalone.xml or domain.xml right after the extensions section.

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

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

Dialogs

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 i18n to true on controls for which you want to enable  localized authoring.

Template scripts

Similarly, you define an i18nBasename in the template or component definition. You would then use a key in the template script.

Freemarker:

${i18n['link.readon']}

JSP (JSTL):

<fmt:message key="link.readon"/>

Content

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.

One hierarchy or many

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.

Storing localized content

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 subtitle and text properties for each language under the 02 paragraph node. Each property is suffixed with a language identifier: _de or _fr. Since English is the base locale on this site, no _en identifier is used.

Delivering localized content

Localized content is served to visitors at a URL that identifies the locale:

Correspondingly, the HTML element on the public page identifies the language with standard lang and xml:lang attributes.

<!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:

• Allow the visitor to select a language or region from a dropdown, then redirect them to the correct URL. This is a common strategy on airline websites. Airlines serve customers in many countries and languages, and allow users to select their home country while travelling.
• Detect the visitor's origin from their IP or the referring page, then redirect them to the localized site automatically.
• Detect the visitor's preferred locale from their browser settings, then redirect them to the localized site automatically.

Content translation

The Content Translation Support module allows you to export and re-import page content in translation-friendly CSV and Excel formats.

Related content

• Multilanguage Structure
• Creating a language switcher link