Skip to content

Commit a43cecc

Browse files
stevepiercystevepiercy
authored
Merge pull request #1528 from plone/erral-language-redirect-documentation
document how to override the language negotiation/redirect
2 parents 17967e5 + 0e5b94f commit a43cecc

File tree

3 files changed

+59
-9
lines changed

3 files changed

+59
-9
lines changed

‎docs/i18n-l10n/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ language tag
6262
: A language tag is a string used as an identifier for a language.
6363
A language tag may have one or more subtags.
6464
The basic form of a language tag is `LANGUAGE-[SUBTAG]`.
65-
65+
6666
```{seealso}
6767
- W3C article [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/)
6868
- W3C Working Draft [Language Tags and Locale Identifiers for the World Wide Web](https://www.w3.org/TR/ltli/)
@@ -145,6 +145,7 @@ These differences depend upon the programming language, either Python or JavaScr
145145
146146
translating-text-strings
147147
language-negotiation
148+
language-negotiation-volto
148149
translating-content
149150
contributing-translations
150151
resync-translations

‎docs/i18n-l10n/language-negotiation-volto.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "Accessing and changing the language state of Plone programmatically."
5+
"property=og:description": "Accessing and changing the language state of Plone programmatically."
6+
"property=og:title": "Language negotiation in Volto"
7+
"keywords": "Plone, Internationalization, i18n, language, negotiation, translation, localization, volto"
8+
---
9+
10+
(language-negotiation-volto-label)=
11+
12+
# Language negotiation in Volto
13+
14+
Volto does not rely on the configuration set in Plone's Language Control Panel to handle the redirection from the root of the site to the Language Root Folder.
15+
16+
Volto has a setting in its own configuration stating whether a site is multilingual or not: `isMultilingual`.
17+
18+
First of all, you need to set that setting to `true`.
19+
20+
Then you need to add the list of supported languages to the `supportedLanguages` setting, and match them with the languages configured in Plone's Language Control Panel.
21+
22+
As a last thing, you need to set your site's `defaultLanguage` to one of the `supportedLanguages`.
23+
24+
When all these settings are configured, Volto's [`MultilingualRedirector`](https://github.com/plone/volto/blob/main/src/components/theme/MultilingualRedirector/MultilingualRedirector.jsx) will handle the language negotiation and the redirect.
25+
26+
In its configuration, the component tries to match the `I18N_LANGUAGE` cookie set in the user's browser with the list of supported languages, and if the match does not succeed, it selects the default language configured in Volto.
27+
28+
After that it does the redirection to the matched Language Root Folder.
29+
30+
If the site is not configured to be multilingual, Volto doesn't do any redirect.
31+
32+
## Overriding the default behavior
33+
34+
To do so, you need to provide your own `MultilingualRedirector` component {doc}`customizing it </volto/recipes/customizing-components>`.

‎docs/i18n-l10n/language-negotiation.md

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@ myst:
33
html_meta:
44
"description": "Accessing and changing the language state of Plone programmatically."
55
"property=og:description": "Accessing and changing the language state of Plone programmatically."
6-
"property=og:title": "Language negotiation"
6+
"property=og:title": "Language negotiation in Classic UI"
77
"keywords": "Plone, Internationalization, i18n, language, negotiation, translation, localization"
88
---
99

1010
(language-negotiation-label)=
1111

12-
# Language negotiation
12+
# Language negotiation in Classic UI
1313

1414
```{todo}
1515
This section may contain incorrect information.
@@ -19,7 +19,7 @@ If you find errors, please submit a pull request to correct them.
1919
Language negotiation is a function of the HTTP protocol.
2020
It lets a server choose among several language versions of a page based on the URL and preference information sent by the browser.
2121

22-
Plone uses specific rules to select the language in which the user interface is presented to the end user.
22+
Plone Classic UI uses specific rules to select the language in which the user interface is presented to the end user.
2323
There are two distinct use cases: when `plone.app.multilingual` is not enabled and when it is.
2424

2525

@@ -60,7 +60,7 @@ For instance, if the site is being presented in a sub-folder (`www.domain.com/en
6060

6161
Another common configuration is to use the browser language request negotiation.
6262
This means that Plone relies on the `Accept-Language` HTTP header sent by the user's browser.
63-
The user can configure the list of languages to use in their preferred order, such as in German (de), French (fr), and English (en).
63+
The user can configure the list of languages to use in their preferred order, such as German (de), French (fr), and English (en).
6464
In this scenario, Plone will compare its language list with the user's preferences, and will determine in which language to present the site.
6565

6666
The exact working of each of the negotiation options is implemented in the class [`LanguageUtility`](https://github.com/plone/plone.i18n/blob/fc05eb4c131574fd8a4353d5346e17866b3a5e2c/plone/i18n/utility.py#L73) in the module `utility.py` in the package `plone/plone.i18n`.
@@ -69,11 +69,13 @@ Plone also sets a cookie with the language preference of the user.
6969
This cookie is called `I18N_LANGUAGE`.
7070
It must be declared as a "technical cookie".
7171
It is a session cookie, which means that it will be deleted after the user leaves the site.
72-
To obey the cookie the setting, {guilabel}`Use cookie for manual override` should be set along with {guilabel}`Set the language cookie always`.
72+
To obey the cookie setting, {guilabel}`Use cookie for manual override` should be set along with {guilabel}`Set the language cookie always`.
7373

7474
Building websites with user interfaces in multiple languages is complicated due to the different expectations of the users and the difficulty of the configuration.
7575

76-
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.
76+
As we will see in the {doc}`translating-content` chapter, Plone will set a special view for the Plone root object called `@@language-switcher` whose implementation relies on `plone.app.multilingual.browser.switcher.LanguageSwitcher`.
77+
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.
78+
7779

7880
(language-negotiation-plone.app.multilingual-is-enabled-label)=
7981

@@ -86,13 +88,26 @@ For example, if `en` and `es` are enabled, Plone will create `www.domain.com/en`
8688
Plone will assume that all the content below `en` is in English, and all content below `es` is in Spanish.
8789
It will rely on that assumption to present the user interface in those languages when the user is browsing those parts of the site.
8890

89-
As we will see in the {ref}`translating-content-label` chapter, Plone will set a special view for the Plone root object called `@@language-switcher` whose implementation relies on `plone.app.multilngual.browser.switcher.LanguageSwitcher`.
91+
As we will see in the {doc}`translating-content` chapter, Plone will set a special view for the Plone root object called `@@language-switcher` whose implementation relies on `plone.app.multilingual.browser.switcher.LanguageSwitcher`.
9092
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.
9193

9294
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.
9395
As such, there are two options.
94-
96+
9597
- They may override the `@@language-switcher` view.
9698
- They may write their own view, and configure the ZMI.
9799
To configure the ZMI, visit `www.domain.com/portal_types/Plone%20Site/manage_propertiesForm` or navigate there as an Admin user, {guilabel}`username > Site Setup`, {guilabel}`Advanced > Management Interface`, {guilabel}`portal_types`, and finally {guilabel}`Plone Site`.
98100
Set the value of `Default view method` to the name of the view.
101+
102+
103+
## Changing the default behavior
104+
105+
If for any reason you want to change the default behavior set when using `plone.app.multilingual`, you have two options.
106+
107+
1. Override the `language-switcher` view.
108+
Plone has a view called `language-switcher` defined in [plone.app.multilingual.browser.switcher.py](https://github.com/plone/plone.app.multilingual/blob/master/src/plone/app/multilingual/browser/switcher.py) which handles the redirection from the root of the Plone site to the proper Language Root Folder.
109+
You can override this view using the usual techniques to provide your own implementation.
110+
111+
1. Create a new view.
112+
You can create your own view with your own implementation, configure it properly, and then set it as a `default view` for `Plone Site` objects.
113+
To do so, you may need to provide your own installation profile with a {file}`Plone Site.xml` file and with the proper configuration.

0 commit comments

Comments
 (0)