chrome.i18n

refresh date: 2026-09-25 robots: noindex

Beschreibung

Verwenden Sie die chrome.i18n-Infrastruktur, um die Internationalisierung in Ihrer gesamten App oder Erweiterung zu implementieren.

Sie müssen alle für Nutzer sichtbaren Strings in einer Datei mit dem Namen messages.json speichern. Jedes Mal, wenn Sie eine neue Sprache hinzufügen, fügen Sie eine Nachrichtendatei in einem Verzeichnis mit dem Namen _locales/_localeCode_ hinzu, wobei localeCode ein Code wie en für Englisch ist.

Hier ist die Dateihierarchie für eine internationalisierte Erweiterung, die Englisch (en), Spanisch (es) und Koreanisch (ko) unterstützt:

Unterstützung mehrerer Sprachen

Angenommen, Sie haben eine Erweiterung mit den Dateien, die in der folgenden Abbildung dargestellt sind:

Wenn Sie diese Erweiterung internationalisieren möchten, benennen Sie jeden für Nutzer sichtbaren String und fügen ihn in eine Nachrichtendatei ein. Das Manifest, die CSS-Dateien und der JavaScript-Code der Erweiterung verwenden den Namen jedes Strings, um die lokalisierte Version abzurufen.

So sieht die Erweiterung aus, wenn sie internationalisiert ist (beachten Sie, dass sie immer noch nur englische Strings enthält):

<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"="" />

Wichtig: Wenn eine Erweiterung ein _locales-Verzeichnis hat, muss im Manifest „default_locale“ definiert sein.

Einige Hinweise zur Internationalisierung:

• Sie können alle unterstützten Sprachen verwenden. Wenn Sie ein nicht unterstütztes Gebietsschema verwenden, wird es von Google Chrome ignoriert.

• In manifest.json- und CSS-Dateien verweisen Sie so auf einen String mit dem Namen messagename:

  __MSG_messagename__
  

• Verweisen Sie im JavaScript-Code Ihrer Erweiterung oder App auf einen String namens messagename:

  chrome.i18n.getMessage("messagename")
  

• Bei jedem Aufruf von getMessage() können Sie bis zu 9 Strings angeben, die in die Nachricht aufgenommen werden sollen. Weitere Informationen finden Sie unter Beispiele: getMessage.

• Einige Nachrichten, z. B. @@bidi_dir und @@ui_locale, werden vom Internationalisierungssystem bereitgestellt. Eine vollständige Liste der vordefinierten Nachrichtennamen finden Sie im Abschnitt Vordefinierte Nachrichten.

• In messages.json hat jeder für Nutzer sichtbare String einen Namen, ein „message“-Element und ein optionales „description“-Element. Der Name ist ein Schlüssel wie „extName“ oder „search_string“, der den String identifiziert. „message“ gibt den Wert des Strings in dieser Sprache an. Die optionale „Beschreibung“ bietet Übersetzern Hilfe, die möglicherweise nicht sehen können, wie der String in Ihrer Erweiterung verwendet wird. Beispiel:

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

  Weitere Informationen finden Sie unter Formate: Gebietsschemaspezifische Nachrichten.

Sobald eine Erweiterung oder App internationalisiert ist, lässt sie sich ganz einfach übersetzen. Sie kopieren messages.json, übersetzen es und legen die Kopie in einem neuen Verzeichnis unter _locales ab. Wenn du beispielsweise Spanisch unterstützen möchtest, füge einfach eine übersetzte Kopie von messages.json unter _locales/es ein. Die folgende Abbildung zeigt die vorherige Erweiterung mit einer neuen spanischen Übersetzung.

Vordefinierte Nachrichten

Das Internationalisierungssystem bietet einige vordefinierte Nachrichten, die Sie bei der Lokalisierung unterstützen. Dazu gehören @@ui_locale, mit dem Sie die aktuelle Sprache der Benutzeroberfläche erkennen können, und einige @@bidi_...-Nachrichten, mit denen Sie die Textrichtung erkennen können. Letztere haben ähnliche Namen wie Konstanten in der Gadgets BIDI (bi-directional) API.

Die spezielle Nachricht @@extension_id kann in den CSS- und JavaScript-Dateien verwendet werden, unabhängig davon, ob die Erweiterung oder App lokalisiert ist. Diese Nachricht funktioniert nicht in Manifestdateien.

In der folgenden Tabelle werden die einzelnen vordefinierten Nachrichten beschrieben.

Name der Nachricht	Beschreibung
@@extension_id	Die Erweiterungs- oder App-ID. Sie können diesen String verwenden, um URLs für Ressourcen innerhalb der Erweiterung zu erstellen. Auch nicht lokalisierte Erweiterungen können diese Nachricht verwenden. Hinweis: Sie können diese Nachricht nicht in einer Manifestdatei verwenden.
@@ui_locale	Die aktuelle Sprache. Sie können diesen String verwenden, um länderspezifische URLs zu erstellen.
@@bidi_dir	Die Textrichtung für die aktuelle Sprache, entweder „ltr“ für rechtsläufige Sprachen wie Deutsch oder „rtl“ für linksläufige Sprachen wie Japanisch.
@@bidi_reversed_dir	Wenn @@bidi_dir „ltr“ ist, ist dies „rtl“, andernfalls „ltr“.
@@bidi_start_edge	Wenn @@bidi_dir „ltr“ ist, ist dies „left“, andernfalls „right“.
@@bidi_end_edge	Wenn @@bidi_dir „ltr“ ist, ist dies „right“, andernfalls „left“.

Hier ein Beispiel für die Verwendung von @@extension_id in einer CSS-Datei zum Erstellen einer URL:

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

Wenn die Erweiterungs-ID „abcdefghijklmnopqrstuvwxyzabcdef“ lautet, sieht die fett formatierte Zeile im vorherigen Code-Snippet so aus:

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

Hier ein Beispiel für die Verwendung von @@bidi_*-Nachrichten in einer CSS-Datei:

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

Für rechtsläufige Sprachen wie Deutsch werden die fett formatierten Zeilen zu:

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

Sprachen

Sie können aus vielen Sprachen auswählen, darunter auch einige (z. B. en), bei denen eine einzelne Übersetzung mehrere Varianten einer Sprache unterstützt (z. B. en_GB und en_US).

Unterstützte Gebietsschemen

Sie können alle vom Chrome Web Store unterstützten Sprachen verwenden.

Suchen von Nachrichten

Sie müssen nicht jeden String für jede unterstützte Sprache definieren. Solange die Datei messages.json des Standard-Locale einen Wert für jeden String enthält, wird Ihre Erweiterung oder App ausgeführt, unabhängig davon, wie dünnbesetzt eine Übersetzung ist. So sucht das Erweiterungssystem nach einer Nachricht:

1. Suchen Sie in der Nachrichtendatei (falls vorhanden) nach der bevorzugten Sprache des Nutzers. Wenn beispielsweise die Sprache von Google Chrome auf britisches Englisch (en_GB) eingestellt ist, sucht das System zuerst in _locales/en_GB/messages.json nach der Nachricht. Wenn diese Datei vorhanden ist und die Nachricht darin enthalten ist, sucht das System nicht weiter.
2. Wenn die bevorzugte Sprache des Nutzers eine Region enthält (d. h. die Sprache enthält einen Unterstrich: _), suchen Sie nach der Sprache ohne diese Region. Wenn die Nachrichtendatei en_GB beispielsweise nicht vorhanden ist oder die Nachricht nicht enthält, sucht das System in der Nachrichtendatei en. Wenn diese Datei vorhanden ist und die Nachricht darin enthalten ist, sucht das System nicht weiter.
3. Suchen Sie in der Nachrichtendatei nach dem Standardgebietsschema. Wenn beispielsweise die „default_locale“ der Erweiterung auf „es“ festgelegt ist und weder _locales/en_GB/messages.json noch _locales/en/messages.json die Nachricht enthält, verwendet die Erweiterung die Nachricht aus _locales/es/messages.json.

In der folgenden Abbildung ist die Nachricht „colores“ in allen drei von der Erweiterung unterstützten Sprachen vorhanden, „extName“ jedoch nur in zwei Sprachen. Wenn ein Nutzer Google Chrome auf US-Englisch verwendet, wird das Label „Colors“ angezeigt, während ein Nutzer von britischem Englisch „Colours“ sieht. Sowohl US-amerikanische als auch britische Nutzer sehen den Erweiterungsnamen „Hello World“. Da die Standardsprache Spanisch ist, sehen Nutzer, die Google Chrome in einer anderen Sprache als Englisch verwenden, das Label „Colores“ und den Erweiterungsnamen „Hola mundo“.

Gebietsschema des Browsers festlegen

Wenn Sie Übersetzungen testen möchten, können Sie die Sprache Ihres Browsers festlegen. In diesem Abschnitt erfahren Sie, wie Sie die Sprache in Windows, Mac OS X, Linux und ChromeOS festlegen.

Windows

Sie können die Sprache entweder über eine länderspezifische Tastenkombination oder über die Google Chrome-Benutzeroberfläche ändern. Die Methode mit Kurzbefehlen ist schneller, sobald sie eingerichtet ist, und ermöglicht es Ihnen, mehrere Sprachen gleichzeitig zu verwenden.

Länderspezifische Tastenkombination verwenden

So erstellen und verwenden Sie eine Verknüpfung, mit der Google Chrome mit einer bestimmten Sprache gestartet wird:

1. Erstellen Sie eine Kopie der Google Chrome-Verknüpfung, die sich bereits auf Ihrem Desktop befindet.
2. Benennen Sie die neue Verknüpfung entsprechend der neuen Sprache um.

3. Ändern Sie die Eigenschaften der Verknüpfung so, dass im Feld „Ziel“ die Flags --lang und --user-data-dir angegeben sind. Das Ziel sollte in etwa so aussehen:

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

4. Starten Sie Google Chrome, indem Sie auf die Verknüpfung doppelklicken.

Wenn Sie beispielsweise eine Verknüpfung erstellen möchten, mit der Google Chrome auf Spanisch (es) gestartet wird, können Sie eine Verknüpfung mit dem Namen chrome-es und dem folgenden Ziel erstellen:

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

Sie können beliebig viele Verknüpfungen erstellen, um Tests in mehreren Sprachen durchzuführen. Beispiel:

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

Hinweis: Die Angabe von --user-data-dir ist optional, aber praktisch. Wenn Sie ein Datenverzeichnis pro Sprache haben, können Sie den Browser in mehreren Sprachen gleichzeitig ausführen. Ein Nachteil ist, dass die Daten der Sprachen nicht geteilt werden. Sie müssen Ihre Erweiterung also mehrmals installieren – einmal pro Sprache. Das kann schwierig sein, wenn Sie die Sprache nicht sprechen. Weitere Informationen finden Sie unter Profile erstellen und verwenden.

Benutzeroberfläche verwenden

So ändern Sie die Spracheinstellung über die Benutzeroberfläche in Google Chrome für Windows:

1. App-Symbol > Optionen
2. Wähle den Tab Unter der Haube aus.
3. Scrollen Sie nach unten zu Webinhalt.
4. Klicken Sie auf Schriftart- und Spracheinstellungen ändern.
5. Wähle den Tab Sprachen aus.
6. Legen Sie über das Drop-down-Menü die Google Chrome-Sprache fest.
7. Chrome neu starten

Mac OS X

Wenn Sie die Sprache auf einem Mac ändern möchten, verwenden Sie die Systemeinstellungen.

1. Wählen Sie im Apple-Menü die Option Systemeinstellungen aus.
2. Wählen Sie im Bereich Privat die Option International aus.
3. Sprache und Standort auswählen
4. Chrome neu starten

Linux

Wenn Sie die Sprache unter Linux ändern möchten, beenden Sie zuerst Google Chrome. Legen Sie dann in einer Zeile die Umgebungsvariable LANGUAGE fest und starten Sie Google Chrome. Beispiel:

LANGUAGE=es ./chrome

ChromeOS

So ändern Sie die Spracheinstellung unter ChromeOS:

1. Wählen Sie in der Taskleiste die Einstellungen aus.
2. Wählen Sie im Abschnitt Sprachen und Eingabe das Drop-down-Menü Sprache aus.
3. Wenn Ihre Sprache nicht aufgeführt ist, klicken Sie auf Sprachen hinzufügen und fügen Sie sie hinzu.
4. Klicken Sie nach dem Hinzufügen neben der Sprache auf das Dreipunkt-Menü Weitere Aktionen und wählen Sie ChromeOS in dieser Sprache anzeigen aus.
5. Klicken Sie neben der festgelegten Sprache auf Neu starten, um ChromeOS neu zu starten.

Beispiele

Einfache Beispiele für die Internationalisierung finden Sie im Verzeichnis examples/api/i18n. Ein vollständiges Beispiel finden Sie unter examples/extensions/news. Weitere Beispiele und Hilfe zum Anzeigen des Quellcodes finden Sie unter Beispiele.

Beispiele: getMessage

Im folgenden Code wird eine lokalisierte Nachricht vom Browser abgerufen und als String angezeigt. Sie ersetzt zwei Platzhalter in der Nachricht durch die Strings „string1“ und „string2“.

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

So geben Sie einen einzelnen String an und verwenden ihn:

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

Weitere Informationen zu Platzhaltern finden Sie auf der Seite Gebietsschemaspezifische Nachrichten. Weitere Informationen zum Aufrufen von getMessage() finden Sie in der API-Referenz.

Beispiel: getAcceptLanguages

Im folgenden Code werden die akzeptierten Sprachen aus dem Browser abgerufen und als String angezeigt, wobei die einzelnen Sprachen durch ein Komma getrennt sind.

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

Weitere Informationen zum Aufrufen von getAcceptLanguages() finden Sie in der API-Referenz.

Beispiel: detectLanguage

Der folgende Code erkennt bis zu drei Sprachen aus dem angegebenen String und zeigt das Ergebnis als Strings an, die durch Zeilenumbrüche getrennt sind.

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

Weitere Informationen zum Aufrufen von detectLanguage(inputText) finden Sie in der API-Referenz.

Typen

LanguageCode

Chrome 47 oder höher

Ein ISO-Sprachcode wie en oder fr. Eine vollständige Liste der von dieser Methode unterstützten Sprachen finden Sie unter kLanguageInfoTable. Bei einer unbekannten Sprache wird und zurückgegeben. Das bedeutet, dass [Prozentsatz] des Textes für CLD unbekannt ist.

Typ

String

Methoden

detectLanguage()

Promise Chrome 47 und höher

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

Erkennt die Sprache des bereitgestellten Textes mithilfe von CLD.

Parameter

• Text

  String

  Vom Nutzer eingegebener String, der übersetzt werden soll.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (result: object) => void

  • Ergebnis

    Objekt

    LanguageDetectionResult-Objekt, das die Zuverlässigkeit der erkannten Sprache und ein Array von DetectedLanguage enthält

    • isReliable

      boolean

      Zuverlässigkeit der von CLD erkannten Sprache

    • Sprachen

      object[]

      Array von detectedLanguage

      • Sprache

        String

      • Prozentsatz

        Zahl

        Der Prozentsatz der erkannten Sprache

Ausgabe

• Promise<object>

  Chrome 99 oder höher

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getAcceptLanguages()

Promise

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

Ruft die akzeptierten Sprachen des Browsers ab. Diese unterscheidet sich von der vom Browser verwendeten Sprache. Verwenden Sie i18n.getUILanguage, um die Sprache abzurufen.

Parameter

• callback

  function optional

  Der Parameter callback sieht so aus:

  (languages: string[]) => void

  • Sprachen

    String[]

    Array von LanguageCode

Ausgabe

• Promise<LanguageCode[]>

  Chrome 99 oder höher

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getMessage()

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

Ruft den lokalisierten String für die angegebene Nachricht ab. Wenn die Nachricht fehlt, gibt diese Methode einen leeren String ('') zurück. Wenn das Format des getMessage()-Aufrufs falsch ist, z. B. wenn messageName kein String ist oder das Array substitutions mehr als 9 Elemente enthält, gibt diese Methode undefined zurück.

Parameter

• messageName

  String

  Der Name der Nachricht, wie in der Datei messages.json angegeben.

• Substitutionen

  any optional

  Bis zu 9 Ersetzungsstrings, falls für die Nachricht erforderlich.

• Optionen

  Objekt optional

  Chrome 79 oder höher
  • escapeLt

    Boolesch optional

    < in der Übersetzung zu < maskieren. Dies gilt nur für die Nachricht selbst, nicht für die Platzhalter. Entwickler können diese Option verwenden, wenn die Übersetzung in einem HTML-Kontext verwendet wird. Closure-Vorlagen, die mit Closure Compiler verwendet werden, generieren dies automatisch.

Ausgabe

• String

  Nachricht für die aktuelle Sprache lokalisiert.

getUILanguage()

chrome.i18n.getUILanguage(): string

Ruft die Sprache der Benutzeroberfläche des Browsers ab. Dies unterscheidet sich von i18n.getAcceptLanguages, das die bevorzugten Nutzersprachen zurückgibt.

Ausgabe

• String

  Der Sprachcode der Browser-UI, z. B. en-US oder fr-FR.