Improve Language Negotiation

- Clarify what needs to be done in TODOs
- Clean up Introduction
- Add labels
- Fix heading levels
- Fix MyST and English syntax and markup
- One sentence per line
- Verify GUI labels, add screenshots

Author: stevepiercy

docs/_static/i18n-l10n/language-controlpanel-general.png

@@ -10,49 +10,91 @@ html_meta:
 
 # Language negotiation
 
-```{note}
-TODO: rework this section.
+```{todo}
+This section may contain incorrect information.
+If you find errors, please submit a pull request to correct them.
 ```
 
 ```{admonition} Description
 Accessing and changing the language state of Plone programmatically.
 ```
 
+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.
 
-## Introduction
+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.
 
-Language negotiation is a function of the HTTP protocol which lets a server choose among several language versions of a page, based on the URL and on preference information sent by the browser.
 
-Plone uses specific negotiation rules to negotiate the language in which provides the user interface to the end user. In any case, we have to distinguish two different cases here: when plone.app.multilingual is enabled and when not
+(language-negotiation-plone.app.multilingual-is-not-enabled-label)=
 
-### plone.app.multilingual is not enabled
+## `plone.app.multilingual` is not enabled
 
-When the referenced product is not installed but the Site Administrator configures multiple languages in Plone, Plone assumes that the user only wants to allow to change the user interface language. 
+When `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.
 
-This means that the language change links on the top of the page will only have effect in the user interface presented to the user. For example: search form options, editing interface messages, portal message statuses, ...
+By visiting the URI `@@language-controlpanel` ({guilabel}`Site Setup > General > Language`), the site administrator may configure language options for the site.
 
-Going to the @@language-controlpanel the site administrator has multiple options with which can influence the working of the site. 
+```{image} /_static/i18n-l10n/language-controlpanel-general.png
+:alt: Language Control Panel, General
+```
+
+```{todo}
+Should we document all the options?
+Currently this is incomplete.
+```
+
+```{todo}
+The next sentence might not be true.
+When I toggled it, nothing changed.
+Does it actually do anything?
+```
+
+By default, the {guilabel}`Always show language selector` option is not enabled, but it is required if the user wants to offer the language change in the interface.
 
-For instance, 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. Goingo to the "Negotiation scheme" in the same configuration page, the Site Administrator can influence how Plone will decide which language to present to each user. 
+By selecting the {guilabel}`Negotiation scheme` tab, the site administrator can configure how Plone will select a language to present to each user.
+
+```{image} /_static/i18n-l10n/language-controlpanel-negotiation-scheme.png
+:alt: Language Control Panel, Negotiation scheme
+```
 
-For instance, if the site is being presented in a subfolder with the language code (think of www.domain.com/en) or in subdomain (think of en.domain.com), Plone can be configured to take that subfolder or domain language code and select that language to present to the 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 browser (which previously can be configured to set the list of the wanted languages in rank of preference). For example a user can configure her browser to request pages in German (de), French (fr), and English (en). In such a case Plone will compare Plone's language list with the user requirements, and will decide in which language to present the site.
+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 `LanguageUtility` which lies in `plone.i18n.utility.py`.
+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`.
 
-Plone also sets a language cookie with the language preference of the user. This cookie called `I18N_LANGUAGE` must be declared as a `Technical Cookie` and is a session cookie, which means that will be deleted after the user has leave the site. To obey the cookie the setting "Use cookie for manual override" should be set along with the "Set cookie for manual override".
+Plone also sets a cookie with the language preference of the user.
+This cookie is called `I18N_LANGUAGE`.
+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, {guilabel}`Use cookie for manual override` should be set along with {guilabel}`Set the language cookie always`.
 
-In any case, building websites with user interfaces in multiple languages is a hard work due to the different expectations of the users and the difficulty of the configuration.
+Building websites with user interfaces in multiple languages is complicated due to the different expectations of the users and the difficulty of the configuration.
 
-### plone.app.multilingual is enabled
 
-When plone.app.multilingual is enabled, Plone creates the so called `Language Root Folder`s (LRFs for short) for each of the languages, so the language negotiation only applies for the users visiting the root domain of the site.
+(language-negotiation-plone.app.multilingual-is-enabled-label)=
 
-For example, if 'en' and 'es' are enabled, Plone will create www.domain.com/en and www.domain.com/es, and Plone will assume that all the content below 'en' is in English and all content below 'es' is in Spanish, so it will rely on that assumption to present the user interface in those languages when the user is browsing those parts of the site.
+## `plone.app.multilingual` is enabled
 
-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.multilngual.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.
+When `plone.app.multilingual` is enabled, Plone creates the `Language Root Folder`s (LRFs) for each of the languages.
+Thus, the language negotiation only applies for the users visiting the root domain of the site.
 
-If an integrator wants to modify this behavior to always send a user to a given language, or wants to negotiate the language selection in some other way (using the domain, a cookie, or some other techniques), she will have to override that `@@language-swicher` view, or will have to write her own view and set it as the `default view method` in the `Plone Site` object configuration in `www.domain.com/portal_types/Plone Site/manage_workspace`
+For example, if `en` and `es` are enabled, Plone will create `www.domain.com/en` and `www.domain.com/es`.
+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 {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`.
+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 `@@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.