Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
...
Include Page | ||||
---|---|---|---|---|
|
...
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, an editor, publisher or even a sysadmin – let's refer to them with the term AdminCentral user – working with the author instance of Magnolia may have different locale preferences than the visitor. An AdminCentral user's native and hence preferred language may be, for example, Spanish but the content being edited may still be in English. 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:
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 :
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 public locale is slightly more difficult. Visitors usually access web content as anonymous users. Magnolia then has to rely on indirect means that point to the preferred locale of a visitor.
...
The new locale will be is applied the next time you login log in to the AdminCentral.
...
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:
...
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:
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 |
...
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.
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.
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
....
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.
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 n |
---|
...
Mgnl n |
---|
...
Mgnl p |
---|
...
Mgnl p |
---|
...
Mgnl p |
---|
...
Mgnl p |
---|
...
|
...
|
...
|
...
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 | |
---|---|
|
|
...
For the Accept-Language header case:
|
Javadoc resource link | ||||
---|---|---|---|---|
|
...
...
Javadoc resource link | ||||
---|---|---|---|---|
|
...
de
for example. ...
<name>_
...
<locale>
pattern exists on a content node:Javadoc resource link | ||||
---|---|---|---|---|
|
...
, for example:
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
.
...
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.
...
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
required, default is en
...
.