chrome.i18n

Description

Fichier manifeste

Si une extension possède un répertoire /_locales, le fichier manifeste doit définir "default_locale".

Concepts et utilisation

Vous devez placer toutes ses 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 tel que en pour l'anglais.

Voici la hiérarchie des fichiers d'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 illustré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 toujours que des chaînes en anglais):

Voici quelques remarques sur l'internationalisation:

• Vous pouvez utiliser n'importe quelle langue prise en charge. Si vous utilisez une langue non prise en charge, 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 à 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. Pour obtenir la liste complète des noms de messages prédéfinis, consultez la section Messages prédéfinis.

• Dans messages.json, chaque chaîne visible par l'utilisateur possède 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 aide les traducteurs, qui ne peuvent pas toujours 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 Formats: messages spécifiques à la langue.

Une fois qu'une extension est internationalisée, la traduire est simple. Vous copiez messages.json, le traduisez, puis placez la copie dans un nouveau répertoire sous /_locales. Par exemple, pour prendre en charge l'espagnol, il suffit de placer une copie traduite de messages.json sous /_locales/es. L'image 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. Cela inclut @@ui_locale, qui vous permet de détecter la langue de l'UI actuelle, et quelques messages @@bidi_... qui vous permettent de détecter l'orientation du texte. Les messages de ce type portent 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 soit localisée ou non. Ce message ne fonctionne pas dans les fichiers manifestes.

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

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:

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

Paramètres régionaux

Vous avez le choix entre de nombreux paramètres régionaux, y compris certains (comme en) qui permettent à une seule traduction de prendre en charge plusieurs variantes d'une langue (comme en_GB et en_US).

Vous pouvez localiser votre extension dans n'importe quelle langue prise en charge par le Chrome Web Store. Si votre langue n'est pas proposée, choisissez la langue la plus proche. Par exemple, si la langue par défaut de votre extension est "de_CH", sélectionnez "de" dans le Chrome Web Store.

Rechercher des messages

Vous n'avez pas besoin de définir chaque chaîne pour chaque paramètre régional compatible. Tant que le fichier messages.json du paramètre régional par défaut comporte une valeur pour chaque chaîne, votre extension ou votre application s'exécute, quelle que soit la rareté de la traduction. 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 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 /_locales/en_GB/messages.json. Si ce fichier existe et que le message s'affiche, le système ne recherche rien d'autre.
2. Si les paramètres régionaux préférés de l'utilisateur comportent une région (c'est-à-dire qu'ils comportent 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 recherche dans le fichier de messages en. Si ce fichier existe et que le message s'affiche, le système ne recherche rien d'autre.
3. Recherchez les paramètres régionaux par défaut dans le fichier de messages. Par exemple, si "default_locale" de l'extension est défini sur "es", et que ni /_locales/en_GB/messages.json ni /_locales/en/messages.json ne contiennent le message, l'extension utilise le message de /_locales/es/messages.json.

Dans l'image suivante, le message nommé "colores" est disponible dans les trois langues prises en charge par l'extension, mais "extName" n'est disponible que dans deux d'entre elles. Lorsqu'un utilisateur exécutant Google Chrome en anglais américain voit le libellé "Colors" (Couleurs), un utilisateur de l'anglais britannique voit "Colours" (Couleurs). Les utilisateurs anglophones des États-Unis et du Royaume-Uni voient le nom de l'extension "Hello World". Étant donné que la langue par défaut est l'espagnol, les utilisateurs exécutant Google Chrome dans une autre langue que l'anglais voient le libellé "Colores" 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, Linux et ChromeOS.

Windows

Vous pouvez modifier les paramètres régionaux à l'aide d'un raccourci spécifique aux paramètres régionaux ou de l'interface utilisateur de Google Chrome. L'approche par raccourci est plus rapide une fois que vous l'avez 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 des paramètres régionaux spécifiques:

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 au nouveau paramètre régional.

3. Modifiez les propriétés du raccourci afin que le champ "Target" (Cible) spécifie les options --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 vous permet de les tester facilement 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:

1. Icône de l'application > Options
2. Sélectionnez l'onglet En coulisses.
3. Faites défiler la page jusqu'à Contenu Web.
4. Cliquez sur Modifier les paramètres de police et de langue.
5. Accédez à l'onglet Langues.
6. Utilisez le menu déroulant pour définir la langue de Google Chrome.
7. Redémarrer Chrome

macOS

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

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

Linux

Pour modifier les paramètres régionaux sous Linux, fermez 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 sur ChromeOS:

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

Exemples

Vous trouverez des exemples 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 pour afficher le code source, consultez la section Exemples.

getMessage()

Le code suivant récupère un message localisé à partir 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 "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 à la langue. 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 à partir du navigateur et les affiche sous forme de chaîne en séparant chaque langue acceptée par une 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.

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 nouvelles lignes.

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.

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

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

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

chrome.i18n.getUILanguage()