browser.i18n

Beschreibung

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

Manifest

Wenn eine Erweiterung ein /_locales-Verzeichnis hat, muss im Manifest "default_locale" definiert sein.

Konzepte und Verwendung

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

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:

  browser.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 internationalisiert ist, ist die Übersetzung unkompliziert. 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 Englisch oder „rtl“ für linksläufige Sprachen wie Arabisch.
@@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).

Sie können Ihre Erweiterung für alle Sprachen lokalisieren, die vom Chrome Web Store unterstützt werden. Wenn Ihre Sprache hier nicht aufgeführt ist, wählen Sie die am besten passende Alternative aus. Wenn die Standardsprache Ihrer Erweiterung beispielsweise "de_CH" ist, wählen Sie im Chrome Web Store "de" aus.

Gebietsschema-Code	Sprache (Region)
ar	Arabisch
am	Amharisch
bg	Bulgarisch
bn	Bengalisch
ca	Katalanisch
cs	Tschechisch
da	Dänisch
de	Deutsch
el	Griechisch
en	Englisch
en_AU	Englisch (Australien)
en_GB	Englisch (Vereinigtes Königreich)
en_US	Englisch (USA)
es	Spanisch
es_419	Spanisch (Lateinamerika und Karibik)
et	Estnisch
fa	Persisch
fi	Finnisch
fil	Philippinisch
fr	Französisch
gu	Gujarati
he	Hebräisch
hi	Hindi
hr	Kroatisch
hu	Ungarisch
id	Indonesisch
it	Italienisch
ja	Japanisch
kn	Kannada
ko	Koreanisch
lt	Litauisch
lv	Lettisch
ml	Malayalam
mr	Marathi
ms	Malaiisch
nl	Niederländisch
no	Norwegian
pl	Polnisch
pt_BR	Portugiesisch (Brasilien)
pt_PT	Portugiesisch (Portugal)
ro	Rumänisch
ru	Russisch
sk	Slowakisch
sl	Slowenisch
sr	Serbisch
sv	Schwedisch
sw	Swahili
ta	Tamil
te	Telugu
th	Thailändisch
tr	Türkisch
uk	Ukrainisch
vi	Vietnamesisch
zh_CN	Chinesisch (China)
zh_TW	Chinesisch (Taiwan)

Nachrichten suchen

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 das Gebietsschema unter Windows, macOS, Linux und ChromeOS festlegen.

Windows

Sie können die Sprache entweder über eine länderspezifische Tastenkombination oder über die Google Chrome-Benutzeroberfläche ändern. Nach der Einrichtung ist die Kurzbefehl-Methode schneller und ermöglicht es dir, 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 Kurzbefehle 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. Scrolle 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

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

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.

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.

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.

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 und höher browser.* seit Chrome 148

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

Chrome 47 und höher browser.* seit Chrome 148

browser.i18n.detectLanguage(
  text: string,
): Promise<object>

Erkennt die Sprache des bereitgestellten Textes mithilfe von CLD.

Parameter

• Text

  String

  Vom Nutzer eingegebener String, der übersetzt werden soll.

Ausgabe

• Promise<object>

  Chrome 99 und höher browser.* seit Chrome 148

getAcceptLanguages()

browser.i18n.getAcceptLanguages(): 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.

Ausgabe

• Promise<LanguageCode[]>

  Chrome 99 und höher browser.* seit Chrome 148

getMessage()

browser.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 und höher browser.* seit Chrome 148
  • 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()

browser.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.