Language configuration

Magnolia CMS provides comprehensive multilanguage support for both the AdminCentral interface and website content. Key features include:

  • System language configuration

  • User interface language preferences

  • Multilanguage content creation and management

  • Content storage and URL strategies for localized content

  • UTF-8 support for international character sets

Language configuration operates at multiple levels, from individual user preferences to system-wide settings and site-specific configurations. Understanding these different aspects helps you implement an effective multilanguage strategy for your Magnolia projects.

Configure system languages

Magnolia supports multiple system languages for the administration interface and other system components.

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.

server:
  i18n:
    system:
      fallbackLanguage: en
      languages:
        en:
          country:
          enabled: true
          language: en
        pt:
          country:
          enabled: true
          language: pt
        pt_BR:
          country: BR
          enabled: true
          language: pt
        zh_CN:
          country: CN
          enabled: true
          language: zh
        zh_TW:
          country: TW
          enabled: true
          language: zh
From Magnolia 6.2.4, both Java 8 and Java 7 locale IDs are supported in configuration.

Fallback language

One language is designated as the fallback language. If no content is available in the target language, Magnolia displays content in the fallback language (en in the example above).

Configure user interface language preferences

Magnolia allows users to set their preferred language for the user interface. This setting is stored in the user profile and applies to the AdminCentral interface.

Set an editor’s language preference

To set a user’s language preference:

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

  2. Select the user profile you wish to edit.

  3. Click Edit user.

  4. Select a language from the Language dropdown.

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

Set up multilanguage content

This section explains how to enable and configure multilanguage content for your website.

Enable multilanguage content

To enable multilanguage content:

  1. Configure the I18NAuthoringSupport implementation to support multilanguage editing. See Configure I18nAuthoringSupport.

  2. Set i18n: true in form fields to allow multilanguage content entry. See Set i18n to true in form fields.

  3. Set i18n: true in content type properties for multilanguage content types. See Set i18n to true in content type properties.

  4. Define locales in the site configuration to specify available languages. See Define locales for the site.

Configure I18nAuthoringSupport

In Magnolia 6.3, the I18NAuthoringSupport interface, which controls multilanguage authoring, is configured in a module descriptor instead of JCR at /server/i18n/authoring. For example, the magnolia-module-multisite-jcr module defines:

<component>
  <type>info.magnolia.ui.api.i18n.I18NAuthoringSupport</type>
  <implementation>info.magnolia.multisite.i18n.MultiSiteI18nAuthoringSupport</implementation>
  <scope>singleton</scope>
</component>
If you use Live Copy, you can override this configuration with info.magnolia.livecopy.i18n.I18NAuthoringSupportProvider, which by default resolves to MultiSiteI18nAuthoringSupport. See the Live copy internationalization page for more details.

To override this with a custom implementation (for example, extending MultiSiteI18nAuthoringSupport to define locales based on a node path), add it to your project module’s descriptor:

<module-name>-jcr.xml
<component>
  <type>info.magnolia.ui.api.i18n.I18NAuthoringSupport</type>
  <implementation>com.custom.i18n.CustomI18nAuthoringSupport</implementation>
  <scope>singleton</scope>
</component>

Before Magnolia 6.3, you could override I18NAuthoringSupport via JCR at /server/i18n/authoring. If using magnolia-module-multisite-jcr, ensure your custom module loads after it by adding a Maven dependency in your pom.xml:

<dependency>
  <groupId>info.magnolia.multisite</groupId>
  <artifactId>magnolia-module-multisite-jcr</artifactId>
  <version>${multisiteVersion}</version>
</dependency>

See Upgrading to Magnolia 6.3 for more information.

Set i18n to true in form fields

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

Example: Multilanguage content is enabled for the title text field.

<module-name>/dialogs/pages/<dialog-name>.yaml
form:
  properties:
    title:
      $type: textField
      i18n: true

Set i18n to true in 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.

<module-name>/contentTypes/tourVehicle.yaml
datasource:
  $type: jcrContentTypeDatasource
  workspace: tourvehicles
  autoCreate: true
model:
  properties:
    - name: description
      i18n: true

Define locales for the site

Define the languages that editors should be able to choose as locales in the site definition under <site>/i18n/locales.

Example: en, de and cs locales in an example test site definition.

test:
  i18n:
    enabled: true
    class: info.magnolia.cms.i18n.DefaultI18nContentSupport
    fallbackLocale: en
    defaultLocale: cs
    locales:
      cz:
        country: CZ
        language: cs
        enabled: true
      de:
        country: DE
        language: de
        enabled: true

Properties

Property Description

enabled

optional, default is false

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

class

required

Class that implements info.magnolia.cms.i18n.I18nContentSupport such as:

  • Implementations for a site organized into a single tree, in which the locale prefix usually points to the root of a site.

    • info.magnolia.cms.i18n.IetfI18nContentSupport. This is the default implementation, which supports IETF BCP 47 language Tags.

      Example
      test:
  i18n:
    enabled: true
    class: info.magnolia.cms.i18n.IetfI18nContentSupport
    fallbackLocale: en
    defaultLocale: cs
    locales:
      cz:
        languageTag: cs-CZ
        enabled: true

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

fallbackLocale

optional, default is en

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

defaultLocale

optional

If no locale can be determined, the default locale will be set. If no default locale is defined, the fallback locale is used.

locales

required

     <locale>

required

An arbitrary locale ID. For example, one that consists of language and country such as zh-TW for traditional Chinese or pt-BR for Brazilian Portuguese.

         country

optional, for configurations using the language property

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

         language

required, unless a configuration with the languageTag property is used

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

         languageTag

required, unless a configuration with the language property is used

An IETF BCP 47 language tag.

Available since Magnolia 6.2.45.

         enabled

optional, default is false

Enables the locale.
Configure locales for the fallback site

If i18n is enabled in the configuration of your content app, you need to configure locales for the fallback site or extend a site definition with locales.

Then, when editing structured content, the locales of the fallback site will be used while showing the language dropdown.

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

Authoring language selector

When you select a language, 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.

English as fallback language

Magnolia’s default language selector is a dropdown, but you can implement alternatives like tabs for each language if you don’t need a large number of languages.

Manage translated content

This section covers creating, storing, and exporting translated content.

Create translated content

Editors can select a language from the dropdown in the Pages app to enter translations. Magnolia stores translations as language-specific properties (for example, title_en, title_de) in a single content hierarchy or as separate nodes if using multiple hierarchies.

Store localized content

Magnolia stores translated content in the JCR repository. By default, translations are stored in a single content hierarchy as properties with language suffixes.

Example: A Text and Image component translated into English, German, and French.

content:
  00:
  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>Übersetzung der Benutzeroberfläche Text ist eine Gemeinde unterstützt das Projekt.</p>
    text_fr: <p>Traduction du texte de l'interface utilisateur est un projet soutenu de la communauté.</p>

You can disable single-hierarchy storage and create separate site hierarchies for each locale. See [one-hierarchy-or-many] or Multilanguage structure.

Export and import translations

The Content Translation Support module allows you to export page content to CSV or Excel, translate it, and re-import it.

  1. In the Pages app, select a page and export it using the Content Translation Support module.

  2. Translate the content in the exported CSV/Excel file.

  3. Re-import the file to update translations.

One hierarchy or many

Magnolia’s default strategy stores translations in a single JCR content node, using language-specific properties (such as subtitle_de). Alternatively, you can create separate site hierarchies for each locale for region-specific structures. See Multilanguage structure for guidance on choosing a strategy.

Serve localized URLs

Magnolia serves translated content at language-specific URLs, such as mysite.com/de/welcome.html.

Configure language-specific URLs

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

server:
  i18n:
    system:
    content:
      enabled: true
      class: info.magnolia.module.site.i18n.SiteI18nContentSupport
    authoring:
Property Description

enabled

required, default is true

Enables multilanguage content storage and delivery.

class

required

Class that implements info.magnolia.cms.i18n.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.

Localized content is served at URLs identifying the locale:

Locale URL

Default locale

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

The HTML element on public pages identifies the language with standard lang and xml:lang attributes.

<!DOCTYPE html>
<html xml:lang="en" lang="en" class="no-js">

Redirect to localized URLs

Magnolia doesn’t redirect visitors to the localized URL automatically. Configure this behavior on your web server using strategies like:

  • Dropdown selection: Allow visitors to select a language/region.

  • IP-based detection: Redirect based on the visitor’s origin.

  • Browser settings: Detect the visitor’s preferred locale from their browser settings, then redirect them to the localized site.

UTF-8 character encoding

Magnolia supports UTF-8 character encoding for Unicode, enabling non-ASCII characters in page names and content.

To enable UTF-8 page names:

  1. For JBoss AS, add the following to standalone.xml or domain.xml 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 in Magnolia:

    magnolia.properties
    # Activate UTF-8 support to pages
magnolia.utf8.enabled=true (1)
    1 This allows non-ASCII characters in node names.
    The value must be the same on both the author and public instance. Publication between instances with a different UTF-8 setting is not supported.

Sites built using Magnolia Templating Essentials templates declare UTF-8 encoding with:

<meta charset="utf-8">

Example: Al Arabiya, an Arabic-language site built with Magnolia, uses UTF-8 for right-to-left cursive script.

Arabic language site built with Magnolia

Related Topics

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules