Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
Page History
This page describes two different types of language locale in Magnolia and how to configure Magnolia for them. The two locales influence the rendering of content in the AdminCentral and on a published page.
| Table of Contents |
|---|
What is locale
| Include Page | ||||
|---|---|---|---|---|
|
Two locales in Magnolia
The question of "two locales" is connected with the types of users who access a Magnolia instance.
An ordinary internet user, new or returning, or even an application issuing REST commands consuming content as JSON or XML via REST API – all of whom we shall call visitor for simplicity – will usually only be able to see and interact with content of a published web project or website. The visitor will be interacting with a running public instance of Magnolia and will expect that the content of each page on the site will be available in a language he can understand or defines in his request, ideally in his native language. A visitor who's whose native language is English will prefer content in English (the screenshots are from the Travel Demo):
On the other hand, a Magnolia an editor/, publisher (user) or even a sysadmin – let's for now use refer to them with the term system AdminCentral user – working with the author instance of Magnolia may have different locale preferences than the public user. A system visitor. An AdminCentral user's native and hence preferred language may be, for example, Spanish but the content being edited may still be in the English language. The system AdminCentral user would probably welcome if the following items in the author instance (see also Types of translatable text) are displayed in Spanish rather than in English:
- Field labels and descriptions,
- Messages (alerts, warnings, information),
- App UI elements such as workbenches, columns, forms and actions, and
- Buttons in the page editor in edit mode (used to open dialogs)
in the author instance (see also Types of translatable text) were displayed in Spanish rather than in English:
Magnolia has been built to deal with these two separate locale preferences, that is with :
- Public Site Locale
- AdminCentral Locale.
Determining and setting the latter is fairly straightforward since the system users will usually know which locale they prefer. They can also set the locale themselves directly in the AdminCentral or they may always ask a user with superuser rights to set the preferred locale for them.
To determine site public locale is slightly more difficult. Public users Visitors usually access web pages content as anonymous users. Magnolia then has to rely on indirect means that point to the preferred locale of a public uservisitor.
...
...
Please note that on this page, by site in Site locale we mean the preferred locale rendering of a web project on a public user's device. Be aware that in Magnolia the term site may be used in other contexts and meanings such as in Site module or website (a workspace name).
AdminCentral locale
The AdminCentral locale primarily defines the language of User interface labels that the system which the AdminCentral user wants to work interact in with in the AdminCentral. This concerns, for example, the language of labels in the Action bar (English on the left, Korean on the right):
...
An incomplete localisation of a UI element may result in displaying a label in the fallback language, as shown below in the case the Copy page and Paste page actions:
...
Setting and configuring the AdminCentral locale
When logged-in in the AdminCentral, its users may set their language locale parameter via the Language field in the Edit user profile dialog. The setting will be reflected in the names of action menus, actions, buttons and labels throughout the AdminCentral provided the locale is one of the available the available system languages or languages or it will fallback to English, the default fallback language (see also the configuration of available system languages and fallback language but configurableconfiguration).
To set itthe locale of the AdminCentral, open the pull down menu in the top right corner of the browser window and click the first row of the menu, titled Edit user profile if the current locale setting is English. On the Preferences tab:
- Choose a language in the Language field:
With the superuser role you may can set language locales for other users, see how at Setting an editor's language preference.
The new locale will be is applied the next time you login log in to the AdminCentral.
...
Public locale
Again, by site locale we refer to the preferred locale rendering of a web project on a public user's device. Site locale Public locale influences the editorial content and template labels rendered on the a visitor's device. Unless a public user visitor registers to a web product /or service and actively provides the preferred locale information to the webapp, the webserver public instance has to rely on other means that help identify the visitors visitor's preferred locale.
Determining the preferred
...
public locale
There are a number of ways of obtaining some form of locale information. Some of them use advanced techniques such as geolocation based on ping delay or topology, but one of the most common way ways is to look into the content of an HTTP request. At least the following three parts of an HTTP request are relevant to the identification of the public user's locale:
- the
User-Agentheader - the
Accept-Languageheader Request-URI
From the User-Agent header
While occassionally containing The header may contain information such as en_US , for example in :
| Code Block |
|---|
Mozilla/5.0 (compatible; Konqueror/4.5; NetBSD 5.0.2; X11; amd64; en_US) KHTML/4.5.4 (like Gecko) |
However, this locale information in the User-Agent header:
- identifies Identifies the language variant of the software sending the request rather than the user's preferred locale, .
- is Is usually redundant,.
and more Is often than not is missing:
Code Block Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36
Magnolia has no ready-made means how to check for the existence of and retrieve this type of locale information. The preferred locale information is communicated via the Accept-Language header.
From the Accept-Language header
The Accept-Language request header of an HTTP request defines which language variant of the page is preferred by the public user. This locale information may take one of the following three forms:
...
The first represents language expressed as a 2 or 3-character string, the second represents language as a full language tag, the third says means "any language" (see Accept-Language and Language Tags in RFC-2616).
Additionally, the locale value that is sent in the header – optionally in a semicolon-delimited range for more languages – may be given an associated quality value ( q=<qvalue>). The quality value represents an estimate of the user's preference for the languages specified by that range, for example:
| Code Block |
|---|
Accept-Language: cs-CZ,cs;q=0.9,en-US;q=0.8,en;q=0.7 |
A site in Magnolia may be configured to reflect In Magnolia the locale information provided in the Accept-Language header , see RequestLocaleAwareI18nContentSupport in the configuration section belowcan be handled by the RequestLocaleAwareI18nContentSupport implementation of the I18nContentSupport interface, see below in The I18nContentSupport interface subsection.
From Request-URI
The most common form of Request-URI is that used to identify a resource on an origin server or gateway. For example:
...
| Code Block |
|---|
/de/tour-type~active~.html |
To configure a site in Magnolia to parse Request-URI for locale preference, see DefaultI18nContentSupport and HierarchyBasedI18nContentSupport in the configuration section below.
Configuring locale for a site
The configuration that defines the locale information for a site is usually located:
- In the Enterprise Edition under
/modules/multisite/config/sites/<site-name>/i18n/locales - In the Community Edition under
/site/config/site/<site-name>/i18n/locales
In the CE's Travel Demo bundle the configuration is extended from/modules/travel-demo/config/travel.
...
| heading | 0 |
|---|---|
| multiple | false |
| enableHeadingAttributes | false |
| enableSorting | false |
| class | m5-configuration-tree |
| enableHighlighting | false |
In Magnolia the locale information provided in the Request-URI can be handled by DefaultI18nContentSupport and HierarchyBasedI18nContentSupport implementations of the I18nContentSupport interface, see the details in the following subsection.
The I18nContentSupport interface
...
| Mgnl n |
|---|
...
| Mgnl n |
|---|
...
| Mgnl p |
|---|
...
| Mgnl p |
|---|
...
| Mgnl p |
|---|
...
| Mgnl p |
|---|
When determining the preferred public locale, a key role in deciding which approach to apply is played by the
| Javadoc resource link | ||||
|---|---|---|---|---|
|
/server/i18n/content . The entry point to this interface is via the | Javadoc resource link | |
|---|---|
|
|
...
|
...
|
...
| Mgnl p |
|---|
...
Properties
...
language
...
required
The minimum locale specification if the resolution of locale set under <locale-name> is enabled.
Defines the language part of the locale parameter, for example uk for Ukrainian.
For additional language codes see https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry.
...
country
...
optional
Defines the regional variant of the locale parameter, for example GB for the United Kingdom.
For additinal country codes see https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry.
...
enabled
...
required
true enables the detection of locale for the configuration defined under <locale-name> .
...
|
/server/filters/i18n ). The I18nContentSupport interface has the following implementations:...
Javadoc resource link className
info.magnolia.cms.i18n.
...
– an abstract implementation. The detection of the current locale is left to one of the following three classes.AbstractI18nContentSupport renderType asynchronous
...
Javadoc resource link className info.magnolia.cms.i18n.RequestLocaleAwareI18nContentSupport renderType asynchronous
...
- – relevant to the From the Accept-Language header case described above, this implementation reads the locale from the Accept-Language header. This implementation does not render language specific URIs (see the classes below).
For the Request-URI case:
Javadoc resource link className info.magnolia.cms.i18n.DefaultI18nContentSupport renderType asynchronous
...
- – relevant to the From Request-URI case described above and used in the Magnolia Travel Demo, this implementation supports a language prefix in the URI, such as
defor example.
...
- It checks if a node data with the
<name>_
...
<locale>pattern exists on a content node:
Same as above but for a hierarchyJavadoc resource link className info.magnolia.cms.i18n.HierarchyBasedI18nContentSupport renderType asynchronous
...
, for example:
Code Block my-website ├─en │ ├─page-1 │ └─page-n ├─de │ ├─page-1 │ └─page-n └─de_CH ├─page-1 └─page-nThe locale code can be at whatever position in the URI, not necessarily the first one. For example,
/my-website/node-1/node-2/de/home-page.html.
...
required, default is false
Enables or disables the locale configuration.
...
optional
If no locale can be determined, this defaultLocale will be set. If unset, the fallbackLocale will be used.
...
Configuring locale for a site
The configuration that defines the locale information for a site is usually located:
- In the Enterprise Edition under
/modules/multisite/config/sites/<site-name>/i18n/locales - In the Community Edition under
/site/config/site/<site-name>/i18n/locales
In the CE's Travel Demo bundle the configuration is extended from/modules/travel-demo/config/travel.
For further details about configuring locale for a site, please see Language configuration: 3. Define locales in site
required, default is en
...
.
Overview
Content Tools