|
| 1 | +--- |
| 2 | +myst: |
| 3 | + html_meta: |
| 4 | + "description": "Internationalization (i18n) and localization (l10n) in Plone 6" |
| 5 | + "property=og:description": "Internationalization (i18n) and localization (l10n) in Plone 6" |
| 6 | + "property=og:title": "Internationalization (i18n) and localization (l10n) in Plone 6" |
| 7 | + "keywords": "Plone, Internationalization, i18n, language, translation, localization" |
| 8 | +--- |
| 9 | + |
| 10 | +(i18n-l10n-label)= |
| 11 | + |
| 12 | +# Internationalization and Localization |
| 13 | + |
| 14 | +{term}`Internationalization` is the process of preparing an application for displaying content in languages and formats specifically to the audience. |
| 15 | +Developers and template authors usually internationalize the application. |
| 16 | +"i18n" is shorthand for "internationalization" (the letter "I", a run of 18 letters, the letter "N"). |
| 17 | + |
| 18 | +{term}`Localization` is the process of writing the translations of text and local formats for an application that has already been internationalized. |
| 19 | +Formats include dates, times, numbers, time zones, units of measure, and currency. |
| 20 | +Translators usually localize the application. |
| 21 | +"l10n" is shorthand for "localization" (the letter "L", a run of 10 letters, the letter "N"). |
| 22 | + |
| 23 | +Plone fully supports internationalization and localization. |
| 24 | + |
| 25 | +```{seealso} |
| 26 | +Wikipedia article [Internationalization and localization](https://en.wikipedia.org/wiki/Internationalization_and_localization) |
| 27 | +``` |
| 28 | + |
| 29 | + |
| 30 | +(i18n-l10n-code-versus-content-label)= |
| 31 | + |
| 32 | +## Code versus content |
| 33 | + |
| 34 | +We categorize the things that we want to internationalize and localize in a Plone application into two groups: |
| 35 | + |
| 36 | +1. **Code-level elements.** |
| 37 | + This includes translations of the user interface elements' text strings and localization. |
| 38 | + The tools used in this group include {term}`gettext`, Plone and Zope {term}`i18n` facilities, and {term}`react-intl`. |
| 39 | + See the chapter {doc}`translating-text-strings`. |
| 40 | +2. **User-generated content.** |
| 41 | + For translating user-generated content, Plone uses the package [`plone.app.multilingual`](https://pypi.org/project/plone.app.multilingual/). |
| 42 | + See the chapter {doc}`translating-content`. |
| 43 | + |
| 44 | + |
| 45 | +(i18n-l10n-common-concepts-label)= |
| 46 | + |
| 47 | +## Common concepts |
| 48 | + |
| 49 | +When you internationalize and localize a Plone application, there are some common concepts used throughout these processes. |
| 50 | + |
| 51 | + |
| 52 | +(i18n-l10n-terms-label)= |
| 53 | + |
| 54 | +### Terms |
| 55 | + |
| 56 | +The following terms are used in this documentation. |
| 57 | + |
| 58 | +locale |
| 59 | +: 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. |
| 60 | + |
| 61 | +language tag |
| 62 | +: A language tag is a string used as an identifier for a language. |
| 63 | + A language tag may have one or more subtags. |
| 64 | + The basic form of a language tag is `LANGUAGE-[SUBTAG]`. |
| 65 | + |
| 66 | + ```{seealso} |
| 67 | + - W3C article [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/) |
| 68 | + - W3C Working Draft [Language Tags and Locale Identifiers for the World Wide Web](https://www.w3.org/TR/ltli/) |
| 69 | + ``` |
| 70 | + |
| 71 | +`.po` |
| 72 | +: Portable Object (PO) file. |
| 73 | + The message file format used by the {term}`gettext` translation system. |
| 74 | + See https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/PO-Files.html. |
| 75 | + |
| 76 | +`.pot` |
| 77 | +: Portable Object (PO) template file, not yet oriented towards any particular language. |
| 78 | + |
| 79 | +`.mo` |
| 80 | +: Machine Object file. |
| 81 | + The binary message file compiled from the {term}`.po` message file. |
| 82 | + |
| 83 | + |
| 84 | +(i18n-l10n-locale-and-language-tag-conventions-label)= |
| 85 | + |
| 86 | +### Locale and language tag conventions |
| 87 | + |
| 88 | +Plone uses certain conventions for its locales and language tags. |
| 89 | + |
| 90 | +- When identifying a language only, use two lowercase letters. |
| 91 | + Examples: `en`, `de`. |
| 92 | +- When identifying a language and a country, use two lowercase letters, an underscore (`_`), and two uppercase letters. |
| 93 | + Examples: `en_GB`, `pt_BR`. |
| 94 | +- When identifying a language and script or character set, use two lowercase letters, an at sign (`@`), and four title case letters. |
| 95 | + Example: `sr@Cyrl`. |
| 96 | + |
| 97 | + |
| 98 | +(i18n-l10n-general-procedure-label)= |
| 99 | + |
| 100 | +### General procedure |
| 101 | + |
| 102 | +```{note} |
| 103 | +This section concerns only *code-level* translations of text strings. |
| 104 | +
|
| 105 | +For *user-generated content* translations, see {doc}`translating-content`. |
| 106 | +``` |
| 107 | + |
| 108 | +In general, the process of internationalization and localization of a Plone application follows these steps. |
| 109 | + |
| 110 | +1. Create translatable strings in your code. |
| 111 | + Plone has already done this step within its core code. |
| 112 | + However, when developing new features or add-ons, you will need to perform this step. |
| 113 | +2. Find and extract all translatable strings from your code with a script, and create a `.pot` template file out of all these. |
| 114 | +3. Create the `.po` files for all locales. |
| 115 | +4. Edit the `.po` files, adding the translated messages into them. |
| 116 | +5. Turn the `.po` files into `.mo` files. |
| 117 | +6. Compile and link the `.mo` files with the gettext library. |
| 118 | + |
| 119 | +```{seealso} |
| 120 | +[Overview of GNU `gettext`](https://www.gnu.org/software/gettext/manual/html_node/Overview.html) |
| 121 | +``` |
| 122 | + |
| 123 | + |
| 124 | +(i18n-l10n-implementation-details-label)= |
| 125 | + |
| 126 | +## Implementation details |
| 127 | + |
| 128 | +Depending on which part of your Plone application that you internationalize and localize, there are different implementation details and tools that are used. |
| 129 | +These differences depend upon the programming language, either Python or JavaScript, being used by that part. |
| 130 | + |
| 131 | +- For the Plone 6 frontend {term}`Volto`, see {doc}`/volto/recipes/i18n`. |
| 132 | + Volto is based on the JavaScript library React, and uses both {term}`react-intl` and {term}`gettext`. |
| 133 | +- For the rest of Plone 6, see {doc}`translating-text-strings`. |
| 134 | + This is based on Python, and uses {term}`gettext`. |
| 135 | +- For user-generated content translations, see {doc}`translating-content`. |
| 136 | + |
| 137 | + |
| 138 | + |
| 139 | +(i18n-l10n-contents-label)= |
| 140 | + |
| 141 | +## Contents |
| 142 | + |
| 143 | +```{toctree} |
| 144 | +:maxdepth: 1 |
| 145 | +
|
| 146 | +translating-text-strings |
| 147 | +language-negotiation |
| 148 | +translating-content |
| 149 | +contributing-translations |
| 150 | +resync-translations |
| 151 | +``` |
| 152 | + |
0 commit comments