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 (Apps > Security).
Select the user profile you wish to edit.
Click Edit user.
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.
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:
Enable multilanguage authoring.
Set i18n=true:
In form fields.
On content type properties.
Define locales for the site.
Enable multilanguage authoring in /server/i18n/authoring. This allows editors to enter the same content in multiple languages.
A class that implements info.magnolia.ui.api.i18n.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: Multilanguage content is enabled for the title text field.
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
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.
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.
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, the tab approach works
well. The default approach works with any number of languages while
keeping UI changes minimal.
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 /server/i18n/content.
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. 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 default locale (defaultLocale) on this site, no _en suffix is used.
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:
For JBoss AS, add the following section in standalone.xml or domain.xml right after the extensions section.
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)Copy
1
This allows you to use a variety of 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 identify the encoding as UTF-8 with an HTML meta element.
<metacharset="utf-8">Copy
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.