chrome.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 "default_locale" im Manifest definiert sein.

Konzepte und Verwendung

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

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

Mehrere Sprachen unterstützen

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

Wenn Sie diese Erweiterung internationalisieren möchten, benennen Sie jeden für Nutzer sichtbaren String und fügen Sie ihn in eine Messages-Datei ein. Im Manifest, in den CSS-Dateien und im JavaScript-Code der Erweiterung wird der Name jedes Strings verwendet, 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 eine nicht unterstützte Sprache verwenden, wird sie von Google Chrome ignoriert.

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

  __MSG_messagename__
  

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

  chrome.i18n.getMessage("messagename")
  

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

• Einige Meldungen wie @@bidi_dir und @@ui_locale werden vom System zur Internationalisierung bereitgestellt. Eine vollständige Liste der vordefinierten Nachrichtennamen finden Sie im Abschnitt Vordefinierte Nachrichten.

• In messages.json hat jeder für den 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 „description“ ist eine Hilfe für Übersetzer, 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: länderspezifische Nachrichten.

Sobald eine Erweiterung internationalisiert ist, ist die Übersetzung unkompliziert. Sie kopieren messages.json, übersetzen es und fügen die Kopie in ein neues Verzeichnis unter /_locales ein. Wenn Sie beispielsweise Spanisch unterstützen möchten, fügen Sie 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 System zur Internationalisierung bietet einige vordefinierte Meldungen, die Ihnen bei der Lokalisierung helfen. 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. Die Namen der letzteren Nachrichten ähneln denen von Konstanten in der Gadgets BIDI (bidirektional) 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 Meldung 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. Mit diesem String können Sie URLs für Ressourcen in der Erweiterung erstellen. Diese Meldung kann auch für nicht lokalisierte Erweiterungen verwendet werden. Hinweis:Sie können diese Meldung nicht in einer Manifestdatei verwenden.
@@ui_locale	Die aktuelle Sprache. Mit diesem String können Sie länderspezifische URLs erstellen.
@@bidi_dir	Die Textrichtung für die aktuelle Sprache: „ltr“ für linksläufige Sprachen wie Deutsch oder „rtl“ für rechtsläufige Sprachen wie Arabisch.
@@bidi_reversed_dir	Wenn @@bidi_dir „ltr“ ist, ist dies „rtl“; andernfalls ist dies „ltr“.
@@bidi_start_edge	Wenn @@bidi_dir „ltr“ ist, ist dies „links“. Andernfalls ist es „rechts“.
@@bidi_end_edge	Wenn @@bidi_dir „ltr“ ist, ist dies „rechts“. Andernfalls ist es „links“.

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, wird die fett formatierte Zeile im vorherigen Code-Snippet so:

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

Bei linksläufigen Sprachen wie Deutsch werden die fetten Linien so:

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

Sprachen

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

Sie können Ihre Erweiterung in jede Sprache lokalisieren, die vom Chrome Web Store unterstützt wird. Wenn Ihre Sprache hier nicht aufgeführt ist, wählen Sie die am besten passende Alternative aus. Wenn die Standard-Region Ihrer Erweiterung beispielsweise "de_CH" ist, wählen Sie im Chrome Web Store "de" aus.

Gebietscode	Sprache (Region)
ar	Arabisch
am	Amharisch
bg	Bulgarisch
bn	Bengalisch
ca	Katalanisch
cs	Tschechisch
da	Dänisch
de	Deutsch
el	Griechisch
de	Englisch
en_AU	Englisch (Australien)
en_GB	Englisch (Vereinigtes Königreich)
de_DE	Englisch (USA)
es	Spanisch
es_419	Spanisch (Lateinamerika und Karibik)
et	Estnisch
fa	Persisch
fi	Finnisch
fil	Philippinisch
fr	Französisch
gu	Gujarati
er	Hebräisch
hi	Hindi
Std.	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
Nein	Norwegisch
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 messages.json-Datei der Standard-Lokalisierung einen Wert für jeden String enthält, wird Ihre Erweiterung oder App ausgeführt, unabhängig davon, wie spärlich die Übersetzung ist. So sucht das Erweiterungssystem nach einer Mitteilung:

1. Suchen Sie in der Nachrichtendatei (falls vorhanden) nach der bevorzugten Sprache des Nutzers. Wenn die Sprache von Google Chrome beispielsweise auf Englisch (Vereinigtes Königreich) (en_GB) festgelegt ist, sucht das System zuerst in /_locales/en_GB/messages.json nach der Meldung. Wenn diese Datei vorhanden ist und die Meldung enthält, sucht das System nicht weiter.
2. Wenn die bevorzugte Sprache des Nutzers eine Region hat (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 Meldung enthält, sucht das System nicht weiter.
3. Suchen Sie in der Nachrichtendatei nach der Standard-LCID. Wenn beispielsweise „default_locale“ der Erweiterung auf „de“ festgelegt ist und weder /_locales/en_GB/messages.json noch /_locales/en/messages.json die Nachricht enthält, verwendet die Erweiterung die Nachricht von /_locales/es/messages.json.

In der folgenden Abbildung ist die Nachricht „colores“ in allen drei Sprachen verfügbar, die von der Erweiterung unterstützt werden, „extName“ jedoch nur in zwei. Wenn ein Nutzer, der Google Chrome auf Englisch (USA) verwendet, das Label „Farben“ sieht, wird einem Nutzer, der Britisches Englisch verwendet, „Farben“ angezeigt. Sowohl Nutzer der US-amerikanischen als auch der britischen Variante der englischen Sprache sehen den Namen der Erweiterung „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“.

Sprache des Browsers festlegen

Wenn Sie Übersetzungen testen möchten, sollten Sie die Sprache Ihres Browsers festlegen. In diesem Abschnitt erfahren Sie, wie Sie die Sprache unter Windows, macOS, Linux und ChromeOS festlegen.

Windows

Sie können das Gebietsschema entweder über eine länderspezifische Tastenkombination oder über die Google Chrome-Benutzeroberfläche ändern. Die Verknüpfung ist schneller, sobald Sie sie eingerichtet haben, und Sie können mehrere Sprachen gleichzeitig verwenden.

Länderspezifische Tastenkombination verwenden

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

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

3. Ändern Sie die Eigenschaften des Shortcuts 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 einen Verknüpfungsnamen chrome-es mit dem Ziel erstellen möchten, Google Chrome auf Spanisch (es) zu starten, können Sie Folgendes eingeben:

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

Sie können beliebig viele Tastenkürzel erstellen, um sie in mehreren Sprachen zu testen. 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 Sie die Erweiterung mehrmals installieren müssen, da die Daten der Sprachen nicht geteilt werden. 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 Sprache in Google Chrome für Windows über die Benutzeroberfläche:

1. App-Symbol > Optionen
2. Wählen Sie den Tab Technische Details aus.
3. Scrollen Sie zu Webcontent.
4. Klicken Sie auf Schriftart- und Spracheinstellungen ändern.
5. Wählen Sie den Tab Sprachen aus.
6. Wählen Sie im Drop-down-Menü die Google Chrome-Sprache aus.
7. Chrome neu starten

Mac OS

Um das Gebietsschema auf einem Mac zu ändern, verwenden Sie die Systemeinstellungen.

1. Wählen Sie im Apple-Menü die Option Systemeinstellungen aus.
2. Wählen Sie im Bereich Persönlich 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 Sprache in ChromeOS:

1. Wählen Sie im Info-Bereich 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 auf das Dreipunkt-Menü Weitere Aktionen neben der Sprache und wählen Sie ChromeOS in dieser Sprache anzeigen aus.
5. Klicken Sie auf die Schaltfläche Neu starten neben der festgelegten Sprache, 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 Informationen zum Aufrufen des Quellcodes finden Sie unter Beispiele.

getMessage()

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

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 Sprachenspezifische Nachrichten. Weitere Informationen zum Aufrufen von getMessage() findest du in der API-Referenz.

getAcceptLanguages()

Im folgenden Code werden die Akzeptanzsprachen aus dem Browser abgerufen und als String angezeigt, wobei jede Akzeptanzsprache durch ein Komma getrennt wird.

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

Weitere Informationen zum Aufrufen von getAcceptLanguages() findest du in der API-Referenz.

detectLanguage()

Der folgende Code erkennt bis zu drei Sprachen aus dem angegebenen String und gibt das Ergebnis als Strings aus, 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) findest du in der API-Referenz.

Typen

LanguageCode

Chrome 47 und 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 Texts für CLD unbekannt ist.

Typ

String

Methoden

detectLanguage()

Promise Chrome 47 und höher

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

Erkennt die Sprache des bereitgestellten Texts mithilfe von CLD.

Parameter

• Text

  String

  Zu übersetzender String der Nutzereingabe.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (result: object) => void

  • Ergebnis

    Objekt

    „LanguageDetectionResult“-Objekt mit der Zuverlässigkeit der erkannten Sprache und einem Array von „DetectedLanguage“

    • isReliable

      boolean

      Zuverlässigkeit der von der CLD erkannten Sprache

    • Sprachen

      object[]

      Array von „detectedLanguage“

      • Sprache

        String

      • Prozentsatz

        Zahl

        Der Prozentsatz der erkannten Sprache

Ausgabe

• Promise<object>

  Chrome 99 und höher

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getAcceptLanguages()

Promise

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

Ruft die vom Browser akzeptierten Sprachen ab. Diese Sprache 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 und höher

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getMessage()

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

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. messageName kein String ist oder das substitutions-Array mehr als 9 Elemente hat, gibt diese Methode undefined zurück.

Parameter

• messageName

  String

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

• Substitutionen

  beliebig optional

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

• Optionen

  object optional

  Chrome 79 und höher
  • escapeLt

    boolescher Wert optional

    Escape < in der Übersetzung zu < Das 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 dem Closure Compiler verwendet werden, generieren dies automatisch.

Ausgabe

• String

  Für die aktuelle Sprache lokalisierte Nachricht.

getUILanguage()

chrome.i18n.getUILanguage()

Die Sprache der Browser-Benutzeroberfläche. Dies unterscheidet sich von i18n.getAcceptLanguages, mit dem die bevorzugten Sprachen der Nutzer zurückgegeben werden.

Ausgabe

• String

  Der Sprachcode der Browseroberfläche, z. B. en-US oder fr-FR.