document how to override the language negotiation/redirect

Author: erral

docs/i18n-l10n/index.md

@@ -62,7 +62,7 @@ language tag
 :   A language tag is a string used as an identifier for a language.
     A language tag may have one or more subtags.
     The basic form of a language tag is `LANGUAGE-[SUBTAG]`.
-    
+
     ```{seealso}
     -   W3C article [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/)
     -   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
 
 translating-text-strings
 language-negotiation
+language-negotiation-volto
 translating-content
 contributing-translations
 resync-translations

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

@@ -0,0 +1,34 @@
+---
+myst:
+  html_meta:
+    "description": "Accessing and changing the language state of Plone programmatically."
+    "property=og:description": "Accessing and changing the language state of Plone programmatically."
+    "property=og:title": "Language negotiation in Volto"
+    "keywords": "Plone, Internationalization, i18n, language, negotiation, translation, localization, volto"
+---
+
+(language-negotiation-volto-label)=
+
+# Language negotiation in Volto
+
+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.
+
+Volto has in its own configuration a setting stating whether a site is multilingual or not: `isMultilingual`.
+
+First of all, you need to set that setting to `true`.
+
+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.
+
+As a last thing, you need to set your site's `defaultLanguage` to one of the `supportedLanguages`.
+
+When all these settings are configured, Volto's [MultilingualRedirector](https://github.com/plone/volto/blob/master/src/components/theme/MultilingualRedirector/MultilingualRedirector.jsx) will handle the language negotiation and the redirect.
+
+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.
+
+After that it does the redirection to the matched Language Root Folder.
+
+If the site is not configured to be multilingual, Volto doesn't do any redirect.
+
+## Overriding the default behavior
+
+To do so, you need to provide your own `MultilingualRedirector` component [customizing it](https://6.docs.plone.org/volto/recipes/customizing-components.html).

docs/i18n-l10n/language-negotiation.md

@@ -3,13 +3,13 @@ myst:
   html_meta:
     "description": "Accessing and changing the language state of Plone programmatically."
     "property=og:description": "Accessing and changing the language state of Plone programmatically."
-    "property=og:title": "Language negotiation"
+    "property=og:title": "Language negotiation in Classic UI"
     "keywords": "Plone, Internationalization, i18n, language, negotiation, translation, localization"
 ---
 
 (language-negotiation-label)=
 
-# Language negotiation
+# Language negotiation in Classic UI
 
 ```{todo}
 This section may contain incorrect information.
@@ -19,7 +19,7 @@ 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.
+Plone Classic UI 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.
 
 
@@ -91,8 +91,17 @@ This language switcher will only rely on the user preferred language to decide w
 
 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 `@@language-switcher` view.
 -   They may write their own view, and configure the ZMI.
     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`.
     Set the value of `Default view method` to the name of the view.
+
+
+## Changing the default behavior
+
+If for any reason you want to change the default behavior set when using `plone.app.multilingual`, you have 2 options:
+
+1- Override the `language-switcher` view. 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. You can override this view using the usual techniques to provide your own implementation.
+
+2- Create a new view: 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. To do so, you may need to provide your own installation profile with a `Plone Site.xml` file and with the proper configuration.