Beschreibung
Du kannst die chrome.i18n
-Infrastruktur nutzen, um die Internationalisierung für deine gesamte App oder Erweiterung zu implementieren.
Sie müssen alle für Nutzer sichtbaren Strings in einer 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 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:
Um diese Erweiterung zu internationalisieren, benennen Sie jeden für den Nutzer sichtbaren String und fügen ihn in eine Nachrichtendatei ein. Im Manifest, in den CSS-Dateien und im JavaScript-Code der Erweiterung wird der Name der einzelnen Strings verwendet, um die lokalisierte Version zu erhalten.
So sieht die Erweiterung aus, wenn sie internationalisiert ist (beachten Sie, dass sie weiterhin nur englische Strings enthält):
<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="In der Datei „manifest.json“ ist „ and="" been="" changed="" chrome.i18n.getmessage("extname").="" has="" en="" file="" file="
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.
Verweisen Sie in
manifest.json
- und CSS-Dateien 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:
chrome.i18n.getMessage("messagename")
Bei jedem Aufruf von
getMessage()
können Sie bis zu 9 Strings für die Nachricht angeben. Weitere Informationen finden Sie unter Beispiele: getMessage.Einige Nachrichten wie
@@bidi_dir
und@@ui_locale
werden vom Internationalisierungssystem bereitgestellt. Im Abschnitt Vordefinierte Nachrichten finden Sie eine vollständige Liste vordefinierter Nachrichtennamen.In
messages.json
hat jeder für den Nutzer sichtbare String einen Namen, ein Nachrichtenelement und ein optionales Element „Beschreibung“. Der Name ist ein Schlüssel wie „extName“ oder „Suchstring“, der den String identifiziert. „message“ gibt den Wert des Strings in dieser Sprache an. Die optionale "Beschreibung" ist eine Hilfe für Übersetzer, die möglicherweise nicht sehen können, wie die Zeichenfolge in der 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.
Sobald eine Erweiterung oder App internationalisiert ist, lässt sich das leicht übersetzen. Sie kopieren messages.json
, übersetzen sie und legen die Kopie in einem neuen Verzeichnis unter _locales
ab. Wenn beispielsweise Spanisch unterstützt werden soll, fügen Sie einfach eine übersetzte Kopie von messages.json
unter _locales/es
hinzu. Die folgende Abbildung zeigt die vorherige Erweiterung mit einer neuen spanischen Übersetzung.
Vordefinierte Nachrichten
Das Internationalisierungssystem stellt einige vordefinierte Nachrichten bereit, die dir bei der Lokalisierung helfen. Dazu gehören @@ui_locale
, damit Sie die aktuelle UI-Sprache erkennen können, und einige @@bidi_...
-Meldungen, mit denen Sie die Textrichtung erkennen können. Die letzteren Meldungen haben ähnliche Namen wie Konstanten in der gadgets bidI (bi-direktional) API.
Die Sondernachricht @@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 Mitteilungen beschrieben.
Name der Nachricht | Beschreibung |
---|---|
@@extension_id | Die Erweiterung oder App-ID. Mit diesem String können Sie URLs für Ressourcen innerhalb der Erweiterung erstellen. Auch nicht lokalisierte Erweiterungen können diese Nachricht verwenden. Hinweis:Sie können diese Nachricht nicht in einer Manifestdatei verwenden. |
@@ui_locale | Das aktuelle Gebietsschema. Mit diesem String können Sie länderspezifische URLs erstellen. |
@@bidi_dir | Die Textrichtung für die aktuelle Sprache, also entweder "ltr" für rechtsläufige Sprachen wie Englisch 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“ (links), andernfalls „right“. |
@@bidi_end_edge | Wenn @@bidi_dir „ltr“ ist, ist dies „right“, andernfalls „left“. |
Hier sehen Sie 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, ändert sich die fett formatierte Zeile im vorherigen Code-Snippet zu:
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 Englisch werden die fett gedruckten Linien wie folgt geändert:
dir: ltr;
padding-left: 0;
padding-right: 1.5em;
Sprachen
Sie können aus vielen Sprachen auswählen, darunter einige (z. B. en
), die es einer einzelnen Übersetzung ermöglichen, mehrere Varianten einer Sprache (z. B. en_GB
und en_US
) zu unterstützen.
Unterstützte Gebietsschemen
Sie können jede vom Chrome Web Store unterstützte Sprache verwenden.
Suchen von Nachrichten
Sie müssen nicht jeden String für jedes unterstützte Gebietsschema 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 dünn eine Übersetzung ist. So sucht das Erweiterungssystem nach einer Nachricht:
- Suchen Sie in der Nachrichtendatei (falls vorhanden) nach der bevorzugten Sprache des Nutzers. Wenn als Sprache von Google Chrome beispielsweise britisches Englisch (
en_GB
) eingestellt ist, sucht das System zuerst in_locales/en_GB/messages.json
nach der Nachricht. Wenn diese Datei und die Meldung vorhanden sind, sucht das System nicht weiter. - Wenn die bevorzugte Sprache des Nutzers eine Region hat (d. h., das Gebietsschema hat einen Unterstrich: _), suchen Sie nach der Sprache ohne diese Region. Wenn beispielsweise die Nachrichtendatei
en_GB
nicht vorhanden oder nicht enthalten ist, sucht das System in der Nachrichtendateien
. Ist diese Datei und die Meldung vorhanden, sucht das System nicht weiter. - Suchen Sie in der Nachrichtendatei nach dem Standardgebietsschema. Wenn beispielsweise „default_locale“ der Erweiterung auf „es“ gesetzt 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 erscheint die Meldung mit dem Namen „colores“ in allen drei von der Erweiterung unterstützten Sprachen, „extName“ jedoch nur in zwei der Sprachen. Wenn ein Nutzer, der Google Chrome in US-Englisch ausführt, das Label "Colors" sieht, wird einem Nutzer mit britischem Englisch das Label "Colours" (Farben) angezeigt. Nutzern in amerikanischem und britischem Englisch 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 Erweiterungsnamen „Hola mundo“.
Sprache deines Browsers einstellen
Zum Testen von Übersetzungen sollten Sie die Sprache Ihres Browsers festlegen. In diesem Abschnitt erfahren Sie, wie Sie die Sprache unter Windows, Mac OS X, Linux und ChromeOS festlegen.
Windows
Sie können das Gebietsschema entweder über eine länderspezifische Verknüpfung oder über die Google Chrome-Benutzeroberfläche ändern. Die Abkürzung geht nach der Einrichtung schneller und Sie können mehrere Sprachen gleichzeitig verwenden.
Länderspezifische Tastenkombination verwenden
So erstellen und verwenden Sie eine Verknüpfung, mit der Google Chrome mit einer bestimmten Sprache gestartet wird:
- Erstellen Sie eine Kopie der Google Chrome-Verknüpfung, die sich bereits auf Ihrem Desktop befindet.
- Benennen Sie die neue Tastenkombination in die neue Sprache um.
Ä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
Doppelklicken Sie auf die Verknüpfung, um Google Chrome zu starten.
Um beispielsweise eine Verknüpfung zu erstellen, mit der Google Chrome auf Spanisch (es
) gestartet wird, können Sie eine Verknüpfung namens chrome-es
mit dem folgenden Ziel erstellen:
path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es
Sie können beliebig viele Tastenkombinationen erstellen und Tests in mehreren Sprachen durchfü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
Benutzeroberfläche verwenden
So ändern Sie das Gebietsschema über die Benutzeroberfläche von Google Chrome für Windows:
- App-Symbol > Optionen
- Wählen Sie den Tab Details aus.
- Scrollen Sie nach unten zu Webinhalte.
- Klicken Sie auf Schriftart- und Spracheinstellungen ändern.
- Wählen Sie den Tab Sprachen aus.
- Wählen Sie im Drop-down-Menü die Google Chrome-Sprache aus.
- Chrome neu starten
Mac OS X
Das Gebietsschema lässt sich auf dem Mac über die Systemeinstellungen ändern.
- Wähle im Apple-Menü Systemeinstellungen aus.
- Wählen Sie im Abschnitt Persönlich die Option International aus.
- Sprache und Standort auswählen
- Chrome neu starten
Linux
Um das Gebietsschema unter Linux zu ändern, beenden Sie zuerst Google Chrome. Legen Sie in einer Zeile die Umgebungsvariable LANGUAGE fest und starten Sie Google Chrome. Beispiel:
LANGUAGE=es ./chrome
ChromeOS
So ändern Sie die Sprache unter ChromeOS:
- Wählen Sie in der Taskleiste Einstellungen aus.
- Wählen Sie im Abschnitt Sprachen und Eingabe das Drop-down-Menü Sprache aus.
- Wenn Ihre Sprache nicht aufgeführt ist, klicken Sie auf Sprachen hinzufügen und fügen Sie sie hinzu.
- Klicken Sie nach dem Hinzufügen auf das Dreipunkt-Menü neben der Sprache Weitere Aktionen und wählen Sie ChromeOS in dieser Sprache anzeigen aus.
- 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 findest du unter examples/extensions/news. Weitere Beispiele und Hilfe zum Aufrufen des Quellcodes finden Sie unter Beispiele.
Beispiele: getMessage
Mit dem 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 Länderspezifische Nachrichten. Weitere Informationen zum Aufrufen von getMessage()
finden Sie in der API-Referenz.
Beispiel: getAcceptLanguage
Mit dem folgenden Code werden „Accept-Sprachen“ aus dem Browser abgerufen und als String angezeigt. Dazu werden die entsprechenden Sprachen durch ein „,“ 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.
Beispiel: detectLanguage
Mit dem folgenden Code werden bis zu drei Sprachen aus dem angegebenen String erkannt und das Ergebnis als durch Zeilenumbrüche getrennte Strings angezeigt.
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
Ein ISO-Sprachcode wie en
oder fr
. Eine vollständige Liste der von dieser Methode unterstützten Sprachen finden Sie unter kLanguageInfoTable. Für eine unbekannte Sprache wird und
zurückgegeben. Das bedeutet, dass [percentage] des Textes der CLD nicht bekannt ist.
Typ
String
Methoden
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
Erkennt die Sprache des bereitgestellten Textes mithilfe von CLD.
Parameters
-
Text
String
Der Nutzereingabestring, der übersetzt werden soll.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: object) => void
-
Ergebnis
Objekt
LanguageDetectionResult-Objekt, das die erkannte Sprachzuverlässigkeit und das Array von DetectedLanguage enthält
-
isReliable
boolean
CLD erkannte Sprachzuverlässigkeit
-
Sprachen
Objekt[]
Array von DetectionLanguage
-
language
String
-
Prozentsatz
Zahl
Prozentsatz der erkannten Sprache
-
-
-
Rückgaben
-
Promise<object>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
Ruft die Accept-Sprachen des Browsers ab. Diese Sprache unterscheidet sich von der vom Browser verwendeten Sprache. Verwenden Sie i18n.getUILanguage
, um sie abzurufen.
Parameters
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(languages: string[]) => void
-
Sprachen
String[]
Array mit LanguageCode
-
Rückgaben
-
Promise<LanguageCode[]>
Chrome 99 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
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 – beispielsweise, wenn messageName kein String ist oder das Substitutions-Array mehr als 9 Elemente enthält, gibt diese Methode undefined
zurück.
Parameters
-
messageName
String
Der Name der Nachricht, wie in der Datei
messages.json
angegeben. -
Substitutionen
Beliebig optional
Bis zu 9 Substitutionsstrings, falls für die Nachricht welche erforderlich sind.
-
Optionen
Objekt optional
Chrome 79 und höher-
escapeLt
Boolescher Wert optional
Für die Übersetzung in die Sprache
<
die Esc-Taste „<
“ drücken. 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ückgaben
-
String
Für die aktuelle Sprache lokalisierte Nachricht.
getUILanguage()
chrome.i18n.getUILanguage()
Ruft die Browsersprache des Browsers ab. Dies unterscheidet sich von i18n.getAcceptLanguages
, bei dem die bevorzugten Nutzersprachen zurückgegeben werden.
Rückgaben
-
String
Der Sprachcode der Browser-Benutzeroberfläche, z. B. en-US oder fr-FR.