Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
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 locale 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 name | Value |
---|---|
i18n | |
system | |
languages | |
zh_TW | |
country | TW |
enabled | true |
language | zh |
pt_BR | |
de | |
fr | |
fallbackLanguage | en |
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 fields.
- Define locales in the site
1. Enable multilanguage authoring
Enable multilanguage authoring in /config/server/i18n/authoring
. This allows editors to enter the same content in multiple languages.
Node name | Value |
---|---|
server | |
i18n | |
system | |
content | |
authoring | |
class | info.magnolia.cms.i18n.DefaultI18nContentSupport |
enabled | true |
Properties:
enabled | required , default is Enables multilanguage content entry. |
class | required A class that implements I18NAuthoringSupport such as:
|
2. Set i18n=true in 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.
form: tabs: - name: tabText label: Text fields: - name: title class: info.magnolia.ui.form.field.definition.TextFieldDefinition label: Title i18n: true
Node name | Value |
---|---|
modules | |
<module name> | |
dialogs | |
<dialog name> | |
form | |
tabs | |
tabText | |
fields | |
title | |
class | info.magnolia.ui.form.field.definition.TextFieldDefinition |
label | Title |
i18n | true |
3. Define locales in site
Define the languages that editors should be able to choose as locales 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.
Example: Locales en
and de
in the default site definition
Node name | Value |
---|---|
<site> | |
i18n | |
locales | |
en | |
country | |
enabled | true |
language | en |
de | |
country | |
enabled | true |
language | de |
class | info.magnolia.cms.i18n.DefaultI18nContentSupport |
enabled | true |
fallbackLocale | en |
Properties:
| required |
| required Locale name constructed from the language and country such as |
| optional , default is Enables the locale. |
| required Language code such as |
| optional Country code such as |
| required Class that implements I18nContentSupport such as:
|
| optional , default is Enables support for localized content. Used to rewrite URIs and getting nodes based on the current language. |
| optional , default is Content is served for the fallback locale if content is not available for the current locale. |
Once multilanguage content entry is enabled, the top bar in 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.
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 (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
.
Node name | Value |
---|---|
server | |
i18n | |
system | |
content | |
class | info.magnolia.module.site.i18n.SiteI18nContentSupport |
enabled | true |
authoring |
Properties:
enabled | required , default is Enables multilanguage content storage and delivery. |
class | required A class that implements I18nContentSupport such as:
|
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 name | Value |
---|---|
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>Ü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> |
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:
Enable URI encoding in your Web container configuration:
For Apache Tomcat, setURIEncoding="UTF-8"
in theConnector
section inconf/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
ordomain.xml
right after theextensions
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>
Enable Unicode support for content node and page names. Set the
magnolia.utf8.enabled
property in amagnolia.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 Magnolia Templating Essentials templates identify the encoding as UTF-8 with an HTML meta element.
<meta 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.