Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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 public user – will usually only be able to see and interact with the pages of a published web project or website. The user 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, ideally in his native language. A user who's native language is English will prefer browsing the English language version of a website (the screenshots are from the Travel Demo):
On the other hand, a Magnolia editor/publisher (user) or sysadmin – let's for now use the term system user – working with the author instance of Magnolia may have different locale preferences than the public user. A system 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 user would probably welcome if
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 site locale is slightly more difficult. Public users usually access web pages as anonymous users. Magnolia then has to rely on indirect means that point to the preferred locale of a public user.
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).
The AdminCentral locale primarily defines the language of User interface labels that the system user wants to work with in the AdminCentral, 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:
When logged-in in the AdminCentral, 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 system languages or it will fallback to English, the default fallback language but configurable.
To set it, 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:
The new locale will be applied the next time you login to the AdminCentral.
On this page by referring to site locale we mean the preferred locale rendering of a web project on a public user's device. Site locale influences the editorial content and template labels. Unless a public user registers to a web product/service and actively provides the locale information to the webapp, the webserver has to rely on other means that could help identify the visitors preferred 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 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
While occassionally containing information such as en_US
, for example in
Mozilla/5.0 (compatible; Konqueror/4.5; NetBSD 5.0.2; X11; amd64; en_US) KHTML/4.5.4 (like Gecko)
this locale information in the User-Agent
header
and more often than not is missing:
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 may take one of the following three forms:
<language>
<locale>
*
The first represents language expressed as a 2 or 3-character string, the second represents language as a full language tag, the third says "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:
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 the locale information provided in the Accept-Language
header, see DefaultI18nContentSupport
and HierarchyBasedI18nContentSupport
in the configuration section below.
The most common form of Request-URI
is that used to identify a resource on an origin server or gateway. For example:
/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:
/de/tour-type~active~.html
To configure a site in Magnolia to parse Request-URI
for locale preference, see RequestLocaleAwareI18nContentSupport
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
.Node name | Value |
---|---|
locales | |
<locale-name> | |
language | de |
country | CH |
enabled | true |
class | info.magnolia.cms.i18n.DefaultI18nContentSupport |
enabled | true |
fallbackLocale | en |
Properties
| required The minimum specification if the resolution of locale for Defines the language part of the locale parameter, for example For additional language codes see https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry. |
| optional Defines the country part of the locale parameter, for example For additinal country codes see https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry. |
| required |
class | required, default is The class that defines the locale implementation. if the class is not specified, the locale is dependent on the setting in For the Accept-Language header case:
For the Request-URI case:
|
enabled | required, default is Enables or disables the locale configuration. |
defaultLocale | optional If no locale can be determined this |
fallbackLocale | required, default is The content is served for this locale if the content is not available for the current locale or the |