This page describes how language is configured in Magnolia. 

Setting an editor's language preference

To set a user's language preference, open the Security app and edit their profile. Select a language from the Language dropdown.

When the user signs in the next time, the UI is displayed in their preferred language.

Available system languages

System languages are configured in Configuration > /server/i18n/system. Each language has a language and country properties that define the locale when combined. This allows you to define regional variations such as zh_TW for traditional Chinese or pt_BR for Brazilian Portuguese.

Please take note of the supported locales for your version of Java (JDK 8 and JRE 8 Supported Locales).

Node nameValue

 i18n


   system


 languages


 zh_TW


 country      

TW

 enabled

true

 language

zh

 pt_BR


 de


 fr


 fallbackLanguage

en

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.

Configuring content entry language

Enable multilanguage content entry in /config/server/i18n/authoring. This allows editors to enter the same content in multiple languages.

Node nameValue

 server


 i18n


 system


 content


 authoring


 class   

info.magnolia.multisite.i18n.MultiSiteI18nAuthoringSupport

 enabled

true

Properties:

enabled

required, default is true

Enables multilanguage content entry.

class

required

A class that implements I18NAuthoringSupport such as:

  • info.magnolia.ui.framework.i18n.DefaultI18NAuthoringSupport supports multilanguage content entry for one site.
  • info.magnolia.multisite.i18n.MultiSiteI18nAuthoringSupport supports multilanguage content entry for many sites (EE Pro). This class reads the available locales (languages) from the site definitions. So you need to define them for each site.

Once i18n authoring is enabled, the top bar in the page editor displays a language dropdown.

When you select a language from the dropdown, component dialogs show a language identifier such as fr next to field labels. This makes it clear what language editors should be entering.

The language dropdown and the identifier is the way Magnolia supports localized content entry by default. You can develop your own alternative implementation. You could for example create a tab for each language. If the number of supported languages is not very large, say 3 or 4, tabs work well. The default strategy works with a large number of languages while keeping UI changes minimal.

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

Storing and serving localized content

Magnolia stores translated content in the repository and serves it at a language-specific URL such as mysite.com/de/welcome.html. 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.

Enable i18n content support in /config/server/i18n/content.

Node nameValue

 server


 i18n


 system


 content


 class   

info.magnolia.multisite.i18n.MultiSiteI18nContentSupport

 enabled

true

 authoring


Properties:

enabled

required, default is true

Enables multilanguage content storage and delivery.

class

required

A class that implements I18nContentSupport such as:

  • info.magnolia.cms.i18n.DefaultI18nContentSupport supports multilanguage content for one site.
  • info.magnolia.multisite.i18n.MultiSiteI18nContentSupport supports multilanguage content for many sites (EE Pro). This class reads the available locales (languages) from the site definitions. So you need to define them for each site.

One hierarchy or many

Magnolia can store multilanguage content in a single JCR content node. This means you only need one site hierarchy even if you serve content in many languages. However, there are cases when you may want to create language specific sites. See: Multilanguage structure.

If you go with the default one-hierarchy strategy, translations are stored as separate properties under a single content node. In the example below, a Text and Image component is translated into English, German and French. The system creates subtitle and text properties for each language under the 01 component node. Each property is suffixed with a language identifier: _de or _fr. Since English is the base locale on this site, no _en suffix is used.

Node nameValue

   content


 00


 0


 01


 imageLocation

left

 subtitle

Translation

 subtitle_de

Übersetzung

 subtitle_fr

Traduction

 text

<p>Translation of the user interface text is a community supported project.</p>

 text_de

<p>&Uuml;bersetzung der Benutzeroberfl&auml;che Text ist eine Gemeinde unterst&uuml;tzt das Projekt.</p>

 text_fr

<p>Traduction du texte de l&#39;interface utilisateur est un projet soutenu de la communaut&eacute;.</p>

Language specific URL

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

LocaleURL

Base locale, default language

www.mywebsite.com/article.html
Germanwww.mywebsite.com/de/article.html
Frenchwww.mywebsite.com/fr/article.html
Spanishwww.mywebsite.com/es/article.html

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 but 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 regardless of where in the world they happen to be.
  • Detect the visitor's origin from their IP or the referring page, then redirect them to the localized site.
  • Detect the visitor's preferred locale from their browser settings, then redirect them to the localized site.

UTF-8 page names

Magnolia supports UTF-8 character encoding for Unicode. UTF-8 is able to represent any character in the Unicode standard and is backwards compatible with ASCII.

To enable UTF-8 character encoding in page names:

  1. Enable URI encoding in your Web container configuration:
    For Apache Tomcat, set  URIEncoding="UTF-8"  in the  Connector section in  conf/server.xml :

    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.

    standalone.xml or domain.xml
    <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>
  1. fake
  2. Enable Unicode support for content node and page names. Set the magnolia.utf8.enabled property in a magnolia.properties file.

    magnolia.properties
    # Activate UTF-8 support to pages
    magnolia.utf8.enabled=true

This allows you to use a variety of non-ASCII characters in node names.

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.


#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))

1 Comment

  1. Christoph Meier Martin Drápela I have created a content app using maven project and enabled i18: true for TextField, when I deploy the app in magnolia its showing language selector in the bottom but showing on "English" and "German" Language default. 

    How to add more language of the content app, as per above doc we need to add locals in i18 but not sure how to add this in maven project, any sample or doc available.