This section may contain incorrect information. If you find errors, please submit a pull request to correct them.
Language negotiation is a function of the HTTP protocol. It lets a server choose among several language versions of a page based on the URL and preference information sent by the browser.
Plone uses specific rules to select the language in which the user interface is presented to the end user.
There are two distinct use cases: when
plone.app.multilingual is not enabled and when it is.
plone.app.multilingual is not enabled#
plone.app.multilingual is not installed, but the site administrator configures multiple languages in Plone, Plone only allows changing the language of the user interface.
This means that the language chooser links on the top of the page will only have effect for the user interface elements presented to the user.
These user interface elements may include search form options, editing interface messages, portal message statuses, and so on.
By visiting the URI
@@language-controlpanel (Site Setup > General > Language), the site administrator may configure language options for the site.
Should we document all the options? Currently this is incomplete.
The next sentence might not be true. When I toggled it, nothing changed. Does it actually do anything?
By default, the Always show language selector option is not enabled, but it is required if the user wants to offer the language change in the interface.
By selecting the Negotiation scheme tab, the site administrator can configure how Plone will select a language to present to each user.
For instance, if the site is being presented in a sub-folder (
www.domain.com/en) or in a subdomain (
en.domain.com), with either example using a language code such as
en, then Plone can be configured to take that sub-folder or subdomain as the language code, and select that language to present to the user.
Another common configuration is to use the browser language request negotiation.
This means that Plone relies on the
Accept-Language HTTP header sent by the user's browser.
The user can configure the list of languages to use in their preferred order, such as in German (de), French (fr), and English (en).
In this scenario, Plone will compare its language list with the user's preferences, and will determine in which language to present the site.
The exact working of each of the negotiation options is implemented in the class
LanguageUtility in the module
utility.py in the package
Plone also sets a cookie with the language preference of the user.
This cookie is called
It must be declared as a "technical cookie".
It is a session cookie, which means that it will be deleted after the user leaves the site.
To obey the cookie the setting, Use cookie for manual override should be set along with Set the language cookie always.
Building websites with user interfaces in multiple languages is complicated due to the different expectations of the users and the difficulty of the configuration.
As we will see in the (translating-content-label)= section, Plone will set a special view for the Plone root object called
@@language-switcher whose implementation lies on
plone.app.multilingual.browser.switcher.LanguageSwitcher. This language switcher will only rely on the user preferred language to decide where to send the user when she visits the root of the site.
plone.app.multilingual is enabled#
plone.app.multilingual is enabled, Plone creates the
Language Root Folders (LRFs) for each of the languages.
Thus, the language negotiation only applies for the users visiting the root domain of the site.
For example, if
es are enabled, Plone will create
Plone will assume that all the content below
en is in English, and all content below
es is in Spanish.
It will rely on that assumption to present the user interface in those languages when the user is browsing those parts of the site.
As we will see in the Translating content chapter, Plone will set a special view for the Plone root object called
@@language-switcher whose implementation relies on
This language switcher will only rely on the user preferred language to decide where to send the user when they visit the root of the site.
An integrator may want to modify this behavior to always send a user to a given language, or to negotiate the language selection in some other way, such as using the domain, a cookie, or some other techniques. As such, there are two options.
They may override the
They may write their own view, and configure the ZMI. To configure the ZMI, visit
www.domain.com/portal_types/Plone%20Site/manage_propertiesFormor navigate there as an Admin user, username > Site Setup, Advanced > Management Interface, portal_types, and finally Plone Site. Set the value of
Default view methodto the name of the view.