Language configuration

This page describes how language is configured in Magnolia.

Setting an editor’s language preference

To set a user’s language preference:

  1. Open the Security app (Apps > Security).

    Type security in the Find Bar.
  2. Select the user profile you wish to edit.

  3. 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 locale has 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.

From Magnolia 6.2.4, both Java 8 and Java 7 locale IDs are supported in configuration.

image

Fallback language

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.

Enabling multilanguage content

To enable multilanguage content:

  1. Enable multilanguage authoring.

  2. Set i18n=true.

    1. in form fields

    2. on content type properties

  3. Define locales in the site.

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

image

Property Description

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 (DX Core). This class reads the available locales (languages) from the site definitions. So you need to define them for each site.

Set i18n=true

In form fields

Set the i18n property to true in all fields where you want to enter multilanguage content.

Example: The text field title is enabled for multilanguage content entry.

<module name>/dialogs/<dialog name>.yaml
form:
  tabs:
    - name: tabText
      label: Text
      fields:
        - name: title
          class: info.magnolia.ui.form.field.definition.TextFieldDefinition
          label: Title
          i18n: true

On content type properties

Add the i18n property with the true value to all content type model properties where you want to enter multilanguage content.

Example: The text field description is enabled for multilanguage content entry.

/my-module/contentTypes/tourVehicle.yaml
datasource:
  workspace: tourvehicles
  rootPath: /
  autoCreate: true
model:
  properties:
    - name: description
      i18n: true

Define the languages that editors should be able to choose as locales in the site definition under <site>/i18n/locales. Each locale has language and country properties. They allow regional variations such as zh-TW for traditional Chinese or pt-BR for Brazilian Portuguese.

From Magnolia 6.2.4, both Java 8 and Java 7 locale IDs are supported in configuration.

Example: Locales en and de in the default site definition

image

Property Description

locales

required

     <locale>

required

Locale ID that consists of language and country such as zh-TW for traditional Chinese or pt-BR for Brazilian Portuguese.

         enabled

optional, default is false

Enables the locale.

         language

required

Language code such as pt for Portuguese. See Java 8 locale IDs.

         country

optional

Country code such as BR for Brazil. See Java 8 locale IDs.

class

required

Class that implements I18nContentSupport such as:

  • info.magnolia.cms.i18n.DefaultI18nContentSupport which supports a language prefix such as /en/* in the URL and stores localized content in a node using the naming pattern <name><locale>, for example subtitle_en.
    Use this implementation if your site is organized into a single tree, in which the locale prefix usually points to the root of a site.

  • info.magnolia.cms.i18n.HierarchyBasedI18nContentSupport which stores and serves localized content in a hierarchical structure.
    Use this implementation if your site is organized into multiple trees, in which site roots are usually named after the locales.

  • info.magnolia.cms.i18n.RequestLocaleAwareI18nContentSupport which reads the locale from the request. This implementation does not render language specific URLs.

enabled

optional, default is false

Enables support for localized content. Used to rewrite URIs and getting nodes based on the current language.

fallbackLocale

optional, default is en

Content is served for the fallback locale if content is not available for the current locale.

Once multilanguage content entry is enabled, the page editor displays a language dropdown.

image

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

The language identifier is not displayed for the fallback locale, unless the i18n property is set to true in the definition of the given dialog. For example, if your fallback locale is English you won’t see (en) next to the field label.

image

Displaying the locale dropdown and a locale identifier in the dialog is Magnolia’s default way to let editors choose a language. You can implement your own alternative such as separate tabs for each language. If the number of supported languages is not very large (3-4) tabs work well. The default approach works with any 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.

image

Property Description

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.module.site.i18n.SiteI18nContentSupport supports multilanguage content for many sites (DX Core). 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.

image

Language specific URL

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

Locale URL

Base locale, default language

www.mywebsite.com/article.html

German

www.mywebsite.com/de/article.html

French

www.mywebsite.com/fr/article.html

Spanish

www.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. 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>
  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 (1)
    1 This allows you to use a variety of non-ASCII characters in node names.

    image

URLs display the same characters as the node name.

image

Sites built using Magnolia Templating Essentials templates identify the encoding as UTF-8 with an HTML meta element.

<meta charset="utf-8">

Al Arabiya is 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.

image

Feedback