From 5d08c67345f5d5d1cbb1d9d0a744e193fbe247ce Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 28 Aug 2023 08:27:56 +0200 Subject: [PATCH 1/5] document how to override the language negotiation/redirect --- docs/i18n-l10n/index.md | 3 +- docs/i18n-l10n/language-negotiation-volto.md | 34 ++++++++++++++++++++ docs/i18n-l10n/language-negotiation.md | 17 +++++++--- 3 files changed, 49 insertions(+), 5 deletions(-) create mode 100644 docs/i18n-l10n/language-negotiation-volto.md diff --git a/docs/i18n-l10n/index.md b/docs/i18n-l10n/index.md index 52f941942..58c3cf7cc 100644 --- a/docs/i18n-l10n/index.md +++ b/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 diff --git a/docs/i18n-l10n/language-negotiation-volto.md b/docs/i18n-l10n/language-negotiation-volto.md new file mode 100644 index 000000000..f0efb57a9 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/i18n-l10n/language-negotiation.md b/docs/i18n-l10n/language-negotiation.md index f118bb150..1681fb763 100644 --- a/docs/i18n-l10n/language-negotiation.md +++ b/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. From 5fc218edbd23ac527fb17ff60c58110bd2ed8673 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 5 Oct 2023 16:28:50 +0200 Subject: [PATCH 2/5] Use internal reference --- docs/i18n-l10n/language-negotiation-volto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/i18n-l10n/language-negotiation-volto.md b/docs/i18n-l10n/language-negotiation-volto.md index f0efb57a9..d51d8162f 100644 --- a/docs/i18n-l10n/language-negotiation-volto.md +++ b/docs/i18n-l10n/language-negotiation-volto.md @@ -31,4 +31,4 @@ 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). \ No newline at end of file +To do so, you need to provide your own `MultilingualRedirector` component {doc}`customizing it `. From eb91e04f9141e3f1ff2c568539e45712867cc563 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 5 Oct 2023 16:31:49 +0200 Subject: [PATCH 3/5] Minor grammar and MyST syntax --- docs/i18n-l10n/language-negotiation-volto.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/i18n-l10n/language-negotiation-volto.md b/docs/i18n-l10n/language-negotiation-volto.md index d51d8162f..2e610c81c 100644 --- a/docs/i18n-l10n/language-negotiation-volto.md +++ b/docs/i18n-l10n/language-negotiation-volto.md @@ -13,7 +13,7 @@ myst: 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`. +Volto has a setting in its own configuration stating whether a site is multilingual or not: `isMultilingual`. First of all, you need to set that setting to `true`. @@ -21,7 +21,7 @@ Then you need to add the list of supported languages to the `supportedLanguages` 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. +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. From f223cf9e820a2ec450c04243e9cd5afd5eebead1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 5 Oct 2023 16:40:58 +0200 Subject: [PATCH 4/5] Fix some typos, grammar, MyST issues --- docs/i18n-l10n/language-negotiation.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/i18n-l10n/language-negotiation.md b/docs/i18n-l10n/language-negotiation.md index 1681fb763..a196cf382 100644 --- a/docs/i18n-l10n/language-negotiation.md +++ b/docs/i18n-l10n/language-negotiation.md @@ -60,7 +60,7 @@ For instance, if the site is being presented in a sub-folder (`www.domain.com/en 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). +The user can configure the list of languages to use in their preferred order, such as 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`](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. 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`. +To obey the cookie setting, {guilabel}`Use cookie for manual override` should be set along with {guilabel}`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. +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`. +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. + (language-negotiation-plone.app.multilingual-is-enabled-label)= @@ -86,7 +88,7 @@ For example, if `en` and `es` are enabled, Plone will create `www.domain.com/en` 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`. +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`. 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. @@ -100,8 +102,12 @@ As such, there are two options. ## 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: +If for any reason you want to change the default behavior set when using `plone.app.multilingual`, you have two 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. +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. +1. 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 {file}`Plone Site.xml` file and with the proper configuration. From 0e5b94f7aa14777090d8c771cc7c8bfe975b7d7c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 5 Oct 2023 18:05:44 +0200 Subject: [PATCH 5/5] Fix link after renaming branch --- docs/i18n-l10n/language-negotiation-volto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/i18n-l10n/language-negotiation-volto.md b/docs/i18n-l10n/language-negotiation-volto.md index 2e610c81c..203fdf68e 100644 --- a/docs/i18n-l10n/language-negotiation-volto.md +++ b/docs/i18n-l10n/language-negotiation-volto.md @@ -21,7 +21,7 @@ Then you need to add the list of supported languages to the `supportedLanguages` 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. +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. 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.