chrome.i18n

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 est un code comme en pour l'anglais.

Voici la hiérarchie de fichiers d'une extension internationalisée compatible avec l'anglais (en), l'espagnol (es) et le coréen (ko):

Dans le répertoire des extensions: manifest.json, *.html, *.js, /_locates directory. Dans le répertoire /_locates: en, es et ko, chacun contenant un fichier messages.json.

Compatibilité avec plusieurs langues

Supposons que vous ayez une extension avec les fichiers indiqués dans la figure suivante:

Un fichier manifest.json et un fichier JavaScript. Le fichier .json contient

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 comporte toujours que des chaînes en anglais):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="Dans le fichier manifest.json, " and="" were="" changed="" chrome.i18n.getmessage("extname").="" define="" en="" /

Quelques remarques sur l'internationalisation:

  • Vous pouvez utiliser tous les paramètres régionaux acceptés. Si vous utilisez des paramètres régionaux non compatibles, Google Chrome l'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 est associée à 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. "message" spécifie la valeur de la chaîne dans ces paramètres régionaux. La "description" facultative fournit une aide aux 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 section Formats: messages spécifiques aux paramètres régionaux.

Une fois qu'une extension est internationalisée, il est facile de la traduire. Vous copiez messages.json, le traduisez 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.

Le résultat est semblable à la figure précédente, mais avec un nouveau fichier dans /_locates/es/messages.json contenant une traduction en espagnol des messages.

Messages prédéfinis

Le système d'internationalisation fournit quelques messages prédéfinis pour vous aider à localiser. 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 messageDescription
@@extension_idExtension ou ID de l'application. Vous pouvez utiliser cette chaîne pour créer des URL pour les 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_localeLes paramètres régionaux actuels. Vous pouvez utiliser cette chaîne pour créer des URL spécifiques aux paramètres régionaux.
@@bidi_dirOrientation du texte pour les paramètres régionaux actuels, "ltr" pour les langues qui se lisent de gauche à droite, comme l'anglais, ou "rtl" pour celles qui se lisent de droite à gauche, telles que le japonais.
@@bidi_reversed_dirSi la valeur de @@bidi_dir est "ltr", la valeur est "rtl". Sinon, la valeur est "ltr".
@@bidi_start_edgeSi @@bidi_dir est "ltr", la valeur est "left" ; sinon, la valeur est "right".
@@bidi_end_edgeSi @@bidi_dir est "ltr", la valeur est "right" (droite). Sinon, la valeur est "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 (comme 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, dont certains (en, par exemple) qui permettent à une même traduction de prendre en charge 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. S'ils ne figurent pas dans cette liste, choisissez l'alternative la plus proche. 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
it 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 chaque paramètre régional pris en charge. Tant que le fichier messages.json des paramètres régionaux par défaut comporte une valeur pour chaque chaîne, votre extension ou application sera exécutée, quelle que soit la dispersion de traduction. Voici comment le système d'extensions recherche un message:

  1. Dans le fichier de messages (le cas échéant), recherchez les paramètres régionaux préférés de l'utilisateur. 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'affiche, le système ne cherche pas d'autres solutions.
  2. Si les paramètres régionaux préférés de l'utilisateur comprennent une région (c'est-à-dire un trait de soulignement: _), recherchez les paramètres régionaux 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 messages en. Si ce fichier existe et que le message s'affiche, le système ne cherche pas d'autres solutions.
  3. Recherchez les paramètres régionaux par défaut dans le fichier de messages. Par exemple, si "default_locale" est défini sur "es" pour l'extension, et que ni /_locates/en_GB/messages.json, ni /_locates/en/messages.json ne contient le message, l'extension utilise le message de /_locates/es/messages.json.

Dans la figure suivante, le message nommé "colores" figure dans les trois paramètres régionaux pris en charge par l'extension, mais "extName" ne figure 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 qui utilisent l'anglais américain et l'anglais britannique voient le nom d'extension "Hello World". Étant donné que la langue par défaut est l'espagnol, les utilisateurs qui utilisent Google Chrome dans une langue autre que l'anglais voient le libellé "Colores" et le nom de l'extension "Hola mundo".

Quatre fichiers: manifest.json et trois fichiers messages.json (pour es, en et en_GB).  Les fichiers es et en contiennent des entrées pour les messages nommés

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 à l'aide de l'interface utilisateur de Google Chrome. Une fois configuré, l'approche du raccourci est plus rapide 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 des paramètres régionaux spécifiques, procédez comme suit:

  1. Créez une copie du raccourci Google Chrome qui se trouve déjà sur votre bureau.
  2. Renommez le nouveau raccourci pour qu'il corresponde aux nouveaux paramètres régionaux.
  3. 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
    
  4. 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:

  1. Icône Application > Options
  2. Sélectionnez l'onglet Options avancées.
  3. Faites défiler la page jusqu'à Contenu Web.
  4. Cliquez sur Modifier les paramètres relatifs à la police et à la langue.
  5. Sélectionnez l'onglet Langues.
  6. Définissez la langue de Google Chrome dans le menu déroulant.
  7. Redémarrer Chrome

Mac OS X

Pour modifier les paramètres régionaux sous Mac, utilisez les préférences système.

  1. Dans le menu Apple, sélectionnez Préférences Système.
  2. Dans la section Personnel, sélectionnez International.
  3. Sélectionnez votre langue et votre zone géographique
  4. Redémarrer Chrome

Linux

Pour modifier les paramètres régionaux sous Linux, quittez d'abord Google Chrome. Ensuite, sur une seule ligne, définissez la variable d'environnement LANGUAGE et lancez Google Chrome. Exemple :

LANGUAGE=es ./chrome

ChromeOS

Pour modifier les paramètres régionaux sous ChromeOS:

  1. Dans la barre d'état système, sélectionnez Paramètres.
  2. Dans la section Langues et saisie, sélectionnez le menu déroulant Langue.
  3. Si votre langue ne figure pas dans la liste, cliquez sur Ajouter des langues, puis ajoutez-la.
  4. Une fois la langue ajoutée, cliquez sur l'élément de menu à trois points Autres actions situé à côté de votre langue, puis sélectionnez Afficher ChromeOS dans cette langue.
  5. Cliquez sur le bouton Redémarrer à côté de la langue définie pour redémarrer ChromeOS.

Exemples

Vous trouverez des exemples simples d'internationalisation dans le répertoire examples/api/i18n. Pour obtenir un exemple complet, consultez examples/extensions/news. Pour obtenir d'autres exemples et de l'aide concernant l'affichage du code source, consultez la section Exemples.

getMessage()

Le code suivant reçoit 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 spécifiques aux 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 acceptées du navigateur et les affiche sous forme de chaîne en séparant chaque expression "accept-language" par une virgule.

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

Pour savoir comment appeler getAcceptLanguages(), consultez la documentation de référence de l'API.

detectLanguage()

Le code suivant détecte jusqu'à trois langues à partir de la chaîne donnée et affiche le résultat sous forme de chaînes séparées par des sauts de 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

Chrome 47 ou version ultérieure

Un code de langue ISO tel que en ou fr. Pour obtenir la liste complète des langues compatibles avec cette méthode, consultez kLanguageInfoTable. Pour une langue inconnue, und est renvoyé, ce qui signifie que le CLD ne connaît pas [percentage] du texte.

Type

chaîne

Méthodes

detectLanguage()

Promesse Chrome 47 et versions ultérieures
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

    fonction facultative

    Le paramètre callback se présente comme suit :

    (result: object)=>void

    • résultat

      objet

      Objet LanguageDetectionResult qui contient la fiabilité des langues détectées et un tableau de DetectedLanguage

      • isReliable

        boolean

        Le CLD a détecté la fiabilité du langage

      • langues

        objet[]

        tableau de DetectLanguage

        • language

          chaîne

        • pourcentage

          number

          Pourcentage de la langue détectée

Renvoie

  • Promise<object>

    Chrome 99 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getAcceptLanguages()

Promesse
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

Récupère les langues acceptées du navigateur. Ces paramètres sont différents de ceux utilisés par le navigateur. Pour les obtenir, utilisez i18n.getUILanguage.

Paramètres

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit :

    (languages: string[])=>void

    • langues

      chaîne[]

      Tableau de LanguageCode

Renvoie

  • Promise<LanguageCode[]>

    Chrome 99 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans 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 pour le 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

    Toute valeur facultatif

    Jusqu'à neuf chaînes de substitution, le cas échéant.

  • options

    objet facultatif

    Chrome 79 et versions ultérieures
    • escapeLt

      Booléen facultatif

      Échappement < lors de la traduction en &lt;. Cela s'applique uniquement au message lui-même, et non aux espaces réservés. Cette option peut être utile aux développeurs si la traduction est utilisée dans un contexte HTML. Les modèles de fermeture utilisés avec Closure Compiler génèrent cette fonction 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.