Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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 |
---|
Include Page | ||||
---|---|---|---|---|
|
The Typically, Magnolia runs on two instances, the author instance and the public instance and the question of "two locales" is connected with the types of users who access a Magnolia instance.
An ordinary internet user, new or returning – whom we can call a public user , or even an application 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 the pages content of a published web project or website. The user visitor will be interacting – via the web browser – 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. For example, a user who's A visitor whose native language is English will prefer browsing the English language version of a website 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 just simplify these roles to a system user – working refer to them with the term AdminCentral user – working with the author instance of Magnolia may have different locale preferences than the public user. For example, 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. Such an editor . The 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:
...
...
Magnolia has been built to deal with these two separate locale preferences, that is with :
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 ask a user with superuser rights to set the preferred locale for them.
Determining the locale for a site is less transparent since public users To determine public locale is more difficult. Visitors usually access web pages content as anonymous users. Magnolia then has to rely on indirect means that point to the preferred locale of public usersa visitor.
The AdminCentral locale primarily sets defines the language of User interface labels that the which the AdminCentral user of AdminCentral wants to see and work with, such as interact in with the AdminCentral. This concerns, for example, the language of labels in the Action bar (English on the left, Korean on the right):
AdminCentral's time zone setting, on the other hand, has an effect on the content of – for instance – the date field before any date is entered in it. The field shows a pseudo-placeholder text that changes according to the actual (user's) time zone setting, compare:
Surely, two different English-speaking editors, one working in London and the other one working in Berlin, will want to use their local times in many instances of such a field. In addition, the form of the timezone placeholder depends not only the time zone setting, but also on the language setting described just above. If the preferred working language of one of the editors is set to German, the hint will show MEZ (abbrev. of Mitteleuropäische Zeit) instead of CET (abbrev. of Central European Time).
...
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:
When logged-in in the AdminCentral, its users may set their language locale parameter via the Language and Time zone fields field in the Edit user profile dialog. The language part of the locale 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 system languages (see further below) or the available system languages or it will fallback to English. , the default fallback language (see also the configuration of available system languages and fallback language configuration).
To set a the 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 timezone in the Time zone field.
The new locale will be is applied the next time you log in into to the AdminCentral.
...
The setting of site Public locale influences the editorial content and template labels rendered on a visitor's device. Unless a visitor registers to a product or service and actively provides the preferred locale information, the public instance has to rely on other means that help identify the visitor's preferred locale.
...
There are a number of ways of obtaining locale information. Some of them use advanced techniques such as geolocation based on ping delay or topology, but one of the most common 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:
User-Agent
headerAccept-Language
headerRequest-URI
The header may contain information such as en_US
, for example:
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:
Is often 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.
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 The Public instance delivers the final page to a page visitor, and tries to deliver it in a way that fulfills the content of the HTTP request for the page. A part of the HTTP request's header defines which languages the visitor (client) is able to understand, and which locale variant of the page is preferred. The part that does this is the Accept-Language
request header and 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 |
In Magnolia the locale information provided in the Accept-Language
header can be handled by the RequestLocaleAwareI18nContentSupport
implementation of the I18nContentSupport
interface, see below in The I18nContentSupport interface subsection.
The most common form of Request-URI
is that used to identify a resource on an origin server or gateway. For example:
Code Block |
---|
/tour-type~active~.html |
The preferred locale information may be sent to the server as a part of a Request-URI
, such as de
in the following example:
Code Block |
---|
/de/tour-type~active~.html |
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.
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 | ||||
---|---|---|---|---|
|
/server/filters/i18n
). The I18nContentSupport
interface has the following implementations:Javadoc resource link | ||||
---|---|---|---|---|
|
Javadoc resource link | ||||
---|---|---|---|---|
|
Javadoc resource link | ||||
---|---|---|---|---|
|
de
for example. It checks if a node data with the <name>_<locale>
pattern exists on a content node:Javadoc resource link | ||||
---|---|---|---|---|
|
Code Block |
---|
my-website
├─en
│ ├─page-1
│ └─page-n
├─de
│ ├─page-1
│ └─page-n
└─de_CH
├─page-1
└─page-n |
The 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
.
The configuration that defines the locale information for a site is usually located:
/modules/multisite/config/sites/<site-name>/i18n/locales
/site/config/site/<site-name>/i18n/locales
/modules/travel-demo/config/travel
.For further details about configuring locale for a site, please see Language configuration: 3. Define locales in site.