diff --git a/files/fr/mozilla/add-ons/webextensions/internationalization/index.md b/files/fr/mozilla/add-ons/webextensions/internationalization/index.md index f9e03de43fb556..abfb9b7b8da397 100644 --- a/files/fr/mozilla/add-ons/webextensions/internationalization/index.md +++ b/files/fr/mozilla/add-ons/webextensions/internationalization/index.md @@ -18,11 +18,11 @@ Une extension internationalisée peut contenir les mêmes fonctionnalités que n - `répertoire-racine-de-l'extension/` - `_locales` - `en` - - `messages.json` : un fichier qui contiendra les chaînes de caractères en anglais + - `messages.json` : un fichier qui contiendra les chaines de caractères en anglais - `fr_FR` - - `messages.json` : un fichier qui contiendra les chaînes de caractères en français + - `messages.json` : un fichier qui contiendra les chaines de caractères en français - `de` - - `messages.json` : un fichier qui contiendra les chaînes de caractères en allemand + - `messages.json` : un fichier qui contiendra les chaines de caractères en allemand - etc. - `manifest.json` : des métadonnées relatives aux locales sont ajoutées au [manifeste](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json) - `fichierJavaScript.js` : de la logique pour récupérer la locale du navigateur, récupérer les messages spécifiques à la locale courante, etc. @@ -30,9 +30,9 @@ Une extension internationalisée peut contenir les mêmes fonctionnalités que n Examinons chacune de ces fonctionnalités supplémentaires. Chacune des sections qui suit représente une étape à suivre pour l'internationalisation de votre extension. -## Fournir des chaînes localisées dans `_locales` +## Fournir des chaines localisées dans `_locales` -L'internationalisation nécessite de fournir des chaînes traduites pour les différentes locales qu'on souhaite prendre en charge. Pour les extensions, le répertoire `_locales`, présent à la racine de l'extension, contient un sous-répertoire pour chaque locale, nommé grâce à [l'étiquette de langue correspondante](https://fr.wikipedia.org/wiki/%C3%89tiquette_d%27identification_de_langues_IETF) et ce dernier contient un fichier `messages.json` avec les chaînes de caractères traduites pour la locale correspondante. +L'internationalisation nécessite de fournir des chaines traduites pour les différentes locales qu'on souhaite prendre en charge. Pour les extensions, le répertoire `_locales`, présent à la racine de l'extension, contient un sous-répertoire pour chaque locale, nommé grâce à [l'étiquette de langue correspondante](https://fr.wikipedia.org/wiki/%C3%89tiquette_d%27identification_de_langues_IETF) et ce dernier contient un fichier `messages.json` avec les chaines de caractères traduites pour la locale correspondante. > **Attention :** Contrairement à la convention qui consiste à séparer la sous-étiquette de base et celle de la variante régionale par un tiret (par exemple `en-US` ou `fr-CA`), **il faudra utiliser un tiret bas pour le nom du répertoire sous `_locales`** (par exemple `en_US` ou `fr_CA`). @@ -72,7 +72,7 @@ Regardons maintenant la structure de l'un de ces fichiers ([`_locales/en/message } ``` -Ce fichier est du JSON standard, chaque propriété est un objet avec un nom, qui contient une propriété `message` et une propriété `description`. Tous ces éléments sont des chaînes de caractères et `$URL$` est un emplacement de substitution qui sera remplacé par une sous-chaîne lorsque la propriété `notificationContent` sera manipulée par l'extension. Nous verrons comment faire dans la section [Récupération des messages localisés dans le code JavaScript](#récupérer_des_messages_localisés_dans_le_code_javascript). +Ce fichier est du JSON standard, chaque propriété est un objet avec un nom, qui contient une propriété `message` et une propriété `description`. Tous ces éléments sont des chaines de caractères et `$URL$` est un emplacement de substitution qui sera remplacé par une sous-chaine lorsque la propriété `notificationContent` sera manipulée par l'extension. Nous verrons comment faire dans la section [Récupération des messages localisés dans le code JavaScript](#récupérer_des_messages_localisés_dans_le_code_javascript). > **Note :** Pour plus d'informations sur le contenu des fichiers `messages.json`, voir [la référence des formats de messages localisés](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference). @@ -80,9 +80,9 @@ Ce fichier est du JSON standard, chaque propriété est un objet avec un nom, qu Plusieurs actions sont nécessaires pour internationaliser le manifeste (`manifest.json`) de l'extension. -### Récupérer les chaînes localisées dans le manifeste +### Récupérer les chaines localisées dans le manifeste -[Le manifeste de l'extension](https://github.com/mdn/webextensions-examples/blob/main/notify-link-clicks-i18n/manifest.json) contient des chaînes de caractères qui seront visibles de l'utilisatrice et de l'utilisateur, comme le nom et la description de l'extension. Si vous internationalisez ces propriétés et placez les traductions appropriées dans les fichiers `messages.json`, la traduction appropriée sera affichée en fonction des paramètres de locale du navigateur. +[Le manifeste de l'extension](https://github.com/mdn/webextensions-examples/blob/main/notify-link-clicks-i18n/manifest.json) contient des chaines de caractères qui seront visibles de l'utilisatrice et de l'utilisateur, comme le nom et la description de l'extension. Si vous internationalisez ces propriétés et placez les traductions appropriées dans les fichiers `messages.json`, la traduction appropriée sera affichée en fonction des paramètres de locale du navigateur. Pour internationaliser ces propriétés, renseignez le manifeste ainsi : @@ -91,12 +91,12 @@ Pour internationaliser ces propriétés, renseignez le manifeste ainsi : "description": "__MSG_extensionDescription__", ``` -Ces valeurs spéciales indiqueront au navigateur de rechercher la chaîne localisée correspondante, plutôt que d'utiliser la mème valeur statique pour toutes les locales. +Ces valeurs spéciales indiqueront au navigateur de rechercher la chaine localisée correspondante, plutôt que d'utiliser la mème valeur statique pour toutes les locales. -Pour faire référence à un message localisé, composez la chaîne de caractères en concaténant : +Pour faire référence à un message localisé, composez la chaine de caractères en concaténant : 1. Deux tirets bas (`__`) -2. La chaîne `MSG` +2. La chaine `MSG` 3. Un tiret bas (`_`) 4. Le nom du message visé, tel qu'il est défini dans `messages.json` 5. Deux tirets bas (`__`) @@ -123,7 +123,7 @@ Si un message n'est pas disponible dans la locale courante du navigateur, ce der ## Utiliser du code CSS variant selon la locale -Il est aussi possible d'utiliser des chaînes localisées au sein des fichiers CSS de l'extension. Par exemple, on pourra ainsi construire une règle CSS qui varie selon la locale : +Il est aussi possible d'utiliser des chaines localisées au sein des fichiers CSS de l'extension. Par exemple, on pourra ainsi construire une règle CSS qui varie selon la locale : ```css header { @@ -166,15 +166,15 @@ La première ligne récupère le message avec l'identifiant `notificationTitle` } ``` -La propriété `"placeholders"` définit tous les emplacements de substitution ainsi que leur origine pour le remplacement. Pour `"url"`, l'origine du contenu est `$1`, ce qui correspond à la première valeur passée dans le second paramètre de `getMessage()`. Puisque l'emplacement de substitution est appelé `"url"`, nous utilisons `$URL$` pour l'appeler dans la chaîne de message (pour `"nomdemplacement"` vous utiliserez `$NOMDEMPLACEMENT$`, etc.). Si un message possède plusieurs emplacements de substitution, les valeurs à remplacer pourront être fournies sous la forme d'un tableau, passé en deuxième paramètre à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage). Ainsi, fournir le tableau `[a, b, c]` permettra de fournir des valeurs pour les emplacements de substitution dont les origines respectives sont `$1`, `$2`, et `$3`. +La propriété `"placeholders"` définit tous les emplacements de substitution ainsi que leur origine pour le remplacement. Pour `"url"`, l'origine du contenu est `$1`, ce qui correspond à la première valeur passée dans le second paramètre de `getMessage()`. Puisque l'emplacement de substitution est appelé `"url"`, nous utilisons `$URL$` pour l'appeler dans la chaine de message (pour `"nomdemplacement"` vous utiliserez `$NOMDEMPLACEMENT$`, etc.). Si un message possède plusieurs emplacements de substitution, les valeurs à remplacer pourront être fournies sous la forme d'un tableau, passé en deuxième paramètre à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage). Ainsi, fournir le tableau `[a, b, c]` permettra de fournir des valeurs pour les emplacements de substitution dont les origines respectives sont `$1`, `$2`, et `$3`. -Par exemple, dans le fichier `en/messages.json`, la chaîne originale du message `notificationContent` est +Par exemple, dans le fichier `en/messages.json`, la chaine originale du message `notificationContent` est ``` You clicked $URL$. ``` -Si le lien sur lequel on a cliqué pointe vers `https://developer.mozilla.org`, après l'appel à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage), le contenu du deuxième paramètre sera mis à disposition via l'origine `$1`, et remplacera la sous-chaîne `$URL$` tel que défini dans `"url"`. La chaîne de caractères finalement obtenue sera donc : +Si le lien sur lequel on a cliqué pointe vers `https://developer.mozilla.org`, après l'appel à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage), le contenu du deuxième paramètre sera mis à disposition via l'origine `$1`, et remplacera la sous-chaine `$URL$` tel que défini dans `"url"`. La chaine de caractères finalement obtenue sera donc : ``` You clicked https://developer.mozilla.org. @@ -182,7 +182,7 @@ You clicked https://developer.mozilla.org. ### Utilisation directe d'un emplacement de substitution -Il est possible d'insérer vos variables (`$1`, `$2`, `$3`, etc.) directement dans les chaînes de message. Par exemple nous pourrions réécrire la propriété `"notificationContent"` comme ceci : +Il est possible d'insérer vos variables (`$1`, `$2`, `$3`, etc.) directement dans les chaines de message. Par exemple nous pourrions réécrire la propriété `"notificationContent"` comme ceci : ```json "notificationContent": { @@ -195,7 +195,7 @@ Cela peut sembler plus rapide et moins complexe, mais l'utilisation de `"placeho ### Substitution codée en dur -Il est également possible d'inclure des chaînes statiques dans des emplacements de substitution, de sorte que la même valeur soit utilisée à chaque fois plutôt que d'obtenir la valeur d'une variable dans le code. Par exemple : +Il est également possible d'inclure des chaines statiques dans des emplacements de substitution, de sorte que la même valeur soit utilisée à chaque fois plutôt que d'obtenir la valeur d'une variable dans le code. Par exemple : ```json "mdn_banner": { @@ -209,18 +209,18 @@ Il est également possible d'inclure des chaînes statiques dans des emplacement } ``` -Dans ce cas, nous plaçons une chaîne statique pour la substitution plutôt que de l'obtenir à partir d'une variable comme `$1`. Cette technique peut s'avérer utile lorsque le fichier de messages est très complexe et qu'il devient nécessaire de séparer différentes valeurs afin de rendre le fichier plus lisible. De plus, ces valeurs sont alors accessibles en JavaScript. +Dans ce cas, nous plaçons une chaine statique pour la substitution plutôt que de l'obtenir à partir d'une variable comme `$1`. Cette technique peut s'avérer utile lorsque le fichier de messages est très complexe et qu'il devient nécessaire de séparer différentes valeurs afin de rendre le fichier plus lisible. De plus, ces valeurs sont alors accessibles en JavaScript. -En outre, vous pouvez utiliser ces substitutions pour spécifier les parties de la chaîne que vous ne souhaitez pas traduire, telles que les noms de personne ou d'entreprise. +En outre, vous pouvez utiliser ces substitutions pour spécifier les parties de la chaine que vous ne souhaitez pas traduire, telles que les noms de personne ou d'entreprise. -## Algorithme de sélection de la chaîne de caractères localisée +## Algorithme de sélection de la chaine de caractères localisée -Les locales peuvent être indiquées à l'aide d'une simple étiquette de langue comme `fr` ou `en`, ou avec en plus une sous-étiquette de région comme `en_US` ou `en_GB`. Lorsqu'on utilise l'API `i18n` afin de récupérer une chaîne de caractères localisée, le navigateur utilise l'algorithme suivant : +Les locales peuvent être indiquées à l'aide d'une simple étiquette de langue comme `fr` ou `en`, ou avec en plus une sous-étiquette de région comme `en_US` ou `en_GB`. Lorsqu'on utilise l'API `i18n` afin de récupérer une chaine de caractères localisée, le navigateur utilise l'algorithme suivant : -1. S'il existe un fichier `messages.json` pour exactement la locale courante, et si ce fichier contient la chaîne demandée, c'est celle-ci qui est renvoyée. -2. Sinon, si la locale courante est fournie avec une sous-étiquette de région (par exemple `en_US`) et qu'il existe un fichier `messages.json` pour l'étiquette de langue correspondante sans région (par exemple `en`), et si ce fichier contient la chaîne, c'est celle-ci qui est renvoyée. -3. Sinon, s'il existe un fichier `messages.json` pour la locale par défaut (fournie via la propriété du manifeste `default_locale`), et que ce fichier contient la chaîne, c'est celle-ci qui est renvoyée. -4. Sinon, c'est la chaîne de caractères vide qui est renvoyée. +1. S'il existe un fichier `messages.json` pour exactement la locale courante, et si ce fichier contient la chaine demandée, c'est celle-ci qui est renvoyée. +2. Sinon, si la locale courante est fournie avec une sous-étiquette de région (par exemple `en_US`) et qu'il existe un fichier `messages.json` pour l'étiquette de langue correspondante sans région (par exemple `en`), et si ce fichier contient la chaine, c'est celle-ci qui est renvoyée. +3. Sinon, s'il existe un fichier `messages.json` pour la locale par défaut (fournie via la propriété du manifeste `default_locale`), et que ce fichier contient la chaine, c'est celle-ci qui est renvoyée. +4. Sinon, c'est la chaine de caractères vide qui est renvoyée. Prenons la structure d'exemple suivante : @@ -235,12 +235,12 @@ Prenons la structure d'exemple suivante : Supposons que `default_locale` vaille `fr`, et que la locale courante du navigateur soit `en_GB` : -- Si l'extension appelle `getMessage("colorLocalised")`, c'est la chaîne `"colour"` qui sera renvoyée +- Si l'extension appelle `getMessage("colorLocalised")`, c'est la chaine `"colour"` qui sera renvoyée - Si `colorLocalised` n'était pas présent dans le fichier pour `en_GB`, `getMessage("colorLocalised")` renverrait alors `"color"` (car `en` est l'étiquette de langue sans région correspondante à `en_GB`), et pas `"couleur"`. ## Messages prédéfinis -L'API `i18n` permet d'utiliser des messages prédéfinis, de la même façon que pour [récupérer les chaînes localisées dans le manifeste](#récupérer_les_chaînes_localisées_dans_le_manifeste) ou [depuis le code CSS](#utiliser_du_code_css_variant_selon_la_locale). Par exemple : +L'API `i18n` permet d'utiliser des messages prédéfinis, de la même façon que pour [récupérer les chaines localisées dans le manifeste](#récupérer_les_chaînes_localisées_dans_le_manifeste) ou [depuis le code CSS](#utiliser_du_code_css_variant_selon_la_locale). Par exemple : ``` __MSG_extensionName__ @@ -266,11 +266,11 @@ Le tableau suivant indique les différents messages prédéfinis disponibles&nbs @@extension_id

- L'UUID généré en interne pour l'extension. Vous pouvez utiliser cette chaîne pour créer des URL pour les ressources à l'intérieur de l'extension. Même les extensions non localisées peuvent utiliser ce message. + L'UUID généré en interne pour l'extension. Vous pouvez utiliser cette chaine pour créer des URL pour les ressources à l'intérieur de l'extension. Même les extensions non localisées peuvent utiliser ce message.

Vous ne pouvez pas utiliser ce message dans un fichier de manifeste.

- Notez également que cet identifiant ne correspond pas à l'identifiant renvoyé par runtime.id qui peut être défini à l'aide de la clé de manifeste browser_specific_settings. C'est l'UUID généré qui apparaît dans l'URL du module complémentaire. Cela signifie que vous ne pouvez pas utiliser cette valeur comme paramètre extensionId pour runtime.sendMessage(), et que vous + Notez également que cet identifiant ne correspond pas à l'identifiant renvoyé par runtime.id qui peut être défini à l'aide de la clé de manifeste browser_specific_settings. C'est l'UUID généré qui apparait dans l'URL du module complémentaire. Cela signifie que vous ne pouvez pas utiliser cette valeur comme paramètre extensionId pour runtime.sendMessage(), et que vous ne pouvez pas l'utiliser pour vérifier la propriété id d'un objet runtime.MessageSender.

@@ -278,31 +278,31 @@ Le tableau suivant indique les différents messages prédéfinis disponibles&nbs @@ui_locale - La locale courante. Cette chaîne peut être utilisée afin de construire des URL variant en fonction de la locale. + La locale courante. Cette chaine peut être utilisée afin de construire des URL variant en fonction de la locale. @@bidi_dir - La direction du texte pour la locale courante. Cette chaîne vaut "ltr" pour les langues écrites de gauche à droite telles que le français ou "rtl" pour les langues écrites de droite à gauche telles que l'arabe. + La direction du texte pour la locale courante. Cette chaine vaut "ltr" pour les langues écrites de gauche à droite telles que le français ou "rtl" pour les langues écrites de droite à gauche telles que l'arabe. @@bidi_reversed_dir - Si @@bidi_dir vaut "ltr", alors cette chaîne vaudra "rtl", sinon elle vaudra "ltr". + Si @@bidi_dir vaut "ltr", alors cette chaine vaudra "rtl", sinon elle vaudra "ltr". @@bidi_start_edge - Si @@bidi_dir vaut "ltr", alors cette chaîne vaudra "left", sinon elle vaudra "right". + Si @@bidi_dir vaut "ltr", alors cette chaine vaudra "left", sinon elle vaudra "right". @@bidi_end_edge - Si @@bidi_dir vaut "ltr", alors cette chaîne vaudra "right", sinon elle vaudra "left". + Si @@bidi_dir vaut "ltr", alors cette chaine vaudra "right", sinon elle vaudra "left". @@ -357,6 +357,6 @@ Pour tester la localisation de votre extension, utilisez [Firefox](https://www.m Ensuite, pour chaque locale que vous prenez en charge et que vous voulez tester, suivez les instructions de la page [Utiliser Firefox dans une autre langue](https://support.mozilla.org/fr/kb/utiliser-firefox-dans-autre-langue) afin de changer la locale utilisée pour l'interface utilisateur de Firefox (si vous connaissez les paramètres, allez dans la section Langue et utilisez Choisir des alternatives). -Lorsque Firefox utilise la locale à tester, [installez l'extension temporairement](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/). Après avoir installé votre extension, vérifiez dans la page `about:debugging` que votre extension est bien mise en place et que l'icône, le nom et la description apparaissent avec la bonne locale. Vous pouvez également vérifier les métadonnées localisées via la page `about:addons`. Finalement, utilisez les fonctionnalités de l'extension pour vérifier que les chaînes localisées sont bien présentes. +Lorsque Firefox utilise la locale à tester, [installez l'extension temporairement](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/). Après avoir installé votre extension, vérifiez dans la page `about:debugging` que votre extension est bien mise en place et que l'icône, le nom et la description apparaissent avec la bonne locale. Vous pouvez également vérifier les métadonnées localisées via la page `about:addons`. Finalement, utilisez les fonctionnalités de l'extension pour vérifier que les chaines localisées sont bien présentes. Si vous souhaitez vous faire la main sur ce processus de test, vous pouvez utiliser [l'exemple d'extension `notify-link-clicks-i18n`](https://github.com/mdn/webextensions-examples/tree/main/notify-link-clicks-i18n). Paramétrez Firefox pour qu'il s'affiche dans l'une des locales prise en charge (l'allemand, le néerlandais ou le japonais), chargez l'extension et allez sur un site web. Cliquez sur un lien pour voir la notification localisée indiquer le lien de l'URL.