chrome.i18n

Beschreibung

Verwenden Sie die chrome.i18n-Infrastruktur, um die Internationalisierung für Ihre gesamte App oder Erweiterung zu implementieren.

Manifest

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

Konzepte und Verwendung

Sie müssen alle für den 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 Nachrichtendatei in einem Verzeichnis namens /_locales/_localeCode_ hinzu, wobei localeCode ein Code wie en für Englisch ist.

Hier sehen Sie 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:

Zum Internationalisieren dieser Erweiterung benennen Sie jeden für den 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 der einzelnen Strings, um die lokalisierte Version zu ermitteln.

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="" _locates="" a="" alt="In der Datei "manifest.json" " and="" be="" geändert="" chrome.i18n.getmessage("extname").="" /

Hinweise zur Internationalisierung:

• Sie können jedes unterstützte Gebietsschema verwenden. Wenn Sie eine nicht unterstützte Sprache verwenden, wird diese von Google Chrome ignoriert.

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

  __MSG_messagename__
  

• Verweisen Sie im JavaScript-Code Ihrer Erweiterung oder App auf einen String mit dem Namen messagename, der so aussieht:

  chrome.i18n.getMessage("messagename")
  

• In 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 wie @@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 den Nutzer sichtbare String einen Namen, ein Element „Nachricht“ und ein optionales Element „Beschreibung“. 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 „description“ ist eine hilfreiche Funktion 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: Sprachspezifische Nachrichten.

Nachdem eine Erweiterung internationalisiert wurde, lässt sie sich ganz einfach übersetzen. Sie kopieren messages.json, übersetzen den Inhalt und legen die Kopie in einem neuen Verzeichnis unter /_locates ab. Wenn Sie zum Beispiel Spanisch unterstützen möchten, setzen Sie einfach eine übersetzte Kopie von messages.json unter /_locates/es. Die folgende Abbildung zeigt die vorherige Erweiterung mit einer neuen spanischen Übersetzung.

Vordefinierte Mitteilungen

Das Internationalisierungssystem enthält einige vordefinierte Nachrichten, die Ihnen bei der Lokalisierung helfen. Dazu gehören @@ui_locale, damit Sie die aktuelle UI-Sprache erkennen können, und einige @@bidi_...-Nachrichten, mit denen Sie die Textrichtung ermitteln können. Die letzteren Meldungen haben ähnliche Namen wie die Konstanten in der BIDI-API (bidirektional).

Die spezielle Meldung @@extension_id kann in den CSS- und JavaScript-Dateien unabhängig davon verwendet werden, 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 Erweiterung oder App-ID. Sie können diesen String verwenden, um URLs für Ressourcen innerhalb der Erweiterung zu erstellen. Diese Nachricht kann auch für nicht lokalisierte Erweiterungen verwendet werden. Hinweis:Du kannst diese Nachricht nicht in einer Manifestdatei verwenden.
@@ui_locale	Die aktuelle Sprache. Mit dieser Zeichenfolge können Sie gebietsspezifische URLs 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 das „rtl“. Andernfalls ist es „ltr“.
@@bidi_start_edge	Wenn @@bidi_dir „ltr“ ist, ist dies „left“. Andernfalls ist es „right“.
@@bidi_end_edge	Wenn @@bidi_dir „ltr“ ist, ist dies „right“. Andernfalls ist es „left“.

Hier ist 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 gedruckte Zeile im vorherigen Code-Snippet so:

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

Hier ist 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 Englisch werden die fett formatierten Zeilen so dargestellt:

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

Sprachen

Sie können aus vielen Sprachen auswählen, einschließlich einiger (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 jede Sprache lokalisieren, die vom Chrome Web Store unterstützt wird. Wenn Ihr Land hier nicht aufgeführt ist, wählen Sie eine Alternative aus, die Ihnen am nächsten kommt. Wenn die Standardsprache Ihrer Erweiterung beispielsweise "de_CH" ist, wählen Sie im Chrome Web Store "de" aus.

Gebietsschemacode	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
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 Datei messages.json der Standardsprache 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 Nachricht:

1. Suchen Sie in der Nachrichtendatei (falls vorhanden) nach dem bevorzugten Gebietsschema des Nutzers. Wenn als Sprache in Google Chrome beispielsweise britisches Englisch (en_GB) festgelegt ist, sucht das System zuerst in /_locates/en_GB/messages.json nach der Nachricht. Wenn diese Datei vorhanden ist und die Nachricht vorhanden ist, sucht das System nicht weiter.
2. Wenn die bevorzugte Sprache des Nutzers eine Region enthält (d. h. einen Unterstrich: _), wird die Sprache ohne diese Region durchsucht. 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 vorhanden ist, sucht das System nicht weiter.
3. Suchen Sie in der Nachrichtendatei nach der Standardsprache. Wenn beispielsweise „default_locale“ der Erweiterung auf „es“ festgelegt ist und weder /_locates/en_GB/messages.json noch /_locates/en/messages.json die Nachricht enthält, verwendet die Erweiterung die Nachricht aus /_locates/es/messages.json.

In der folgenden Abbildung befindet sich die Nachricht mit dem Namen "colores" in allen drei von der Erweiterung unterstützten Sprachen, "extName" jedoch nur in zwei Sprachen. Wenn ein Nutzer, der Google Chrome in amerikanischem Englisch ausführt, das Label "Colors" sieht, sieht ein Nutzer von britischem Englisch das Label "Colors" (Farben). Sowohl in US-Englisch als auch in englischer Sprache wird der Erweiterungsname „Hello World“ angezeigt. Da die Standardsprache Spanisch ist, sehen Nutzer, die Google Chrome in einer anderen Sprache als Englisch ausführen, das Label "Colores" und den Namen der Erweiterung "Hola mundo".

Sprache des Browsers festlegen

Um Übersetzungen zu testen, können Sie die Sprache Ihres Browsers einstellen. In diesem Abschnitt erfahren Sie, wie Sie das Gebietsschema unter Windows, Mac OS X, Linux und ChromeOS festlegen.

Windows

Sie können die Sprache entweder über eine länderspezifische Tastenkombination oder über die Benutzeroberfläche von Google Chrome ändern. Die Schnellsuche ist nach der Einrichtung schneller und ermöglicht es Ihnen, mehrere Sprachen gleichzeitig zu verwenden.

Sprachspezifische Tastenkombination verwenden

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

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

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 durch Doppelklicken auf die Verknüpfung.

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

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

Sie können beliebig viele Tastenkombinationen erstellen und so ganz einfach in mehreren Sprachen 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 pro Sprache ein Datenverzeichnis haben, können Sie den Browser in mehreren Sprachen gleichzeitig ausführen. Ein Nachteil besteht darin, dass die Daten der Sprachen nicht gemeinsam genutzt werden. Sie müssen die Erweiterung daher 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 das Gebietsschema in Google Chrome für Windows über die Benutzeroberfläche:

1. App-Symbol > Optionen
2. Wählen Sie den Tab Details aus.
3. Scrollen Sie nach unten zu Webinhalte.
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 Sprache für Google Chrome aus.
7. Chrome neu starten

Mac OS X

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

1. Wähle im Apple-Menü Systemeinstellungen aus.
2. Wählen Sie im Abschnitt Persönlich die Option International aus.
3. Sprache und Standort auswählen
4. Chrome neu starten

Linux

Um das Gebietsschema unter Linux zu ändern, beenden Sie zuerst Google Chrome. Legen Sie dann in einer Zeile die Umgebungsvariable SPRACHE fest und starten Sie Google Chrome. Beispiel:

LANGUAGE=es ./chrome

ChromeOS

So ändern Sie die Sprache unter ChromeOS:

1. Wählen Sie in der Taskleiste Einstellungen aus.
2. Wählen Sie im Bereich 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 Ihrer 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 die Schaltfläche 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 Aufrufen des Quellcodes finden Sie unter Beispiele.

getMessage()

Mit dem folgenden Code wird eine lokalisierte Nachricht vom Browser abgerufen und als String angezeigt. Es 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 würden Sie einen einzelnen String angeben und verwenden:

  // 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 Sprachspezifische Nachrichten. Weitere Informationen zum Aufrufen von getMessage() finden Sie in der API-Referenz.

getAcceptLanguages()

Mit dem folgenden Code werden Annahmesprachen vom Browser abgerufen und als Zeichenfolge angezeigt. Dabei werden alle Accept-Sprachen durch , getrennt.

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 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) findest du 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 [percentage] des Textes CLD nicht bekannt ist.

Typ

String

Methoden

detectLanguage()

Promise Chrome 47 und höher

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

Ermittelt die Sprache des bereitgestellten Texts mithilfe von CLD.

Parameter

• Text

  String

  Zu übersetzender Nutzereingabestring.

• callback

  Funktion optional

  Der Parameter callback sieht so aus:

  (result: object) => void

  • Ergebnis

    Objekt

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

    • isReliable

      boolean

      Erkannte CLD-Sprachzuverlässigkeit

    • Sprachen

      Objekt[]

      Array von detectLanguage

      • language

        String

      • Prozentsatz

        number

        Der Prozentsatz der erkannten Sprache

Rückgabe

• Promise<object>

  Chrome 99 oder höher

  Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in demselben Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getAcceptLanguages()

Versprechen

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

Ruft die Accept-Language-Sprachen des Browsers ab. Sie unterscheidet sich von der im Browser verwendeten Sprache. Verwenden Sie zum Abrufen der Sprache i18n.getUILanguage.

Parameter

• callback

  Funktion optional

  Der Parameter callback sieht so aus:

  (languages: string[]) => void

  • Sprachen

    String[]

    Array von LanguageCode

Rückgabe

• Promise<LanguageCode[]>

  Chrome 99 oder höher

  Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in demselben Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an das Callback ü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, zum Beispiel, wenn messageName kein String ist oder das Array Replacements 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

  Beliebige optionale

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

• Optionen

  Objekt optional

  Chrome 79 oder höher
  • escapeLt

    Boolescher Wert optional

    Geben Sie die Escape-Zeichen < in die Übersetzung in die Sprache < ein. 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 dem Closure Compiler verwendet werden, generieren dies automatisch.

Rückgabe

• String

  Nachricht für die aktuelle Sprache lokalisiert.

getUILanguage()

chrome.i18n.getUILanguage()

Ruft die Browser-UI-Sprache des Browsers ab. Dies unterscheidet sich von i18n.getAcceptLanguages, bei dem die bevorzugten Nutzersprachen zurückgegeben werden.

Rückgabe

• String

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