Description
Utilisez l'infrastructure chrome.i18n
pour implémenter l'internationalisation dans l'ensemble de votre application ou de votre extension.
Manifest
Si une extension possède un répertoire /_locales
, le fichier manifeste doit définir "default_locale"
.
Concepts et utilisation
Vous devez placer toutes les chaînes visibles par l'utilisateur dans un fichier nommé messages.json
. Chaque fois que vous ajoutez des paramètres régionaux, vous ajoutez un fichier de messages dans un répertoire nommé /_locales/_localeCode_
, où localeCode correspond à un code tel que en
pour l'anglais.
Voici la hiérarchie de fichiers pour une extension internationalisée compatible avec l'anglais (en
), l'espagnol (es
) et le coréen (ko
):
Compatibilité avec plusieurs langues
Supposons que vous disposiez d'une extension avec les fichiers indiqués dans la figure suivante:
Pour internationaliser cette extension, vous devez nommer chaque chaîne visible par l'utilisateur et la placer dans un fichier de messages. Le fichier manifeste, les fichiers CSS et le code JavaScript de l'extension utilisent le nom de chaque chaîne pour obtenir sa version localisée.
Voici à quoi ressemble l'extension lorsqu'elle est internationalisée (notez qu'elle ne contient encore que des chaînes en anglais):
<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="Dans le fichier manifest.json, " and="" was="" changed="" chrome.i18n.getjsonmessage("extname").="" définit="" en="" file="" file="" hello/name" has
Remarques sur l'internationalisation:
- Vous pouvez utiliser n'importe laquelle des langues compatibles. Si vous utilisez des paramètres régionaux non compatibles, Google Chrome les ignore.
Dans les fichiers
manifest.json
et CSS, faites référence à une chaîne nommée messagename comme suit:__MSG_messagename__
Dans le code JavaScript de votre extension ou de votre application, faites référence à une chaîne nommée messagename comme suit:
chrome.i18n.getMessage("messagename")
Dans chaque appel de
getMessage()
, vous pouvez fournir jusqu'à neuf chaînes à inclure dans le message. Pour en savoir plus, consultez Exemples: getMessage.Certains messages, tels que
@@bidi_dir
et@@ui_locale
, sont fournis par le système d'internationalisation. Consultez la section Messages prédéfinis pour obtenir la liste complète des noms de messages prédéfinis.Dans
messages.json
, chaque chaîne visible par l'utilisateur comporte un nom, un élément "message" et un élément "description" facultatif. Le nom est une clé, telle que "extName" ou "search_string", qui identifie la chaîne. Le "message" spécifie la valeur de la chaîne dans ces paramètres régionaux. La "description" facultative aide les traducteurs, qui risquent de ne pas voir comment la chaîne est utilisée dans votre extension. Exemple :{ "search_string": { "message": "hello%20world", "description": "The string we search for. Put %20 between words that go together." }, ... }
Pour en savoir plus, consultez la page Formats: messages spécifiques aux paramètres régionaux.
Une fois qu'une extension est internationalisée, la traduction devient un jeu d'enfant. Copiez messages.json
, traduisez-le et placez la copie dans un nouveau répertoire sous /_locates
. Par exemple, pour accepter l'espagnol, il vous suffit de placer une copie traduite de messages.json
sous /_locates/es
. La figure suivante montre l'extension précédente avec une nouvelle traduction en espagnol.
Messages prédéfinis
Le système d'internationalisation fournit quelques messages prédéfinis pour vous aider à localiser vos contenus. Ceux-ci incluent @@ui_locale
, qui vous permet de détecter les paramètres régionaux actuels de l'interface utilisateur, ainsi que quelques messages @@bidi_...
qui vous permettent de détecter l'orientation du texte. Ces messages ont des noms semblables aux constantes de l'API BIDI (bidirectionnelle) des gadgets.
Le message spécial @@extension_id
peut être utilisé dans les fichiers CSS et JavaScript, que l'extension ou l'application soient localisées ou non. Ce message ne fonctionne pas dans les fichiers manifestes.
Le tableau suivant décrit chaque message prédéfini.
Nom du message | Description |
---|---|
@@extension_id | L'extension ou l'ID de l'application. Vous pouvez utiliser cette chaîne pour créer les URL des ressources au sein de l'extension. Même les extensions non localisées peuvent utiliser ce message. Remarque:Vous ne pouvez pas utiliser ce message dans un fichier manifeste. |
@@ui_locale | Paramètres régionaux actuels ; vous pouvez utiliser cette chaîne pour créer des URL spécifiques aux paramètres régionaux. |
@@bidi_dir | Orientation du texte pour les paramètres régionaux actuels, soit "ltr" pour les langues qui se lisent de gauche à droite (comme l'anglais) ou "rtl" pour les langues qui se lisent de droite à gauche (comme l'arabe). |
@@bidi_reversed_dir | Si @@bidi_dir correspond à "ltr", il s'agit de "rtl". Dans le cas contraire, il s'agit de "ltr". |
@@bidi_start_edge | Si @@bidi_dir correspond à "ltr", il s'agit de"left" ; sinon, de la valeur "right". |
@@bidi_end_edge | Si @@bidi_dir correspond à "ltr", il s'agit de "right" (droite) ; sinon, il s'agit de "left" (gauche). |
Voici un exemple d'utilisation de @@extension_id
dans un fichier CSS pour créer une URL:
body {
background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}
Si l'ID d'extension est abcdefghijklmnopqrstuvwxyzabcdef, la ligne en gras de l'extrait de code précédent devient:
background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');
Voici un exemple d'utilisation de messages @@bidi_*
dans un fichier CSS:
body {
direction: __MSG_@@bidi_dir__;
}
div#header {
margin-bottom: 1.05em;
overflow: hidden;
padding-bottom: 1.5em;
padding-__MSG_@@bidi_start_edge__: 0;
padding-__MSG_@@bidi_end_edge__: 1.5em;
position: relative;
}
Pour les langues qui se lisent de gauche à droite, telles que l'anglais, les lignes en gras deviennent les suivantes:
dir: ltr;
padding-left: 0;
padding-right: 1.5em;
Paramètres régionaux
Vous pouvez choisir parmi de nombreux paramètres régionaux, y compris en
, qui permettent à une seule traduction d'accepter plusieurs variantes d'une langue (en_GB
et en_US
, par exemple).
Vous pouvez localiser votre extension dans n'importe quel paramètre régional compatible avec le Chrome Web Store. Si votre paramètre régional n'est pas répertorié ici, choisissez celui qui s'en rapproche le plus. Par exemple, si les paramètres régionaux par défaut de votre extension sont "de_CH"
, sélectionnez "de"
sur le Chrome Web Store.
Code des paramètres régionaux | Langue (région) |
---|---|
ar | Arabe |
am | Amharique |
bg | Bulgare |
bn | Bengali |
ca | Catalan |
cs | Tchèque |
da | Danois |
de | Allemand |
el | Grec |
en | Anglais |
en_AU | Anglais (Australie) |
en_GB | Anglais (Grande-Bretagne) |
en_US | Français |
es | Espagnol |
es_419 | Espagnol (Amérique latine et Caraïbes) |
et | Estonien |
fa | Persan |
fi | Finnois |
fil | Philippin |
fr | Français |
gu | Gujarâtî |
he | Hébreu |
hi | Hindi |
h | Croate |
hu | Hongrois |
id | Indonésien |
pour les recevoir. | Italien |
ja | Japonais |
kn | Kannada |
ko | Coréen |
lt | Lituanien |
lv | Letton |
ml | Malayalam |
mr | Marathi |
ms | Malaisien |
nl | Néerlandais |
non | Norvégien |
pl | Polonais |
pt_BR | Portugais (Brésil) |
pt_PT | Portugais (Portugal) |
ro | Roumain |
ru | Russe |
sk | Slovaque |
sl | Slovène |
sr | Serbe |
sv | Suédois |
sw | Swahili |
ta | Tamoul |
te | Télougou |
th | Thaï |
tr | Turc |
uk | Ukrainien |
vi | Vietnamien |
zh_CN | Chinois (Chine) |
zh_TW | Chinois (Taïwan) |
Rechercher un message
Il n'est pas nécessaire de définir toutes les chaînes pour tous les paramètres régionaux acceptés. Tant que le fichier messages.json
des paramètres régionaux par défaut contient une valeur pour chaque chaîne, votre extension ou application s'exécutera, quelle que soit la quantité de traduction. Voici comment le système d'extensions recherche un message:
- Recherchez les paramètres régionaux préférés de l'utilisateur dans le fichier de messages (le cas échéant). Par exemple, lorsque les paramètres régionaux de Google Chrome sont définis sur l'anglais britannique (
en_GB
), le système recherche d'abord le message dans/_locates/en_GB/messages.json
. Si ce fichier existe et que le message s'y trouve, le système ne cherche pas plus loin. - Si les paramètres régionaux préférés de l'utilisateur comprennent une région (c'est-à-dire si les paramètres régionaux présentent un trait de soulignement: _), effectuez la recherche sans cette région. Par exemple, si le fichier de messages
en_GB
n'existe pas ou ne contient pas le message, le système le recherche dans le fichier de messagesen
. Si ce fichier existe et que le message est présent, le système ne cherche pas plus loin. - Recherchez les paramètres régionaux par défaut dans le fichier de messages. Par exemple, si le paramètre "default_locale" de l'extension est défini sur "es" et que ni
/_locates/en_GB/messages.json
ni/_locates/en/messages.json
ne contiennent le message, l'extension utilise le message de/_locates/es/messages.json
.
Dans la figure suivante, le message nommé "colores" apparaît dans les trois paramètres régionaux compatibles avec l'extension, mais "extName" n'est disponible que dans deux d'entre eux. Chaque fois qu'un utilisateur exécutant Google Chrome en anglais américain voit le libellé "Colors", un utilisateur de l'anglais britannique voit "Colours". Les utilisateurs de l'anglais américain et de l'anglais britannique voient le nom de l'extension "Hello World". Étant donné que la langue par défaut est l'espagnol, les utilisateurs qui exécutent Google Chrome dans une langue autre que l'anglais voient le libellé "Colores" (Couleurs) et le nom de l'extension "Hola mundo".
Définir les paramètres régionaux de votre navigateur
Pour tester les traductions, vous pouvez définir les paramètres régionaux de votre navigateur. Cette section explique comment définir les paramètres régionaux sous Windows, Mac OS X, Linux et ChromeOS.
Windows
Vous pouvez modifier les paramètres régionaux à l'aide d'un raccourci spécifique ou de l'interface utilisateur de Google Chrome. La méthode de raccourci est plus rapide, une fois configurée et vous permet d'utiliser plusieurs langues à la fois.
Utiliser un raccourci spécifique aux paramètres régionaux
Pour créer et utiliser un raccourci qui lance Google Chrome avec un paramètre régional spécifique:
- Créez une copie du raccourci Google Chrome déjà enregistré sur votre bureau.
- Renommez le nouveau raccourci pour qu'il corresponde aux nouveaux paramètres régionaux.
Modifiez les propriétés du raccourci afin que le champ "Cible" spécifie les indicateurs
--lang
et--user-data-dir
. La cible doit se présenter comme suit:path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
Lancez Google Chrome en double-cliquant sur le raccourci.
Par exemple, pour créer un raccourci qui lance Google Chrome en espagnol (es
), vous pouvez créer un raccourci nommé chrome-es
avec la cible suivante:
path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es
Vous pouvez créer autant de raccourcis que vous le souhaitez, ce qui facilite les tests dans plusieurs langues. Exemple :
path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko
Utiliser l'interface utilisateur
Pour modifier les paramètres régionaux à l'aide de l'interface utilisateur de Google Chrome pour Windows, procédez comme suit:
- Icône de l'application > Options
- Sélectionnez l'onglet Options avancées.
- Faites défiler la page jusqu'à Contenu Web.
- Cliquez sur Modifier les paramètres de police et de langue.
- Sélectionnez l'onglet Langues.
- Dans le menu déroulant, définissez la langue de Google Chrome.
- Redémarrer Chrome
Mac OS X
Pour modifier les paramètres régionaux sur Mac, utilisez les préférences système.
- Dans le menu "Apple", sélectionnez Préférences système.
- Dans la section Personnel, sélectionnez International.
- Choisissez votre langue et votre zone géographique
- Redémarrer Chrome
Linux
Pour modifier les paramètres régionaux sous Linux, commencez par quitter Google Chrome. Définissez ensuite la variable d'environnement LANGUAGE et lancez Google Chrome. Exemple :
LANGUAGE=es ./chrome
ChromeOS
Pour modifier les paramètres régionaux sous ChromeOS:
- Dans la barre d'état système, sélectionnez Paramètres.
- Dans la section Langues et saisie, cliquez sur le menu déroulant Langue.
- Si votre langue ne figure pas dans la liste, cliquez sur Ajouter des langues, puis ajoutez-la.
- Ensuite, cliquez sur l'élément de menu à trois points Autres actions à côté de votre langue, puis sélectionnez Afficher ChromeOS dans cette langue.
- Cliquez sur le bouton Redémarrer situé à côté de la langue sélectionnée pour redémarrer ChromeOS.
Exemples
Vous trouverez des exemples d'internationalisation simples dans le répertoire examples/api/i18n. Pour obtenir un exemple complet, consultez examples/extensions/news. Pour obtenir d'autres exemples et obtenir de l'aide concernant l'affichage du code source, consultez la section Exemples.
getMessage()
Le code suivant récupère un message localisé du navigateur et l'affiche sous forme de chaîne. Elle remplace deux espaces réservés dans le message par les chaînes "string1" et "string2".
function getMessage() {
var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
document.getElementById("languageSpan").innerHTML = message;
}
Voici comment fournir et utiliser une seule chaîne:
// In JavaScript code
status.innerText = chrome.i18n.getMessage("error", errorDetails);
"error": {
"message": "Error: $details$",
"description": "Generic error template. Expects error parameter to be passed in.",
"placeholders": {
"details": {
"content": "$1",
"example": "Failed to fetch RSS feed."
}
}
}
Pour en savoir plus sur les espaces réservés, consultez la page Messages associés à des paramètres régionaux. Pour en savoir plus sur l'appel de getMessage()
, consultez la documentation de référence de l'API.
getAcceptLanguages()
Le code suivant récupère les langues d'acceptation à partir du navigateur et les affiche sous la forme d'une chaîne en séparant chaque langue par ",".
function getAcceptLanguages() {
chrome.i18n.getAcceptLanguages(function(languageList) {
var languages = languageList.join(",");
document.getElementById("languageSpan").innerHTML = languages;
})
}
Pour en savoir plus sur l'appel de getAcceptLanguages()
, consultez la documentation de référence de l'API.
detectLanguage()
Le code suivant détecte jusqu'à trois langues de la chaîne donnée et affiche le résultat sous forme de chaînes séparées par un retour à la ligne.
function detectLanguage(inputText) {
chrome.i18n.detectLanguage(inputText, function(result) {
var outputLang = "Detected Language: ";
var outputPercent = "Language Percentage: ";
for(i = 0; i < result.languages.length; i++) {
outputLang += result.languages[i].language + " ";
outputPercent +=result.languages[i].percentage + " ";
}
document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
});
}
Pour en savoir plus sur l'appel de detectLanguage(inputText)
, consultez la documentation de référence de l'API.
Types
LanguageCode
Code de langue ISO, tel que en
ou fr
. Pour obtenir la liste complète des langues acceptées par cette méthode, consultez la section kLanguageInfoTable. Pour une langue inconnue, und
est renvoyé, ce qui signifie que [pourcentage] du texte est inconnu du CLD.
Type
chaîne
Méthodes
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
Détecte la langue du texte fourni à l'aide de CLD.
Paramètres
-
text
chaîne
Chaîne saisie par l'utilisateur à traduire.
-
rappel
function facultatif
Le paramètre
callback
ressemble à ceci :(result: object) => void
-
résultat
objet
Objet LanguageDetectionResult qui contient la fiabilité langugae détectée et le tableau de DetectedLanguage
-
isReliable
boolean
Fiabilité de la langue détectée par CLD
-
langues
objet[]
tableau dedetectLanguage
-
language
chaîne
-
pourcentage
Nombre
Pourcentage de la langue détectée
-
-
-
Renvoie
-
Promise<object>
Chrome 99 ou version ultérieureLes promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
Récupère les langues acceptées du navigateur. Ils sont différents de ceux utilisés par le navigateur. Pour obtenir les paramètres régionaux, utilisez i18n.getUILanguage
.
Paramètres
-
rappel
function facultatif
Le paramètre
callback
ressemble à ceci :(languages: string[]) => void
-
langues
chaîne[]
Tableau de LanguageCode
-
Renvoie
-
Promise<LanguageCode[]>
Chrome 99 ou version ultérieureLes promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
)
Récupère la chaîne localisée du message spécifié. Si le message est manquant, cette méthode renvoie une chaîne vide (''). Si le format de l'appel getMessage()
est incorrect (par exemple, messageName n'est pas une chaîne ou que le tableau substitutions comporte plus de neuf éléments), elle renvoie undefined
.
Paramètres
-
messageName
chaîne
Nom du message, tel que spécifié dans le fichier
messages.json
. -
substitutions
Tout facultatif
Jusqu'à neuf chaînes de substitution, si le message en requiert.
-
options
objet facultatif
Chrome 79 ou version ultérieure-
escapeLt
Booléen facultatif
Échappez
<
dans la traduction en<
. Cela s'applique uniquement au message lui-même, pas aux espaces réservés. Les développeurs peuvent utiliser cette option si la traduction est utilisée dans un contexte HTML. Les modèles de fermetures utilisés avec Closure Compiler la génèrent automatiquement.
-
Renvoie
-
chaîne
Message localisé pour les paramètres régionaux actuels.
getUILanguage()
chrome.i18n.getUILanguage()
Récupère la langue de l'interface utilisateur du navigateur. Cette méthode est différente de i18n.getAcceptLanguages
, qui renvoie les langues préférées des utilisateurs.
Renvoie
-
chaîne
Code de langue de l'interface utilisateur du navigateur, tel que en-US ou fr-FR.