chrome.i18n

Description

Utilisez l'infrastructure chrome.i18n pour implémenter l'internationalisation dans l'ensemble de votre application ou de votre extension.

Vous devez placer toutes les chaînes visibles par l'utilisateur dans un fichier nommé messages.json. À chaque fois 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 tel que en pour l'anglais.

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

Dans le répertoire de l'extension: manifest.json, *.html, *.js, _locales. Dans le répertoire _locales: les répertoires "en", "es" et "ko", contenant chacun un fichier messages.json

Compatibilité avec plusieurs langues

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

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

Pour internationaliser cette extension, vous devez nommer chaque chaîne visible par l'utilisateur et la placer dans un . Le fichier manifeste, les fichiers CSS et le code JavaScript de l'extension utilisent le nom de chaque chaîne pour obtenir ses version localisée.

Voici à quoi ressemble l'extension quand elle sera internationalisée (notez qu'elle ne contient toujours Chaînes en anglais):

<img "__msg_extname__",="" "default_locale"="" "fr".="" "nomext."="" "bonjour="" _locales=&quot;&quot; a=&quot;&quot; alt="Dans le fichier manifest.json, " and=&quot;&quot; été="" changed=&quot;&quot; chrome.i18n.getmessage("nomextension").="" defines=&quot;&quot; en=&quot;&quot; file=&quot;&quot; file,=&quot;&quot; has=&quot;&quot; hello=&quot;&quot; in=&quot;&quot; item=&quot;&quot; javascript=&quot;&quot; messages.json=&quot;&quot; named=&quot;&quot; new="" src=&quot;/static/images/i18n-after-1.gif&quot; the=&quot;&quot; to=&quot;&quot; value="" world"="" /&gt;

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 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. Voir Exemple: getMessage pour en savoir plus.

  • Certains messages, tels que @@bidi_dir et @@ui_locale, sont fournis par l'internationalisation du système d'exploitation. 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 "message" et une option facultative &quot;description&quot; élément. Le nom est une clé, comme "extName" ou "chaîne_recherche" qui identifie le . Le "message" spécifie la valeur de la chaîne dans ces paramètres régionaux. La "description" facultative qui aide les traducteurs, qui ne savent peut-être pas comment la chaîne est utilisée . 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 ou une application est internationalisée, la traduction devient un jeu d'enfant. Vous copiez messages.json, le traduire et de placer la copie dans un nouveau répertoire sous _locales. Par exemple, pour prendre en charge Espagnol, il suffit de placer une copie traduite de messages.json sous _locales/es. La figure suivante affiche l'extension précédente avec une nouvelle traduction en espagnol.

Cette image est identique à la figure précédente, mais avec un nouveau fichier dans _locales/es/messages.json qui contient 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 vos contenus. Ces inclure @@ui_locale afin que vous puissiez 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 API Google Gadgets BIDI (bidirectionnelle).

Le message spécial @@extension_id peut être utilisé dans les fichiers CSS et JavaScript, que le paramètre l'extension ou l'application est localisée. Ce message ne fonctionne pas dans les fichiers manifestes.

Le tableau suivant décrit chaque message prédéfini.

Nom du messageDescription
@@extension_idL'extension ou l'ID de l'application vous pouvez utiliser cette chaîne pour construire les URL des ressources dans 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_localeParamè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 les langues qui s'écrivent de droite à gauche, comme le japonais.
@@bidi_reversed_dirSi @@bidi_dir est "ltr", il s'agit de "rtl". sinon la valeur est "ltr".
@@bidi_start_edgeSi @@bidi_dir est "ltr", il s'agit de "left". sinon c'est la bonne.
@@bidi_end_edgeSi @@bidi_dir correspond à "ltr", il s'agit de "right". sinon c'est "left".

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 dans le code précédent doit être indiquée. l'extrait 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 certains (en, par exemple) qui permettent une seule traduction accepter plusieurs variantes d'une langue (par exemple, en_GB et en_US).

Paramètres régionaux pris en charge

Vous pouvez utiliser les paramètres régionaux compatibles avec le Chrome Web Store.

Recherche de messages

Il n'est pas nécessaire de définir toutes les chaînes pour tous les paramètres régionaux acceptés. Tant que les paramètres régionaux par défaut messages.json contient une valeur pour chaque chaîne. Votre extension ou application s'exécutera quelle que soit la méthode une traduction creuse. Voici comment le système d'extension recherche un message:

  1. 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 Google Les paramètres régionaux de Chrome étant définis sur l'anglais britannique (en_GB), le système recherche d'abord le message dans _locales/en_GB/messages.json Si ce fichier existe et que le message s'y trouve, le système recherche pas plus loin.
  2. 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: _), 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 consulte le fichier de messages en. Si ce fichier existe et le message est là, le système ne cherche pas plus loin.
  3. Recherchez les paramètres régionaux par défaut dans le fichier de messages. Par exemple, si l'extension "paramètres régionaux par défaut" est défini sur "es", et ni _locales/en_GB/messages.json ni _locales/en/messages.json contient le message, l'extension utilise le message de _locales/es/messages.json

Dans la figure suivante, le message intitulé "colores" se trouve dans les trois paramètres régionaux dans lesquels l'extension pris en charge, mais "extName" n’est disponible que dans deux des langues. Chaque fois qu'un utilisateur exécutant Google Chrome aux États-Unis L'anglais voit le libellé "Colors", un utilisateur de l'anglais britannique voit "Colours". L'anglais américain et Les utilisateurs anglophones britanniques voient le nom de l'extension "Hello World". Comme la langue par défaut est l'espagnol, Les utilisateurs exécutant Google Chrome dans une autre langue que l'anglais voient la mention "Couleurs". et l'extension et nommez-la "Hola mundo".

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

Comment 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 vous explique comment configurer 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 est plus rapide, une fois configurée et vous permet d'utiliser plusieurs langues à la fois.

Utilisation d'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:

  1. Créez une copie du raccourci Google Chrome déjà enregistré 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 "Target" (Cible) spécifie --lang et options --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 un raccourci nommé chrome-es ayant 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'UI

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 de l'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 de police et de langue.
  5. Sélectionnez l'onglet Langues.
  6. Dans le menu déroulant, définissez la langue de Google Chrome.
  7. Redémarrer Chrome

Mac OS X

Pour modifier les paramètres régionaux sur 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. Choisissez votre langue et votre zone géographique
  4. Redémarrer Chrome

Linux

Pour modifier les paramètres régionaux sous Linux, commencez par quitter Google Chrome. Ensuite, sur une seule ligne, indiquez la langue 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, cliquez sur le menu déroulant Langue.
  3. Si votre langue ne figure pas dans la liste, cliquez sur Ajouter des langues, puis ajoutez-la.
  4. Cliquez ensuite sur l'élément de menu Autres actions à trois points à côté de votre langue, puis sélectionnez Afficher ChromeOS dans cette langue
  5. 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 une Pour consulter un exemple complet, consultez la section examples/extensions/news. Pour découvrir d'autres exemples et obtenir de l'aide concernant la code source, consultez la section Exemples.

Exemples: getMessage

Le code suivant récupère un message localisé du navigateur et l'affiche sous forme de chaîne. Il remplace deux espaces réservés dans le message par les chaînes "string1" et "chaîne2".

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 appelez getMessage(), consultez la documentation de référence de l'API.

Exemple: getAcceptLanguages

Le code suivant récupère les langues d'acceptation à partir du navigateur et les affiche sous forme de chaîne en en séparant chaque langage d'acceptation par un point-virgule (,).

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.

Exemple: détectLanguage

Le code suivant détecte jusqu'à 3 langues de la chaîne donnée et affiche le résultat comme suit : de chaînes séparées par un saut 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 (version 47 ou ultérieure)

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()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome (version 47 ou ultérieure)
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

Détecte la langue du texte fourni à l'aide de CLD.

Paramètres

  • texte

    chaîne

    Chaîne saisie par l'utilisateur à traduire.

  • rappel

    function facultatif

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

    (result: object) => void

    • résultat

      objet

      Objet LanguageDetectionResult qui contient la fiabilité langugae détectée et le tableau de DetectedLanguage

      • isReliable

        booléen

        Fiabilité de la langue détectée par CLD

      • langues

        object[]

        tableau dedetectLanguage

        • language

          chaîne

        • pourcentage

          Nombre

          Pourcentage de la langue détectée

Renvoie

  • Promise&lt;object&gt;

    Chrome 99 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getAcceptLanguages()

<ph type="x-smartling-placeholder"></ph> Promesse
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

Récupère les langues acceptées du navigateur. Ils diffèrent des paramètres régionaux utilisés par le navigateur. Pour obtenir les paramètres régionaux, utilisez i18n.getUILanguage.

Paramètres

  • rappel

    function facultatif

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

    (languages: string[]) => void

    • langues

      chaîne[]

      Tableau de LanguageCode

Renvoie

  • Promise&lt;LanguageCode[]&gt;

    Chrome 99 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 si le tableau substitutions comporte plus de neuf éléments), cette méthode 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 et versions ultérieures
    • escapeLt

      Booléen facultatif

      Échappez < dans la traduction en &lt;. 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.