Merge branch '6-dev' into MrTango-views-templates

Author: stevepiercy

.github/workflows/build_deploy.yml

@@ -20,6 +20,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -q -r requirements.txt
+          pip freeze
 
       # - name: Run spellcheck
       #   run: make spellcheck

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

@@ -480,5 +480,4 @@ interface
     ```{seealso}
     See also https://zopeinterface.readthedocs.io/en/latest/.
     ```
-    
 ```

docs/_static/i18n-l10n/language-controlpanel-negotiation-scheme.png

@@ -0,0 +1,85 @@
+---
+myst:
+  html_meta:
+    "description": "How to contribute to Plone core translations."
+    "property=og:description": "How to contribute to Plone core translations."
+    "property=og:title": "Contributing Plone Core Translations"
+    "keywords": "Plone, Internationalization, i18n, language, translation, localization"
+---
+
+(contributing-plone-core-translations-label)=
+
+# Contributing Plone Core Translations
+
+```{admonition} Description
+How to contribute to the Plone translations.
+```
+
+This chapter of the documentation describes how to contribute to Plone's translations.
+Plone fully supports {term}`internationalization` and {term}`localization`.
+Plone Classic UI comes with 65 local language translations, and the new default frontend Volto comes with 12, at the time of this writing.
+However, some translations are incomplete, or certain languages have not yet been added.
+Translations can be added or updated as needed by the citizens of Earth.
+You will need to work in one repository for Plone core, and optionally another one for Volto.
+
+
+(contributing-plone-core-translations-pre-requisites-label)=
+
+## Pre-requisites
+
+Request write access to https://github.com/collective/plone.app.locales to be able to commit your translation directly.
+
+To do so, [join the collective GitHub organization](https://collective.github.io/).
+
+Optionally sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement) for translating Volto.
+
+
+(contributing-plone-core-translations-translate-plone-classic-ui-label)=
+
+## Translate Plone Classic UI
+
+The process of translating Plone Classic UI is the following.
+
+1.  Go to https://github.com/collective/plone.app.locales and clone it into your computer.
+
+2.  Create a new branch to work on your translations.
+    Name the branch with something identifiable.
+    For example: `{language}-{date}` (`fr-20220731`).
+
+3.  Either update or create a translation.
+
+    -   To _update_ an existing translation, translate the {term}`PO file`s under your language of choice at `plone/app/locales/locales/{language_code}/LC_MESSAGES/*.po`.
+    In Classic UI, we have several language files because some of the original messages are spread over several language domains and products.
+    -   To _create_ a translation, create a new directory at `plone/app/locales/locales/{language_code}/LC_MESSAGES`, copy all the `.pot` files in `plone/app/locales/locales` to your new directory, rename the files in your directory by changing the file extension to `.po`, and start translating.
+
+4.  Commit your changes, and create a pull request with them.
+    Request a review from a colleague, especially if you are translating a file that already has some translations.
+    You can check the file's commit history with `git blame <filename>` to see previous contributors and request a review from them.
+    This is to ensure coherent translations throughout Plone.
+
+
+(contributing-plone-core-translations-translate-volto-label)=
+
+## Translate Volto
+
+The process of translating the Volto frontend is the following.
+
+1.  Go to https://github.com/plone/volto and clone it into your computer.
+
+2.  Create a new branch to prepare the translations.
+    Name the branch with something identifiable.
+    For example: `{language}-{date}` (`fr-20220731`).
+
+3.  Either update or create a translation.
+
+    -  To update a translation, translate your language's `po` file found at `locales/{language_code}/LC_MESSAGES/volto.po`.
+    -  To create a new translation, create a new directory at `locales/{language_code}/LC_MESSAGES/`, copy the file `locales/volto.pot` to `locales/{language_code}/LC_MESSAGES/volto.po` (note to drop the trailing `t`), and start translating.
+
+4. Commit your changes, and create a pull request.
+
+
+(contributing-plone-core-translations-support-label)=
+
+## Support
+
+Please ask questions on the Plone Community Forum category [Translations and i18n/l10n](https://community.plone.org/c/development/i18nl10n/42).

docs/glossary.md

@@ -0,0 +1,152 @@
+---
+myst:
+  html_meta:
+    "description": "Internationalization (i18n) and localization (l10n) in Plone 6"
+    "property=og:description": "Internationalization (i18n) and localization (l10n) in Plone 6"
+    "property=og:title": "Internationalization (i18n) and localization (l10n) in Plone 6"
+    "keywords": "Plone, Internationalization, i18n, language, translation, localization"
+---
+
+(i18n-l10n-label)=
+
+# Internationalization and Localization
+
+{term}`Internationalization` is the process of preparing an application for displaying content in languages and formats specifically to the audience.
+Developers and template authors usually internationalize the application.
+"i18n" is shorthand for "internationalization" (the letter "I", a run of 18 letters, the letter "N").
+
+{term}`Localization` is the process of writing the translations of text and local formats for an application that has already been internationalized.
+Formats include dates, times, numbers, time zones, units of measure, and currency.
+Translators usually localize the application.
+"l10n" is shorthand for "localization" (the letter "L", a run of 10 letters, the letter "N").
+
+Plone fully supports internationalization and localization.
+
+```{seealso}
+Wikipedia article [Internationalization and localization](https://en.wikipedia.org/wiki/Internationalization_and_localization)
+```
+
+
+(i18n-l10n-code-versus-content-label)=
+
+## Code versus content
+
+We categorize the things that we want to internationalize and localize in a Plone application into two groups:
+
+1.  **Code-level elements.**
+    This includes translations of the user interface elements' text strings and localization.
+    The tools used in this group include {term}`gettext`, Plone and Zope {term}`i18n` facilities, and {term}`react-intl`.
+    See the chapter {doc}`translating-text-strings`.
+2.  **User-generated content.**
+    For translating user-generated content, Plone uses the package [`plone.app.multilingual`](https://pypi.org/project/plone.app.multilingual/).
+    See the chapter {doc}`translating-content`.
+
+
+(i18n-l10n-common-concepts-label)=
+
+## Common concepts
+
+When you internationalize and localize a Plone application, there are some common concepts used throughout these processes.
+
+
+(i18n-l10n-terms-label)=
+
+### Terms
+
+The following terms are used in this documentation.
+
+locale
+:   A locale is an identifier, such as a {term}`language tag`, for a specific set of cultural preferences for some country, together with all associated translations targeted to the same native language.
+
+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/)
+    ```
+
+`.po`
+:   Portable Object (PO) file.
+    The message file format used by the {term}`gettext` translation system.
+    See https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/PO-Files.html.
+
+`.pot`
+:   Portable Object (PO) template file, not yet oriented towards any particular language.
+
+`.mo`
+:   Machine Object file.
+    The binary message file compiled from the {term}`.po` message file.
+
+
+(i18n-l10n-locale-and-language-tag-conventions-label)=
+
+### Locale and language tag conventions
+
+Plone uses certain conventions for its locales and language tags.
+
+-   When identifying a language only, use two lowercase letters.
+    Examples: `en`, `de`.
+-   When identifying a language and a country, use two lowercase letters, an underscore (`_`), and two uppercase letters.
+    Examples: `en_GB`, `pt_BR`.
+-   When identifying a language and script or character set, use two lowercase letters, an at sign (`@`), and four title case letters.
+    Example: `sr@Cyrl`.
+
+
+(i18n-l10n-general-procedure-label)=
+
+### General procedure
+
+```{note}
+This section concerns only *code-level* translations of text strings.
+
+For *user-generated content* translations, see {doc}`translating-content`.
+```
+
+In general, the process of internationalization and localization of a Plone application follows these steps.
+
+1.  Create translatable strings in your code.
+    Plone has already done this step within its core code.
+    However, when developing new features or add-ons, you will need to perform this step.
+2.  Find and extract all translatable strings from your code with a script, and create a `.pot` template file out of all these.
+3.  Create the `.po` files for all locales.
+4.  Edit the `.po` files, adding the translated messages into them.
+5.  Turn the `.po` files into `.mo` files.
+6.  Compile and link the `.mo` files with the gettext library.
+
+```{seealso}
+[Overview of GNU `gettext`](https://www.gnu.org/software/gettext/manual/html_node/Overview.html)
+```
+
+
+(i18n-l10n-implementation-details-label)=
+
+## Implementation details
+
+Depending on which part of your Plone application that you internationalize and localize, there are different implementation details and tools that are used.
+These differences depend upon the programming language, either Python or JavaScript, being used by that part.
+
+-   For the Plone 6 frontend {term}`Volto`, see {doc}`/volto/recipes/i18n`.
+    Volto is based on the JavaScript library React, and uses both {term}`react-intl` and {term}`gettext`.
+-   For the rest of Plone 6, see {doc}`translating-text-strings`.
+    This is based on Python, and uses {term}`gettext`.
+-   For user-generated content translations, see {doc}`translating-content`.
+
+
+
+(i18n-l10n-contents-label)=
+
+## Contents
+
+```{toctree}
+:maxdepth: 1
+
+translating-text-strings
+language-negotiation
+translating-content
+contributing-translations
+resync-translations
+```
+

docs/i18n-l10n/contributing-translations.md

@@ -0,0 +1,98 @@
+---
+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"
+    "keywords": "Plone, Internationalization, i18n, language, negotiation, translation, localization"
+---
+
+(language-negotiation-label)=
+
+# Language negotiation
+
+```{todo}
+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.
+
+
+(language-negotiation-plone.app.multilingual-is-not-enabled-label)=
+
+## `plone.app.multilingual` is not enabled
+
+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.
+
+By visiting the URI `@@language-controlpanel` ({guilabel}`Site Setup > General > Language`), the site administrator may configure language options for 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.
+
+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 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`](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 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`.
+
+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.
+
+(language-negotiation-plone.app.multilingual-is-enabled-label)=
+
+## `plone.app.multilingual` is enabled
+
+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.
+
+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.