chrome.i18n

refresh date: 2026-09-25 robots: noindex

Beschrijving

Gebruik de chrome.i18n-infrastructuur om internationalisering te implementeren in je hele app of extensie.

Je moet alle voor gebruikers zichtbare tekenreeksen in een bestand met de naam messages.json zetten. Elke keer dat je een nieuwe landinstelling toevoegt, voeg je een berichtenbestand toe aan een map met de naam _locales/_localeCode_, waarbij localeCode een code is zoals en voor Engels.

Hier is de bestandshiërarchie voor een geïnternationaliseerde extensie die Engels (en), Spaans (es) en Koreaans (ko) ondersteunt:

In de extensiemap: manifest.json, *.html, *.js, _locales-map. In de directory _locales: de directory's en, es en ko, elk met een messages.json-bestand.

Meerdere talen ondersteunen

Stel dat je een extensie hebt met de bestanden in de volgende afbeelding:

Een manifest.json-bestand en een bestand met JavaScript. Het json-bestand heeft

Als je deze extensie wilt internationaliseren, geef je elke voor de gebruiker zichtbare tekenreeks een naam en plaats je deze in een berichtenbestand. Het manifest, de CSS-bestanden en de JavaScript-code van de extensie gebruiken de naam van elke tekenreeks om de gelokaliseerde versie op te halen.

Zo ziet de extensie eruit als deze is geïnternationaliseerd (houd er rekening mee dat deze nog steeds alleen Engelse tekenreeksen bevat):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="In the manifest.json file, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" defines="" en="" file="" file,="" has="" hello="" in="" item="" javascript="" messages.json="" named="" new="" src="/static/images/i18n-after-1.gif" the="" to="" value="" world"="" />

Een paar opmerkingen over internationalisering:

  • Je kunt een van de ondersteunde landinstellingen gebruiken. Als je een niet-ondersteunde landinstelling gebruikt, negeert Google Chrome deze.

  • In manifest.json- en CSS-bestanden verwijs je zo naar een tekenreeks met de naam messagename:

    __MSG_messagename__

  • Verwijs in de JavaScript-code van je extensie of app naar een tekenreeks met de naam messagename, zoals hier:

    chrome.i18n.getMessage("messagename")

  • In elke aanroep naar getMessage() kunt u maximaal 9 tekenreeksen opgeven die in het bericht moeten worden opgenomen. Ga naar Voorbeelden: getMessage voor meer informatie.

  • Sommige berichten, zoals @@bidi_dir en @@ui_locale, worden geleverd door het internationaliseringssysteem. Ga naar het gedeelte Vooraf gedefinieerde berichten voor een volledige lijst met vooraf gedefinieerde berichtnamen.

  • In messages.json heeft elke voor de gebruiker zichtbare tekenreeks een naam, een berichtitem en een optioneel beschrijvingsitem. De naam is een sleutel, zoals extName of search_string, die de tekenreeks identificeert. Het bericht geeft de waarde van de tekenreeks in deze landinstelling aan. De optionele beschrijving biedt hulp aan vertalers, die misschien niet kunnen zien hoe de tekenreeks wordt gebruikt in je extensie. Voorbeeld:

    {
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}

    Ga voor meer informatie naar Indelingen: landspecifieke berichten.

Nadat een extensie of app is geïnternationaliseerd, is het vertalen ervan eenvoudig. Je kopieert messages.json, vertaalt het en plaatst de kopie in een nieuwe directory onder _locales. Als je bijvoorbeeld Spaans wilt ondersteunen, plaats je een vertaalde kopie van messages.json onder _locales/es. In de volgende afbeelding staat de vorige extensie met een nieuwe Spaanse vertaling.

Dit ziet er hetzelfde uit als de vorige afbeelding, maar met een nieuw bestand op _locales/es/messages.json dat een Spaanse vertaling van de berichten bevat.

Vooraf gedefinieerde berichten

Het internationaliseringssysteem biedt een aantal vooraf gedefinieerde berichten om je te helpen bij de lokalisatie. Deze omvatten @@ui_locale, zodat je de huidige UI-landinstelling kunt detecteren, en een paar @@bidi_...-berichten waarmee je de tekstrichting kunt detecteren. De laatste berichten hebben vergelijkbare namen als constanten in de gadgets BIDI (bi-directional) API.

Het speciale bericht @@extension_id kan worden gebruikt in de css- en JavaScript-bestanden, ongeacht of de extensie of app is gelokaliseerd. Dit bericht werkt niet in manifestbestanden.

In de volgende tabel staat een beschrijving van elk vooraf gedefinieerd bericht.

BerichtnaamBeschrijving
@@extension_idDe extensie- of app-ID. Je kunt deze tekenreeks gebruiken om URL's te maken voor bronnen in de extensie. Zelfs niet-gelokaliseerde extensies kunnen dit bericht gebruiken.
Opmerking: Je kunt dit bericht niet gebruiken in een manifestbestand.
@@ui_localeDe huidige landinstelling. Je kunt deze tekenreeks gebruiken om landspecifieke URL's te maken.
@@bidi_dirDe tekstrichting voor de huidige landinstelling, 'ltr' voor talen die van links naar rechts worden geschreven, zoals het Engels, of 'rtl' voor talen die van rechts naar links worden geschreven, zoals het Japans.
@@bidi_reversed_dirAls de @@bidi_dir 'ltr' is, is dit 'rtl'. Anders is het 'ltr'.
@@bidi_start_edgeAls de @@bidi_dir ltr is, is dit left. Anders is het right.
@@bidi_end_edgeAls de @@bidi_dir 'ltr' is, is dit 'right'. Anders is het 'left'.

Hier volgt een voorbeeld van het gebruik van @@extension_id in een CSS-bestand om een URL te maken:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

Als de extensie-ID abcdefghijklmnopqrstuvwxyzabcdef is, wordt de vetgedrukte regel in het vorige codefragment:

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

Hier is een voorbeeld van het gebruik van @@bidi_*-berichten in een CSS-bestand:

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;
}

Voor talen die van links naar rechts worden geschreven, zoals het Nederlands, worden de vetgedrukte regels:

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

Landen

Je kunt kiezen uit veel landinstellingen, waaronder enkele (zoals en) waarmee één vertaling meerdere varianten van een taal ondersteunt (zoals en_GB en en_US).

Ondersteunde landinstellingen

Je kunt een van de landen gebruiken die de Chrome Web Store ondersteunt.

Berichten zoeken

Je hoeft niet elke tekenreeks voor elke ondersteunde landinstelling te definiëren. Zolang het bestand messages.json van de standaardlandinstelling een waarde heeft voor elke tekenreeks, wordt je extensie of app uitgevoerd, ongeacht hoe schaars een vertaling is. Zo zoekt het extensiesysteem naar een bericht:

  1. Zoek in het berichtenbestand (als dat er is) naar de voorkeurslandinstelling van de gebruiker. Als de landinstelling van Google Chrome bijvoorbeeld is ingesteld op Brits-Engels (en_GB), zoekt het systeem eerst naar het bericht in _locales/en_GB/messages.json. Als dat bestand bestaat en het bericht erin staat, zoekt het systeem niet verder.
  2. Als de voorkeurslandinstelling van de gebruiker een regio heeft (dat wil zeggen dat de landinstelling een underscore heeft: _), zoek je de landinstelling zonder die regio. Als het berichtenbestand en_GB bijvoorbeeld niet bestaat of het bericht niet bevat, zoekt het systeem in het berichtenbestand en. Als dat bestand bestaat en het bericht erin staat, zoekt het systeem niet verder.
  3. Zoek in het berichtenbestand naar de standaard landinstelling. Als de default_locale van de extensie bijvoorbeeld is ingesteld op es en noch _locales/en_GB/messages.json noch _locales/en/messages.json het bericht bevat, gebruikt de extensie het bericht uit _locales/es/messages.json.

In de volgende afbeelding staat het bericht met de naam colores in alle 3 de landinstellingen die de extensie ondersteunt, maar extName staat in maar 2 van de landinstellingen. Overal waar een gebruiker die Google Chrome in het Amerikaans-Engels gebruikt het label Colors ziet, ziet een gebruiker van Brits-Engels Colours. Zowel gebruikers van Amerikaans-Engels als Brits-Engels zien de extensienaam Hello World. Omdat de standaardtaal Spaans is, zien gebruikers die Google Chrome in een andere taal dan Engels gebruiken, het label Colores en de extensienaam Hola mundo.

4 bestanden: manifest.json en 3 messages.json-bestanden (voor es, en en en_GB). De bestanden es en en tonen vermeldingen voor berichten met de naam

De landinstelling van je browser instellen

Als je vertalingen wilt testen, kun je de landinstelling van je browser instellen. In dit gedeelte staat hoe je de landinstelling instelt in Windows, Mac OS X, Linux en ChromeOS.

Windows

Je kunt de landinstelling wijzigen met een landspecifieke sneltoets of de UI van Google Chrome. De sneltoetsmethode is sneller nadat je deze hebt ingesteld en je kunt meerdere talen tegelijk gebruiken.

Een landspecifieke sneltoets gebruiken

Zo maak en gebruik je een snelkoppeling die Google Chrome start met een bepaalde landinstelling:

  1. Maak een kopie van de Google Chrome-snelkoppeling die al op je bureaublad staat.
  2. Wijzig de naam van de nieuwe snelkoppeling zodat deze overeenkomt met de nieuwe landinstelling.

  3. Wijzig de eigenschappen van de snelkoppeling zodat het veld Doel de markeringen --lang en --user-data-dir bevat. Het doel ziet er ongeveer zo uit:

    path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir

  4. Start Google Chrome door te dubbelklikken op de snelkoppeling.

Als je bijvoorbeeld een snelkoppeling wilt maken die Google Chrome start in het Spaans (es), maak je een snelkoppeling met de naam chrome-es met het volgende doel:

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

Je kunt zoveel snelkoppelingen maken als je wilt, zodat je makkelijk in meerdere talen kunt testen. Voorbeeld:

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
De UI gebruiken

Zo wijzig je de landinstelling via de UI in Google Chrome voor Windows:

  1. App-icoon > Opties
  2. Kies het tabblad Under the Hood (Onder de motorkap).
  3. Scroll omlaag naar Webcontent.
  4. Klik op Instellingen voor lettertype en taal wijzigen.
  5. Kies het tabblad Talen.
  6. Gebruik het dropdownmenu om de taal van Google Chrome in te stellen.
  7. Chrome opnieuw starten

Mac OS X

Als je de landinstelling op een Mac wilt wijzigen, gebruik je de systeemvoorkeuren.

  1. Kies Systeemvoorkeuren in het Apple-menu.
  2. Kies in het gedeelte Persoonlijk de optie Internationaal.
  3. Je taal en locatie kiezen
  4. Chrome opnieuw starten

Linux

Als je de landinstelling op Linux wilt wijzigen, sluit je eerst Google Chrome af. Stel daarna op één regel de omgevingsvariabele LANGUAGE in en start Google Chrome. Voorbeeld:

LANGUAGE=es ./chrome

ChromeOS

Zo wijzig je de landinstelling in ChromeOS:

  1. Kies Instellingen in het systeemvak.
  2. Kies in het gedeelte Talen en invoer het dropdownmenu Taal.
  3. Als je taal niet wordt vermeld, klik je op Talen toevoegen en voeg je de taal toe.
  4. Klik nadat je de taal hebt toegevoegd op het menu-item Meer acties met 3 stippen naast de taal en kies ChromeOS weergeven in deze taal.
  5. Klik op de knop Opnieuw opstarten die naast de ingestelde taal verschijnt om ChromeOS opnieuw op te starten.

Voorbeelden

Je vindt eenvoudige voorbeelden van internationalisering in de directory examples/api/i18n. Ga naar examples/extensions/news voor een volledig voorbeeld. Ga naar Samples voor andere voorbeelden en hulp bij het bekijken van de broncode.

Voorbeelden: getMessage

De volgende code haalt een gelokaliseerd bericht op uit de browser en geeft dit weer als een tekenreeks. De functie vervangt 2 tijdelijke aanduidingen in het bericht door de tekenreeksen 'string1' en 'string2'.

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

Zo voert u één tekenreeks in en gebruikt u deze:

  // 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."
    }
  }
}

Ga naar de pagina Landinstellingsspecifieke berichten voor meer informatie over tijdelijke aanduidingen. Ga naar de API-referentie voor meer informatie over het aanroepen van getMessage().

Voorbeeld: getAcceptLanguages

De volgende code haalt accept-languages op uit de browser en toont deze als een tekenreeks door elke accept-language te scheiden met een komma.

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

Ga naar de API-referentie voor meer informatie over hoe u getAcceptLanguages() aanroept.

Voorbeeld: detectLanguage

De volgende code herkent maximaal 3 talen in de opgegeven tekenreeks en toont het resultaat als tekenreeksen gescheiden door nieuwe regels.

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;
  });
}

Ga naar de API-referentie voor meer informatie over het aanroepen van detectLanguage(inputText).

Typen

LanguageCode

Chrome 47+

Een ISO-taalcode, zoals en of fr. Ga naar kLanguageInfoTable voor een volledige lijst met talen die door deze methode worden ondersteund. Voor een onbekende taal wordt und geretourneerd, wat betekent dat [percentage] van de tekst onbekend is voor CLD

Type

tekenreeks

Methoden

detectLanguage()

Promise Chrome 47+ 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
): Promise<object>

Detecteert de taal van de ingevoerde tekst met CLD.

Parameters

  • tekst

    tekenreeks

    De door de gebruiker ingevoerde tekenreeks die moet worden vertaald.

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (result: object) => void

    • resultaat

      object

      LanguageDetectionResult-object dat de betrouwbaarheid van de gedetecteerde taal en een matrix van DetectedLanguage bevat

      • isReliable

        booleaans

        Betrouwbaarheid van door CLD gedetecteerde taal

      • talen

        object[]

        array van detectedLanguage

        • taal

          tekenreeks

        • percentage

          getal

          Het percentage van de gedetecteerde taal

Retourzendingen

  • Promise<object>

    Chrome 99 of hoger

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getAcceptLanguages()

Promise 
chrome.i18n.getAcceptLanguages(
  callback?: function,
): Promise<LanguageCode[]>

Haalt de geaccepteerde talen van de browser op. Dit is anders dan de landinstelling die de browser gebruikt. Gebruik i18n.getUILanguage om de landinstelling op te halen.

Parameters

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (languages: string[]) => void

    • talen

      tekenreeks[]

      Matrix van LanguageCode

Retourzendingen

  • Promise<LanguageCode[]>

    Chrome 99 of hoger

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getMessage()

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

Haalt de gelokaliseerde tekenreeks voor het opgegeven bericht op. Als het bericht ontbreekt, retourneert deze methode een lege tekenreeks (''). Als de indeling van de aanroep van getMessage() onjuist is, bijvoorbeeld als messageName geen tekenreeks is of de matrix substitutions meer dan 9 elementen bevat, retourneert deze methode undefined.

Parameters

  • messageName

    tekenreeks

    De naam van het bericht, zoals aangegeven in het bestand messages.json.

  • vervangingen

    alleen optioneel

    Maximaal 9 vervangingstekenreeksen, als het bericht deze vereist.

  • opties

    object optioneel

    Chrome 79+
    • escapeLt

      booleaans optioneel

      Escape < in vertaling naar &lt;. Dit is alleen van toepassing op het bericht zelf, niet op de tijdelijke aanduidingen. Ontwikkelaars kunnen dit gebruiken als de vertaling wordt gebruikt in een HTML-context. Closure-templates die worden gebruikt met Closure Compiler, genereren dit automatisch.

Retourzendingen

  • tekenreeks

    Bericht gelokaliseerd voor de huidige landinstelling.

getUILanguage()

chrome.i18n.getUILanguage(): string

Haalt de taal van de browser-UI op. Dit is anders dan i18n.getAcceptLanguages, die de voorkeurstalen van de gebruiker retourneert.

Retourzendingen

  • tekenreeks

    De taalcode van de browser-UI, zoals en-US of fr-FR.