Internationalisierung

Eine internationalisierte Erweiterung kann dieselben Funktionen wie jede andere Erweiterung enthalten — Hintergrundskripte, Inhaltsskripte usw. — jedoch enthält sie auch einige zusätzliche Teile, die es ihr ermöglichen, zwischen verschiedenen Gebietsschemas zu wechseln. Diese sind im folgenden Verzeichnisbaum zusammengefasst:

• extension-root-directory/

  • _locales

    • en

      • messages.json

        • Englische Nachrichten (Strings)

    • de

      • messages.json

        • Deutsche Nachrichten (Strings)

    • usw.

  • manifest.json

    • gebietsschemaspezifische Metadaten

  • myJavascript.js

    • JavaScript zum Abrufen des Browser-Gebietsschemas, gebietsschemaspezifische Nachrichten usw.

  • myStyles.css

    • gebietsschemaspezifisches CSS

Lassen Sie uns jede der neuen Funktionen der Reihe nach erkunden — jeder der folgenden Abschnitte beschreibt einen Schritt, dem Sie folgen sollten, wenn Sie Ihre Erweiterung internationalisieren.

Jedes i18n-System erfordert die Bereitstellung von Strings, die in alle verschiedenen Gebietsschemas übersetzt wurden, die Sie unterstützen möchten. In Erweiterungen sind diese in einem Verzeichnis namens _locales enthalten, das in das Erweiterungsstammverzeichnis eingefügt wird. Jedes einzelne Gebietsschema hat seine Strings (als Nachrichten bezeichnet) in einer Datei namens messages.json enthalten, die in einem Unterverzeichnis von _locales platziert ist, benannt unter Verwendung des Sprachuntertags für die Sprache dieses Gebietsschemas.

Beachten Sie, dass, wenn der Untertag eine grundlegende Sprache plus eine regionale Variante umfasst, die Sprache und die Variante konventionell durch einen Bindestrich getrennt werden: zum Beispiel "en-US". In den Verzeichnissen unter _locales muss der Trennstrich jedoch ein Unterstrich sein: "en_US".

So haben wir zum Beispiel in unserer Beispiel-App Verzeichnisse für "en" (Englisch), "de" (Deutsch), "nl" (Niederländisch) und "ja" (Japanisch). Jedes dieser Verzeichnisse hat eine messages.json-Datei darin.

Schauen wir uns nun die Struktur einer dieser Dateien an (_locales/en/messages.json):

{
  "extensionName": {
    "message": "Notify link clicks i18n",
    "description": "Name of the extension."
  },

  "extensionDescription": {
    "message": "Shows a notification when the user clicks on links.",
    "description": "Description of the extension."
  },

  "notificationTitle": {
    "message": "Click notification",
    "description": "Title of the click notification."
  },

  "notificationContent": {
    "message": "You clicked $URL$.",
    "description": "Tells the user which link they clicked.",
    "placeholders": {
      "url": {
        "content": "$1",
        "example": "https://developer.mozilla.org"
      }
    }
  }
}

Diese Datei ist Standard-JSON — jedes ihrer Mitglieder ist ein Objekt mit einem Namen, das eine message und eine description enthält. Alle diese Elemente sind Strings; $URL$ ist ein Platzhalter, der durch ein Unterzeichenfolgen ersetzt wird, wenn das notificationContent-Mitglied von der Erweiterung aufgerufen wird. Sie lernen, wie man dies im Abschnitt Nachrichten-Strings aus JavaScript abrufen macht.

Es gibt einige verschiedene Aufgaben zu erledigen, um Ihre manifest.json zu internationalisieren.

Ihr manifest.json enthält Strings, die dem Benutzer angezeigt werden, wie der Name und die Beschreibung der Erweiterung. Wenn Sie diese Strings internationalisieren und die entsprechenden Übersetzungen davon in messages.json einfügen, wird die korrekte Übersetzung des Strings basierend auf dem aktuellen Gebietsschema dem Benutzer angezeigt.

Um Strings zu internationalisieren, geben Sie sie wie folgt an:

"name": "__MSG_extensionName__",
"description": "__MSG_extensionDescription__",

Hier rufen wir Nachrichten-Strings abhängig vom Gebietsschema des Browsers ab, anstatt statische Strings einzuschließen.

Um einen Nachrichten-String so aufzurufen, müssen Sie ihn wie folgt angeben:

1. Zwei Unterstriche, gefolgt von
2. Dem String "MSG", gefolgt von
3. Einem Unterstrich, gefolgt von
4. Dem Namen der Nachricht, die Sie aufrufen möchten, wie in messages.json definiert, gefolgt von
5. Zwei Unterstrichen

__MSG_ + messageName + __

Ein weiteres Feld, das Sie in Ihrer manifest.json angeben sollten, ist default_locale:

"default_locale": "en"

Dies gibt ein Standardgebietsschema an, das verwendet wird, wenn die Erweiterung keinen lokalisierten String für das aktuelle Gebietsschema des Browsers enthält. Alle Nachrichten-Strings, die im Browser-Gebietsschema nicht verfügbar sind, werden stattdessen aus dem Standard-Gebietsschema übernommen. Es gibt noch mehr Details, die zu beachten sind, wie der Browser Strings auswählt — siehe Lokalisierte String-Auswahl.

Beachten Sie, dass Sie auch lokalisierte Strings aus CSS-Dateien in der Erweiterung abrufen können. Zum Beispiel könnten Sie eine gebietsschemaspezifische CSS-Regel konstruieren wollen, wie diese:

header {
  background-image: url(../images/__MSG_extensionName__/header.png);
}

Dies ist nützlich, obwohl Sie eine solche Situation möglicherweise besser mit vordefinierten Nachrichten handhaben könnten.

Sie haben Ihre Nachrichten-Strings eingerichtet und Ihr Manifest. Jetzt müssen Sie nur noch beginnen, Ihre Nachrichten-Strings aus JavaScript aufzurufen, damit Ihre Erweiterung so gut wie möglich die richtige Sprache spricht. Die eigentliche i18n-API ist ziemlich einfach und enthält nur vier Hauptmethoden:

• Sie werden wahrscheinlich am häufigsten i18n.getMessage() verwenden — dies ist die Methode, die Sie verwenden, um einen spezifischen Sprachstring abzurufen, wie oben erwähnt. Wir werden unten spezifische Nutzungsbeispiele dafür sehen.
• Die Methoden i18n.getAcceptLanguages() und i18n.getUILanguage() könnten verwendet werden, wenn Sie die Benutzeroberfläche je nach Gebietsschema anpassen müssten — vielleicht möchten Sie Präferenzen anzeigen, die für die bevorzugten Sprachen der Benutzer spezifisch sind, höher in einer Präferenzliste, kulturelle Informationen anzeigen, die nur für eine bestimmte Sprache relevant sind, oder angezeigte Daten gemäß dem Browser-Gebietsschema entsprechend formatieren.
• Die Methode i18n.detectLanguage() könnte verwendet werden, um die Sprache von benutzereingereichten Inhalten zu erkennen und entsprechend zu formatieren.

In unserem notify-link-clicks-i18n-Beispiel enthält das Hintergrundskript die folgenden Zeilen:

let title = browser.i18n.getMessage("notificationTitle");
let content = browser.i18n.getMessage("notificationContent", message.url);

Die erste Zeile ruft einfach das notificationTitle message-Feld aus der verfügbaren messages.json-Datei ab, die am besten zum aktuellen Gebietsschema des Browsers passt. Die zweite Zeile ist ähnlich, aber sie wird mit einer URL als zweitem Parameter aufgerufen. Was hat das zu bedeuten? So geben Sie den Inhalt an, der den $URL$-Platzhalter ersetzt, den wir im notificationContent message-Feld sehen:

"notificationContent": {
  "message": "You clicked $URL$.",
  "description": "Tells the user which link they clicked.",
  "placeholders": {
    "url" : {
      "content" : "$1",
      "example" : "https://developer.mozilla.org"
    }
  }
}

Das "placeholders"-Element definiert alle Platzhalter und wo sie abgerufen werden. Der "url"-Platzhalter gibt an, dass sein Inhalt von $1 stammt, was der erste Wert ist, der im zweiten Parameter von getMessage() angegeben ist. Da der Platzhalter "url" genannt wird, verwenden wir $URL$, um ihn im eigentlichen Nachrichten-String aufzurufen (also für "name" würden Sie $NAME$ verwenden, usw.). Wenn Sie mehrere Platzhalter haben, können Sie sie in einem Array bereitstellen, das i18n.getMessage() als der zweite Parameter übergeben wird — [a, b, c] wird in messages.json als $1, $2 und $3 verfügbar sein, und so weiter.

Lassen Sie uns ein Beispiel durchgehen: Der ursprüngliche notificationContent-Nachrichten-String in der en/messages.json-Datei ist

You clicked $URL$.

Angenommen, der angeklickte Link zeigt auf https://developer.mozilla.org. Nach dem i18n.getMessage()-Aufruf werden die Inhalte des zweiten Parameters in messages.json als $1 verfügbar gemacht, was den $URL$-Platzhalter ersetzt, wie im "url"-Platzhalter definiert. Der endgültige Nachrichten-String ist also

You clicked https://developer.mozilla.org.

Es ist möglich, Ihre Variablen ($1, $2, $3, usw.) direkt in die Nachrichten-Strings einzufügen, zum Beispiel könnten wir das oben genannte "notificationContent"-Mitglied wie folgt umschreiben:

"notificationContent": {
  "message": "You clicked $1.",
  "description": "Tells the user which link they clicked."
}

Dies mag schneller und weniger komplex erscheinen, aber die andere Methode (Verwendung von "placeholders") wird als beste Praxis angesehen. Der Grund dafür ist, dass der Platzhaltername (z.B. "url") und das Beispiel Ihnen helfen, sich zu merken, wofür der Platzhalter gedacht ist — eine Woche, nachdem Sie Ihren Code geschrieben haben, werden Sie wahrscheinlich vergessen haben, wofür $1 – $8 stehen, aber Sie werden sich eher daran erinnern, wofür Ihre Platzhalternamen stehen.

Es ist auch möglich, hardcodierte Strings in Platzhaltern einzufügen, sodass jedes Mal derselbe Wert verwendet wird, anstatt ihn aus einer Variablen in Ihrem Code zu beziehen. Zum Beispiel:

"mdn_banner": {
  "message": "For more information on web technologies, go to $MDN$.",
  "description": "Tell the user about MDN",
  "placeholders": {
    "mdn": {
      "content": "https://developer.mozilla.org/"
    }
  }
}

In diesem Fall hardcoden wir einfach den Platzhalterinhalt, anstatt ihn aus einem Variablenwert wie $1 zu beziehen. Dies kann manchmal nützlich sein, wenn Ihre Nachrichten-Datei sehr komplex ist und Sie verschiedene Werte aufteilen möchten, um die Strings in der Datei lesbarer zu machen, zudem könnten diese Werte dann programmatisch abgerufen werden.

Darüber hinaus können Sie solche Substitutionen verwenden, um Teile des Strings anzugeben, die nicht übersetzt werden sollen, wie Personen- oder Firmennamen.

Gebietsschemas können nur mit einem Sprachcode angegeben werden, wie fr oder en, oder sie können weiter mit einem Regionscode, wie en_US oder en_GB, qualifiziert werden, der eine regionale Variante der gleichen Grundsprache beschreibt. Wenn Sie das i18n-System nach einem String fragen, wird es einen String anhand des folgenden Algorithmus auswählen:

1. Wenn es eine messages.json-Datei für das exakte aktuelle Gebietsschema gibt und sie den String enthält, geben Sie ihn zurück.
2. Andernfalls, wenn das aktuelle Gebietsschema mit einer Region qualifiziert ist (z.B. en_US) und es eine messages.json-Datei für die regionslose Version dieses Gebietsschemas (z.B. en) gibt und diese Datei den String enthält, geben Sie ihn zurück.
3. Andernfalls, wenn es eine messages.json-Datei für das in manifest.json definierte default_locale gibt und sie den String enthält, geben Sie ihn zurück.
4. Andernfalls geben Sie einen leeren String zurück.

Nehmen wir folgendes Beispiel an:

• extension-root-directory/

  • _locales

    • en_GB

      • messages.json

        • { "colorLocalized": { "message": "colour", "description": "Color." }, /* … */ }

      en

      • messages.json

        • { "colorLocalized": { "message": "color", "description": "Color." }, /* … */ }

    • fr

      • messages.json

        • { "colorLocalized": { "message": "couleur", "description": "Color." }, /* … */}

Angenommen, das default_locale ist auf fr gesetzt und das aktuelle Gebietsschema des Browsers ist en_GB:

• Wenn die Erweiterung getMessage("colorLocalized") aufruft, gibt sie "colour" zurück.
• Wenn "colorLocalized" nicht in en_GB vorhanden wäre, würde getMessage("colorLocalized") "color" zurückgeben, nicht "couleur".

Das i18n-Modul bietet uns einige vordefinierte Nachrichten, die wir auf die gleiche Weise wie zuvor gesehen aufrufen können, in Lokalisierte Strings in Manifesten abrufen und Gebietsschemaspezifisches CSS. Zum Beispiel:

__MSG_extensionName__

Vordefinierte Nachrichten verwenden genau dieselbe Syntax, außer dass @@ vor dem Nachrichtennamen steht, zum Beispiel

__MSG_@@ui_locale__

Die folgende Tabelle zeigt die verschiedenen verfügbaren vordefinierten Nachrichten:

Zurück zu unserem früheren Beispiel: Es würde mehr Sinn machen, es so zu schreiben:

header {
  background-image: url(../images/__MSG_@@ui_locale__/header.png);
}

Nun können wir unsere lokalen spezifischen Bilder einfach in Verzeichnissen speichern, die den verschiedenen unterstützten Gebietsschemas entsprechen — en, de, etc. — was viel sinnvoller ist.

Schauen wir uns ein Beispiel für die Verwendung von @@bidi_* Nachrichten in einer CSS-Datei an:

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 von links nach rechts lesbare Sprachen wie Englisch würden die CSS-Deklarationen mit den vordefinierten Nachrichten oben folgendermaßen in den endgültigen Codezeilen übersetzt werden:

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

Für eine von rechts nach links lesbare Sprache wie Arabisch erhalten Sie:

direction: rtl;
padding-right: 0;
padding-left: 1.5em;

Um die Lokalisierung Ihrer Erweiterung zu testen, verwenden Sie Firefox oder Firefox Beta, die Firefox-Builds, in denen Sie Sprachpakete installieren können.

Dann folgen Sie für jede in der Erweiterung unterstützte Sprache, die Sie testen möchten, den Anweisungen, um Firefox in einer anderen Sprache verwenden, um die Sprache der Firefox-Benutzeroberfläche zu wechseln. (Wenn Sie sich in den Einstellungen auskennen, verwenden Sie unter Sprache die Alternative festlegen.)

Wenn Firefox in Ihrer Testsprache läuft, installieren Sie von about:debugging aus die Erweiterung vorübergehend oder laden Sie sie erneut, wenn sie bereits installiert ist. Nachdem Sie Ihre Erweiterung installiert oder neu geladen haben, sehen Sie, wenn Sie Ihre Erweiterung korrekt eingerichtet haben, die Erweiterung mit ihrem Symbol, ihrem Namen und ihrer Beschreibung in der gewählten Sprache aufgelistet. Sie können auch die lokalisierten Erweiterungsdetails in about:addons sehen. Jetzt sollten Sie die Funktionen der Erweiterung nutzen, um sicherzustellen, dass die Übersetzungen vorhanden sind.

Wenn Sie diesen Prozess ausprobieren möchten, können Sie die notify-link-clicks-i18n-Erweiterung verwenden. Richten Sie Firefox so ein, dass eine der in diesem Beispiel unterstützten Sprachen (Deutsch, Niederländisch oder Japanisch) angezeigt wird. Laden Sie die Erweiterung und gehen Sie auf eine Website. Klicken Sie auf einen Link, um die übersetzte Version der Benachrichtigung zu sehen, die die URL des Links meldet.