JavaScript-Lokalisierung – der ultimative Leitfaden

✋🏽 Hinweis » polyglot.extend() wird Übersetzungsnachrichten zu den bereits geladenen hinzufügen. Daher verwenden wir polyglot.replace(), um sicherzustellen, dass wir nur die Übersetzungen der aktiven Sprache laden.

Das sollte unseren schicken Sprachumschalter zum Laufen bringen.

Interpolation

Unser Haupttext enthält den Namen des aktuell angemeldeten Users (natürlich gemockt). Diese Art von interpoliertem Wert wird von Polyglot standardmäßig mit einer speziellen %{variable} Syntax behandelt.

🗒 Hinweis » Du kannst die Zeichen, die interpolierte Werte kennzeichnen, mit der interpolation -Option, die an den Polyglot-Konstruktor übergeben wird, ändern.

<!-- ... -->
    <p data-i18n-key="lead" data-i18n-opt='{"username": "Cadence"}'>
      Welcome to my little spot on the interwebs, %{username}!
    </p>
<!-- ... -->

{
  // ...
  "lead": "Welcome to my little spot on the interwebs, %{username}!"
}

{
  // ...
  "lead": "أهلاً بك في مكاني الصغير على النت يا %{username}."
}

Ein paar Zeilen Code können zu unserer Funktion translatePage() hinzugefügt werden, um Interpolationen zu berücksichtigen.

// ...
// Übersetze alle Elemente auf der Seite, die ein
// data-i18n-key-Attribut haben
function translatePage() {
  const translatableElements = document.querySelectorAll(
    "[data-i18n-key]",
  );
  translatableElements.forEach((el) => {
    const key = el.getAttribute("data-i18n-key");
    // Extrahiere Interpolations-Keys/Werte aus dem HTML und
    // in JSON umwandeln
    const interpolations = el.getAttribute("data-i18n-opt");
    const parsedInterpolations = interpolations
      ? JSON.parse(interpolations)
      : {};
    // Übergebe die analysierten Interpolationen an polyglot.t(),
    // die automatisch Ersetzungen behandelt
    el.innerHTML = polyglot.t(key, parsedInterpolations);
  });
}
// ...

Mit dem obigen Code haben wir nun unseren interpolierten Einleitungsabsatz in der aktiven Sprache gerendert.

Pluralformen

Angenommen, wir möchten dir als aktuell angemeldetem User zeigen, wie viele Nachrichten du erhalten hast: „Du hast 1 neue Nachricht“ oder „Du hast 12 neue Nachrichten“, zum Beispiel. Polyglot setzt Pluralformen auf diese Weise problemlos um. Wir müssen nur unsere Übersetzungen mit dem speziellen interpolierten Zahlenwert, smart_count, hinzufügen.

<!-- ... -->
    <p
      data-i18n-key="new-messages"
      data-i18n-opt='{"smart_count": 12}'
    >
      You have %{smart_count} new messages"
    </p>
<!-- ... -->

Polyglot verwendet smart_count, um je nach aktueller Sprache die korrekte Pluralform aus einer Übersetzungsnachricht auszuwählen. Pluralformen werden in unseren Nachrichten mit vier senkrechten Strichen |||| getrennt. Englisch hat die Pluralformen one und other, und wir müssen sie in der Reihenfolge bereitstellen:

{
  // ...
  "new-messages": "You have %{smart_count} new message |||| You have %{smart_count} new messages"
}

Arabisch hat sechs Pluralformen und wir fügen sie unseren Nachrichten auf die gleiche Weise hinzu.

{
  // ...
  "new-messages": "لا توجد لديك رسائل جديدة |||| لديك رسالة جديدة |||| لديك رسالتان جداد |||| لديك %{smart_count} رسائل جديدة |||| لديك %{smart_count} رسالة جديدة |||| لديك %{smart_count} رسالة جديدة"
}

🗒 Hinweis » Schau dir den Abschnitt Wie lokalisiere ich eine Webseite mit JavaScript? ➞ Pluralformen an, um mehr über Pluralformen zu erfahren.

Eine weitere Sache: Standardmäßig ist Polyglot völlig neutral im Bezug auf das aktive Gebietsschema. Daher kennt es die Pluralregeln des aktiven Gebietsschemas nicht, es sei denn, wir geben das Gebietsschema beim Laden ausdrücklich an.

// ...
// Lade Übersetzungen für das angegebene Gebietsschema und übersetze
// die Seitenelemente für diese Sprache
async function loadAndTranslate(locale) {
  const translations = await loadTranslations(locale);
  polyglot.locale(locale);
  polyglot.replace(translations);
  translatePage();
}
// ...

Das war's! Wir unterstützen jetzt fortschrittliche Pluralformen in unserer App.

🔗 Ressource » Hol dir den gesamten Code für unsere Polyglot-App von unserem GitHub-Repo.

🔗 Ressource » Die offizielle Polyglot-Dokumentation ist genauso kompakt wie die Bibliothek selbst.

Wie lokalisiere ich eine Webseite mit i18next?

Während ich dies schreibe, ist i18next eine der beliebtesten JavaScript-i18n-Bibliotheken. Die „einmal lernen, überall [verwenden]“ Bibliothek funktioniert eigenständig und mit einer Vielzahl von JavaScript-Frameworks. Ein reichhaltiges Plugin-Ökosystem bedeutet, dass du oft nur eine NPM-Installation von der Lösung eines häufigen i18n-Problems entfernt bist. Das alles macht i18next zu einer einfachen Empfehlung.
Alles klar, genug Geschwafel. Lass uns unser kleines Demo noch einmal anschauen und es mit i18next lokalisieren.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <nav class="navbar">
      <div class="container">
        <ul class="navbar-list navbar-start">
          <li class="navbar-item">
            <a href="#" data-i18n-key="home" class="navbar-link">
              Home
            </a>
          </li>
          <li class="navbar-item">
            <a href="#" data-i18n-key="about" class="navbar-link">
              About
            </a>
          </li>
        </ul>
        <div class="navbar-end">
          <img src="img/translation-icon@2x.png" class="translation-icon" />
          <select data-i18n-switcher class="locale-switcher">
            <option value="en">English</option>
            <option value="ar">Arabic (العربية)</option>
          </select>
        </div>
      </div>
    </nav>
    <h1 data-i18n-key="app-title">With i18next</h1>
    <p data-i18n-key="lead" data-i18n-opt='{"username": "Zelda"}'>
      Welcome to my little spot on the interwebs, {{username}}!
    </p>
    <p data-i18n-key="new-messages" data-i18n-opt='{"count": 12}'>
      You have {{count}} new messages
    </p>
  </div>
  <script src="./bundle.js"></script>
</body>
</html>

Hier gibt es nicht viel Neues. Lass uns mit der Lokalisierung beginnen.

Installation

Wir verwenden Node und seinen NPM Paket-Manager, um i18next zu installieren. Zuerst erstellen wir die Datei package.json, um unsere Projektabhängigkeiten und NPM-Skripte zu verfolgen, indem wir Folgendes in der Kommandozeile ausführen.

npm init -y

Der Webpack-Bundler ermöglicht es uns, i18next, seine Plugins und unser eigenes JavaScript zu bündeln und in einer Datei im Browser bereitzustellen. Lass uns Webpack samt Entwicklungsserver installieren, der eine praktische Hot-Reload-Funktion hat, die die Entwicklung erleichtert:

npm install --save-dev webpack webpack-cli webpack-dev-server

Und vergiss unsere i18n-Bibliothek nicht:

npm install i18next

Ein praktisches npm start-Skript kann das Starten unseres Entwicklungsservers abkürzen.

{
  "name": "i18next-demo",
  //...
  "scripts": {
    "start": "webpack-dev-server --config webpack.config.js"
  },
  // ...
  "devDependencies": {
    "webpack": "^5.65.0",
    "webpack-cli": "^4.9.1",
    "webpack-dev-server": "^4.6.0"
  },
  "dependencies": {
    "i18next": "^21.6.3"
  }
}

🗒 Hinweis » Wir verwenden eine relativ einfache webpack.config.js-Datei, um unsere App zu bündeln und den Dev-Server zu konfigurieren. Schau sie dir in unserem Git-Repo auf GitHub an.

Lass uns einen index.js-Einstiegspunkt für unsere App erstellen und i18next einem kurzen Test unterziehen, um zu prüfen, ob es richtig installiert ist.

import i18next from "i18next";
console.log({ i18next });

Wenn du npm start in der Befehlszeile ausführst, startet der Webpack Dev Server und lädt deine App automatisch im Browser.

Grundlegende Übersetzungsnachrichten

i18next ist flexibel darin, wie Übersetzungsnachrichten angenommen werden. Das meiste konfigurieren wir, während wir die Bibliothek mit i18next.init(...) initialisieren. Wir fügen unsere Übersetzungsnachrichten direkt unter der Option resources ein.

import i18next from "i18next";
i18next.init({
  // Das aktive Gebietsschema
  lng: "en",
  // aktiviert nützliche Konsolenausgaben während der Entwicklung
  debug: true,
  // Übersetzungsnachrichten, nach Locale-Code zugeordnet
  Ressourcen: {
    en: {
      // Standardmäßig erwartet i18next Nachrichten unter dem
      // "translation" namespace
      translation: {
        "app-title": "With Polyglot",
        home: "Home"
        about: "About",
      },
    },
    ar: {
      translation: {
        "app-title": "مع بوليجلوت",
        "home": "الرئيسية",
        "about": "نبذة عنا",
      },
    },
  },
});
// Seitenelemente übersetzen
const translatableElements = document.querySelectorAll(
  "[data-i18n-key]",
);
translatableElements.forEach((el) => {
  const key = el.getAttribute("data-i18n-key");
  el.innerHTML = i18next.t(key);
});

Damit sollten wir beim Neuladen unserer App im Browser keine Änderungen sehen. Wenn du jedoch lng in "ar" änderst, siehst du die folgenden arabischen Übersetzungen.

🗒 Hinweis » Die debug: true-Option aktiviert sehr nützliche Konsolenprotokolle im Browser. Beachte oben die Informationen zu fehlenden Keys, zum Beispiel.

Asynchrone Übersetzungs­ladefunktion

Zukunftsorientierte Entwickler wie wir sollten unsere App skalierbarer machen, indem wir unsere Übersetzungen in separate Dateien aufteilen – eine pro Locale.

{
  "app-title": "Mit i18next"
  "home": "Home",
  "about": "About"
}

{
  "app-title": "مع آي أيتين نيكست",
  "home": "الرئيسية",
  "about": "نبذة عنا"
}

i18next ist ausgereift und hat viele Grundlagen abgedeckt. Deshalb müssen wir keinen eigenen Code schreiben, um Übersetzungsdateien aus dem Netzwerk zu laden. Das offizielle HTTP-Backend wird in die Bibliothek integriert und erledigt die gesamte Arbeit für uns. Lass es uns installieren.

npm install i18next-http-backend

Wir können jetzt das Backend in unsere index.js einbinden und nutzen(), während wir i18next initialisieren.

import i18next from "i18next";
import HttpApi from "i18next-http-backend";
// Wir machen die Funktion asynchron, damit wir warten können,
// bis die Übersetzungsdatei aus dem Netzwerk
// übertragen wird.
async function initI18next() {
  // Wir verwenden() das Backend und warten, bis es die
  // Übersetzungen aus dem Netzwerk lädt.
  await i18next.use(HttpApi).init({
    lng: "en",
    debug: true,
    // Entferne die eingebetteten `Ressourcen`
    // Laden der Entwicklungssprache deaktivieren
    fallbackLng: false,
    // Http-Backend konfigurieren
    backend: {
      loadPath: "/lang/{{lng}}.json",
    },
  });
}
// Schnelle Umstrukturierung des Seitenübersetzungscodes
// zu einer Funktion
function translatePageElements() {
  const translatableElements = document.querySelectorAll(
    "[data-i18n-key]",
  );
  translatableElements.forEach((el) => {
    const key = el.getAttribute("data-i18n-key");
    el.innerHTML = i18next.t(key);
  });
}
// Initialisierung
(async function () {
  await initI18next();
  translatePageElements();
})();

Die Option backend.loadPath überschreibt den Standardpfad der Übersetzungsdatei des Backends. Ein spezieller {{lng}} Platzhalter wird durch das aktive Gebietsschema ersetzt. Ein Beispiel: Wenn unsere App zum ersten Mal geladen wird, sucht das Backend nach /lang/en.json, da wir die Standardsprache in unserer Konfiguration zuvor als en festgelegt haben.
Das war’s auch schon. Unsere Übersetzungen werden jetzt aus dem Netzwerk geladen, anstatt in unseren Code eingebettet zu werden.

Unterstützte Sprachversionen und Fallback-Option

Oft möchten wir eine Liste von Sprachen (Locales) angeben, die unsere App unterstützt, sowie eine Sprache (Locale), auf die zurückgegriffen wird, wenn eine Übersetzung fehlt. Du kannst die Konfigurationsoptionen supportLngs und fallbackLng von i18next verwenden, um das zu erreichen.

// ...
async function initI18next() {
  await i18next.use(HttpApi).init({
    lng: "en",
    debug: true,
    supportedLngs: ["en", "ar"],
    fallbackLng: "en",
    backend: {
      loadPath: "/lang/{{lng}}.json",
    },
  });
}
// ...

✋🏽 Hinweis » Die Fallback-Sprache wird immer geladen, unabhängig vom aktiven Gebietsschema.

Automatische Erkennung deiner Sprache und Region

Es ist üblich, die Browsereinstellungen der User zu erkennen und deren Spracheinstellung zu verwenden, wenn wir sie unterstützen. Das ist normalerweise etwas knifflig, aber i18next hat ein offizielles Plugin, das uns hier schnell weiterhilft. Lass uns damit anfangen, es zu installieren.

npm install i18next-browser-languagedetector

Ähnlich wie beim HTTP-Backend importierst du das Detektor-Plugin und verwendest() es bei der Initialisierung.

import i18next from "i18next";
import HttpApi from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";
async function initI18next() {
  await i18next
    .use(HttpApi)
    .use(LanguageDetector)
    .init({
      debug: true,
      supportedLngs: ["en", "ar"],
      fallbackLng: "en",
      // Erlaube, "en" zu verwenden für
      // "en-US", "en-CA" usw.
      nonExplicitSupportedLngs: true,
      backend: {
        loadPath: "/lang/{{lng}}.json",
      },
    });
}
// ...

Und das ist alles, was du brauchst, um mithilfe von i18next eine solide automatische Spracherkennung zu erstellen.

🔗 Ressource » Du fragst dich vielleicht, welche Kriterien die Spracherkennung verwendet, um die Locale des Users zu bestimmen. Wir behandeln dies ausführlich in unserem Leitfaden zur React-Lokalisierung mit i18next.

✋🏽 Hinweis » Die Sprach- und Regionserkennung speichert die erkannte Spracheinstellung standardmäßig im lokalen Speicher deines Browsers und verwendet diesen Wert, wenn du unsere Website erneut besuchst.

🤿 Mehr Info » Wir haben einen speziellen Leitfaden zur Erkennung der Browsersprache mit JavaScript, der dein Interesse wecken könnte.

Sprachumschalter

Die automatische Spracherkennung ist zwar praktisch, aber oft brauchst du eine Benutzeroberfläche, um deine bevorzugte Sprache explizit festzulegen. Wir haben bereits das Markup für einen Sprachumschalter eingerichtet.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <nav class="navbar">
      <div class="container">
      <!-- ... -->
        <div class="navbar-end">
          <img src="img/translation-icon@2x.png" class="translation-icon" />
          <select data-i18n-switcher class="locale-switcher">
            <option value="en">English</option>
            <option value="ar">Arabic (العربية)</option>
          </select>
        </div>
      </div>
    </nav>
    <!-- ... -->
  </div>
  <script src="./bundle.js"></script>
</body>
</html>

Lass uns diesen HTML-Code nutzen und die Funktion i18next.changeLanguage() verwenden, um deine aktive Sprache auf die von dir gewählte Sprache einzustellen. Nachdem die lokalen Nachrichten geladen sind, kannst du translatePageElements anhängen, um die Seite mit den aktualisierten Übersetzungen neu zu rendern.

// ...
function bindLocaleSwitcher(initialValue) {
  const switcher = document.querySelector(
    "[data-i18n-switcher]",
  );
  switcher.value = initialValue;
  switcher.onchange = (e) => {
    i18next
      .changeLanguage(e.target.value)
      .then(translatePageElements);
  };
}
// Init
(async function () {
  await initI18next();
  translatePageElements();
  bindLocaleSwitcher(i18next.resolvedLanguage);
})();

✋🏽 Hinweis » Der Lokalisierungsdetektor könnte eine Sprache erkannt haben, die wir nicht unterstützen, und dieser Wert wird in i18next.language vorhanden sein. Wir verwenden i18next.resolvedLanguage, um sicherzustellen, dass wir die aktive, unterstützte Sprache beim Initialisieren unseres Sprachumschalters verwenden.

Et voilà! Die Sprachwechsel-Benutzeroberfläche ist fertig:

Interpolation

Standardmäßig verwendet i18next die {{variable}}-Syntax, um interpolierte Werte in Übersetzungen zu kennzeichnen.

<!-- ... -->
    <p data-i18n-key="lead" data-i18n-opt='{"username": "Zelda"}'>
      Welcome to my little spot on the interwebs, {{username}}!
    </p>
<!-- ... -->

{
  // ...
  "lead": "Welcome to my little spot on the interwebs, {{username}}!"
}

{
  // ...
  "lead": "أهلاً بك في مكاني الصغير على النت يا {{username}}."
}

Wir können diese dynamischen Werte aus unseren HTML-Attributen abrufen und sie an i18next.t() übergeben, das die Interpolation für uns übernimmt.

// ...
function translatePageElements() {
  const translatableElements = document.querySelectorAll(
    "[data-i18n-key]",
  );
  translatableElements.forEach((el) => {
    const key = el.getAttribute("data-i18n-key");
    const interpolations = el.getAttribute("data-i18n-opt");
    const parsedInterpolations = interpolations
      ? JSON.parse(interpolations)
      : {};
    el.innerHTML = i18next.t(key, parsedInterpolations);
  });
}
// ...

Damit werden unsere dynamischen Werte in unseren Nachrichten ersetzt.

Pluralformen

Unter der Haube versucht i18next, die Standard-Intl.PluralRules zu verwenden, um Pluralformen zu verwalten. Eine spezielle interpolierte count-Variable steuert die Wahl der Pluralform, abhängig von der aktiven Locale.

<!-- ... -->
    <p data-i18n-key="new-messages" data-i18n-opt='{"count": 12}'>
      You have {{count}} new messages
    </p>
<!-- ... -->

i18next verwendet eine message_form Konvention für plurale Nachrichten-Keys. Ein Beispiel: Um die one und other Formen in einer englischen new-messages Übersetzung zu behandeln, können wir Folgendes angeben.

{
  // ...
  "new-messages_one": "Du hast {{count}} neue Nachricht"
  "new-messages_other": "Du hast {{count}} neue Nachrichten"
}

Arabisch hat sechs Pluralformen, und wir können sie auf ähnliche Weise angeben.

{
  // ...
  "new-messages_zero": "لا توجد لديك رسائل جديدة",
  "new-messages_one": "لديك رسالة جديدة",
  "new-messages_two": "لديك رسالتان جداد",
  "new-messages_few": "لديك {{count}} رسائل جديدة",
  "new-messages_many": "لديك {{count}} رسالة جديدة",
  "new-messages_other": "لديك {{count}} رسالة جديدة"
}

Mit wenig Aufwand kann unsere App Nachrichten im Plural anzeigen.

🔗 Ressource » Hol dir den gesamten Code, den wir oben behandelt haben, aus unserem GitHub-Repo.

Wie lokalisiere ich eine React-, Angular- oder Vue-App?

In den letzten Jahren haben deklarative Frameworks wie React, Angular, Vue.js und andere die Frontend-Web-Welt im Sturm erobert. Wir behandeln diese Frameworks ausführlich in unserem Blog. Da React das beliebteste unter den großen Frameworks ist, geben wir dir hier gleich einen kurzen Leitfaden zur Lokalisierung von React-Apps. Und für andere deklarative Frameworks schau dir unsere folgenden ausführlichen Artikel an.

Angular-Lokalisierungsartikel

• Übersetzen von Angular-Anwendungen mit dem integrierten I18n-Modul
• Was ist die beste Angular-Bibliothek für Internationalisierung?
• Angular L10n mit I18next
• Angular 10 Tutorial zur Lokalisierung mit Transloco
• Full-Stack I18n mit Angular und .NET Core

Lokalisierungsartikel für Vue.js

• Der ultimative Vue-3-Lokalisierungsleitfaden
• Tiefgehender Einblick: Vue-Übersetzung mit vue-i18next 
• Das einzige Nuxt.js-Tutorial zu I18n, das du jemals brauchen wirst (Vue-basiert)

Lokalisierungsartikel für andere Frameworks

Uns ist bewusst, dass einige unserer Leser vielleicht Svelte, Next oder ein anderes Framework verwenden. Deshalb schreiben wir immer über das Neueste und Beste. Hier ist eine Auswahl an Leitfäden, wie du die App, die du gerade in deinem Lieblings-Framework baust, lokalisieren kannst:

• So lokalisierst du eine Svelte-App mit svelte-i18n
• Ein Schritt-für-Schritt-Leitfaden zur Svelte-Lokalisierung mit svelte-i18n v3
• So lokalisierst du SolidJS-Apps mit I18next
• So lokalisierst du Mithril-Anwendungen
• So lokalisierst du Apps mit dem Aurelia-Framework
• Lokalisierung von StimulusJS-Anwendungen mit I18next
• Full-Stack JavaScript I18n Schritt für Schritt (mit Next.js und Sails.js)

🗒 Hinweis » Genauer gesagt: Wenn du mit internationalen Telefonnummern arbeitest, schau dir die libphonenumber-Bibliothek an. Sie ist framework-unabhängig!

Wie lokalisiere ich eine React-App mit i18next?

Wie versprochen, werfen wir einen schnellen Blick darauf, wie du deine React-Apps mit der i18next-Bibliothek lokalisierst. Wir haben i18next bereits früher in diesem Artikel behandelt, daher konzentrieren wir uns hier auf die React-Integration.

🤿 Mehr Info » Ein Leitfaden zur React-Lokalisierung mit i18next deckt mehr ab und geht mehr in die Tiefe als unser kurzer Überblick hier.

Zuerst nehmen wir unsere vertraute Demo-App und zerlegen sie in React-Komponenten.

import "./App.css";
import Navbar from "./layout/Navbar";
function App() {
  return (
    <div className="container">
      <Navbar />
      <h1>React i18n</h1>
      <p>
        Welcome to my little spot on the interwebs, user
      </p>
      <p>You have count new messages</p>
    </div>
  );
}
export default App;

import LocaleSwitcher from "../features/LocaleSwitcher";
function Navbar() {
  return (
    <nav className="navbar">
      <div className="container">
        <ul className="navbar-list navbar-start">
          <li className="navbar-item">
            <a href="#" className="navbar-link">
              Home
            </a>
          </li>
          <li className="navbar-item">
            <a href="#" className="navbar-link">
              About
            </a>
          </li>
        </ul>
        <div className="navbar-end">
          <LocaleSwitcher />
        </div>
      </div>
    </nav>
  );
}
export default Navbar;

function LocaleSwitcher() {
  return (
    <>
      <img
        alt="Translation icon"
        src="img/translation-icon@2x.png"
        className="translation-icon"
      />
      <select className="locale-switcher">
        <option value="en">English</option>
        <option value="ar">Arabic (العربية)</option>
      </select>
    </>
  );
}
export default LocaleSwitcher;

Der Sprachumschalter tut momentan nicht viel, aber das ändern wir bald. Fürs Erste haben wir einen guten Ausgangspunkt für die Lokalisierung.

Installation der Bibliothek

Zusätzlich zu i18next nutzen wir das offizielle react-i18next -Integrationsframework, das die Verwendung von i18next mit React zum Kinderspiel macht. Wechsle ins Projektverzeichnis und führe folgenden Befehl in der Kommandozeile aus, um die Bibliotheken zu installieren.

npm install i18next react-i18next

Als Nächstes initialisieren wir i18next und verwende() die React-Integration, wie wir es machen. Der grundlegendste Weg, i18next Übersetzungen bereitzustellen, besteht darin, die resources Option bei der Initialisierung zu verwenden.

import i18next from "i18next";
import { initReactI18next } from "react-i18next";
i18next.use(initReactI18next).init({
  Ressourcen: {
    en: {
      translation: {
        "app-title": "With React",
      },
    },
    ar: {
      translation: {
        "app-title": "مع ريأكت",
      },
    },
  },
  lng: "en",
  debug: true,
  interpolation: {
    escapeValue: false,
  },
});
export default i18next;

🗒 Hinweis » Wir setzen die interpolation.escapeValue auf false, um die standardmäßige Escapierung, die i18next zum Schutz vor XSS-Angriffen durchführt, zu deaktivieren, da React das ohnehin für uns erledigt.

Ziehen wir unser Modul in unser Stammverzeichnis index.js, damit wir i18next initialisieren können, wenn unsere App geladen wird.

import React from "react";
import ReactDOM from "react-dom";
import "./lib/skeleton/normalize.css";
import "./lib/skeleton/skeleton.css";
import "./services/i18n";
import App from "./App";
import reportWebVitals from "./reportWebVitals";
ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById("root"),
);
// ...

Grundlegende Übersetzungen

Die vertraute i18next.t()-Übersetzungsfunktion kannst du auch in unseren React-Komponenten verwenden. Wir müssen nur den useTranslation React Hook importieren, damit t verfügbar ist.

import { useTranslation } from "react-i18next";
import Navbar from "./layout/Navbar";
import "./App.css";
function App() {
  const { t } = useTranslation();
  return (
    <div className="container">
      <Navbar />
      <h1>{t("app-title")}</h1>
      // ...
    </div>
  );
}
export default App;

Wenn du die App neu lädst, sieht alles genauso aus wie vorher. Wenn du jedoch den Wert lng in unserem Initialisierer src/services/i18n.js auf "ar" änderst, solltest du sehen, dass der App-Titel auf Arabisch lokalisiert wird.

Asynchrones Laden von Übersetzungsdateien

Mach unsere App skalierbarer, indem du unsere Übersetzungen in sprachspezifische Dateien aufteilst. Das praktische, offizielle i18next-http-backend Plugin macht das für uns zu einer schnellen Angelegenheit. Lass es uns installieren.

npm install i18next-http-backend

Das Backend wird standardmäßig nach Dateien unter /locales/{{lng}}/{{ns}}.json suchen, wobei {{lng}} die aktive Sprache auflöst und {{ns}} den aktiven Namensraum auflöst. Da der Standardnamensraum translation ist, können wir unsere englischen Übersetzungen in public/locales/en/translation.json ablegen.

{
  "app-title": "With React",
  "home": "Home",
  "about": "About"
}

Unsere arabische Datei folgt derselben Konvention:

{
  "app-title": "مع ريأكت",
  "home": "الرئيسية",
  "about": "نبذة عنا"
}

Wir müssen jetzt nur noch das Backend importieren und verwenden(), wenn wir i18next initialisieren. Wir sollten auch unsere Inline-Übersetzungen unter dem resources-Key entfernen, da das Plugin jetzt unsere Übersetzungsnachrichten aus dem Netzwerk lädt.

import i18next from "i18next";
import { initReactI18next } from "react-i18next";
import HttpApi from "i18next-http-backend";
i18next
  .use(initReactI18next)
  .use(HttpApi)
  .init({
    // Entferne `resources`
    lng: "en",
    debug: true,
    interpolation: {
      escapeValue: false,
    },
  });
export default i18next;

Wenn du die App neu lädst, solltest du exakt dieselbe lokalisierte Darstellung sehen. Natürlich werden die Übersetzungen der aktiven Sprache jetzt über das Netzwerk geladen, sodass deine App schneller lädt und leichter zu skalieren und zu warten ist.

Sprachumschalter

Eine Sprachwechsel-UI baust du mit React und i18next ganz einfach. Wir können unsere LocaleSwitcher-Komponente aktualisieren und das <select> darin so steuern, dass die aktive Sprache auf die von dir gewählte geändert wird.

import { useTranslation } from "react-i18next";
function LocaleSwitcher() {
  const { i18n } = useTranslation();
  return (
    <>
      <img
        src="img/translation-icon@2x.png"
        alt="Translation icon"
        className="translation-icon"
      />
      <select
        className="locale-switcher"
        value={i18n.language}
        onChange={(e) =>
          i18n.changeLanguage(e.target.value)
        }
      >
        <option value="en">English</option>
        <option value="ar">Arabic (العربية)</option>
      </select>
    </>
  );
}
export default LocaleSwitcher;

Die i18next React-Integration stellt sicher, dass die Übersetzungen neu gerendert werden, wenn die aktive Sprache geändert wird.

🔗 Ressource » Hol dir den Code für alles, was wir oben gebaut haben, aus unserem GitHub-Repository.

Artikel zur Lokalisierung mit React

Wir lieben es, in unserem Blog über React zu schreiben, deshalb freuen wir uns, dir eine Auswahl unserer tiefgehenden Artikel und React-basierten Framework-Tutorials rund um das Thema Lokalisierung zu zeigen:

• Ein Leitfaden für die React-Lokalisierung mit i18next
• Einführung in JavaScript I18n mit i18next und Moment.js
• React Redux Tutorial: Internationalisierung mit react-i18n-redux
• Erstelle deine eigene i18n-Lösung mit React und Redux
• Lokalisierung von JavaScript- und React-Apps mit LinguiJS
• Lokalisierte serverseitige Darstellung mit React
• Meteor-Anwendungen mit React lokalisieren
• Ein umfassender Leitfaden zur Lokalisierung von React Native
• Alles, was du über i18n mit Gatsby wissen musst (React-basiert)
• Full-Stack JavaScript I18n Schritt für Schritt (mit dem React-basierten Next.js)

Wie lokalisiere ich eine Webseite mit jQuery und i18next?

Auch wenn jQuery heute nicht mehr so angesagt ist wie vor ein paar Jahren, gehört es immer noch zu den beliebtesten JavaScript-Bibliotheken. Du wirst feststellen, dass das Lokalisieren von jQuery-Apps mit der i18next Bibliothek ziemlich einfach ist. Ein offizielles i18next jQuery-Plugin ist ganz einfach einzurichten, also lass uns damit unsere bewährte Demo-App lokalisieren.

🗒 Hinweis » Wir haben i18next ausführlicher weiter oben in diesem Artikel behandelt, daher konzentrieren wir uns hier auf die jQuery-Integration.

Wenn du mitgelesen hast, wird dir die folgende Starter-App bekannt vorkommen. Sie dient als gute Grundlage für unsere Lokalisierungsarbeit.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <nav class="navbar">
      <div class="container">
        <ul class="navbar-list navbar-start">
          <li class="navbar-item">
            <a href="#" data-i18n="home" class="navbar-link">
              Home
            </a>
          </li>
          <li class="navbar-item">
            <a href="#" data-i18n="about" class="navbar-link">
              About
            </a>
          </li>
        </ul>
        <div class="navbar-end">
          <img src="img/translation-icon@2x.png" class="translation-icon" />
          <select data-i18n-switcher class="locale-switcher">
            <option value="en">English</option>
            <option value="ar">Arabic (العربية)</option>
          </select>
        </div>
      </div>
    </nav>
    <h1 data-i18n="app-title">jQuery i18n</h1>
    <p data-i18n="lead" data-i18n-options='{"username": "Jackie"}'>
      Welcome to my little spot on the interwebs, {{username}}!
    </p>
    <p data-i18n="new-messages" data-i18n-options='{"count": 3}'>
      You have {{count}} new messages
    </p>
  </div>
</body>
</html>

🗒 Hinweis » Standardmäßig verwendet das i18next jQuery-Plugin data-i18n (nicht wie zuvor data-i18n-key) als Übersetzungs-Key. Das kannst du in den Plugin-Optionen ändern.

Zeit für's Lokalisieren? Los geht's.

Installation

Der einfachste Weg, i18next und das jQuery-Plugin zu installieren, ist, ihre minifizierten Distributionsdateien herunterzuladen und sie in dein HTML einzubinden. Du kannst die Dateien an den folgenden Orten abrufen.

• jQuery komprimiert
• i18next minified
• jQuery i18next Plugin minifiziert

🔗 Ressource » Schau dir die offizielle Dokumentation des i18next jQuery Plugins auf GitHub an.

Nachdem du die oben genannten Dateien heruntergeladen hast, kannst du sie in ein js/lib Verzeichnis in deinem Projekt ablegen und in deine Haupt-HTML-Seite einbinden.

<!DOCTYPE html>
<html lang="en">
<head>
   <!-- ... -->
</head>
<body>
  <div class="container">
    <!-- ... -->
  </div>
  <script src="./js/lib/jquery-3.6.0.min.js"></script>
  <script src="./js/lib/i18next.min.js"></script>
  <script src="./js/lib/jquery-i18next.min.js"></script>
  <!-- Unser benutzerdefiniertes JavaScript kommt gleich... -->
  <script src="./js/scripts.js"></script>
</body>
</html>

Grundlegende Übersetzungen

Mit unseren installierten Bibliotheken können wir jetzt etwas Setup-Code schreiben, um die grundlegende Lokalisierungsarbeit zum Laufen zu bringen.

// i18next initialisieren
i18next.init({
  lng: "en",     // Ausgangssprache
  debug: true,   // Bietet hilfreiche Konsolenmeldungen
  resources: {   // Übersetzungen
    en: {
      translation: {
        "app-title": "jQuery + i18next",
      },
    },
    ar: {
      translation: {
        "app-title": "جي كويري + آي إيتين نيكست",
      },
    },
  },
});
// i18next jQuery Plugin initialisieren
jqueryI18next.init(i18next, $);
// Seitenelemente übersetzen
$("body").localize();

Wir haben i18next.init(...) bereits früher in diesem Artikel behandelt. Beachte, dass wir hier auch einen jQueryI18next.init(...) Aufruf haben. Im einfachsten Fall übernimmt die jQuery i18next Plugin init-Funktion die aktive i18next Instanz sowie einen Verweis auf das jQuery-Objekt $.
Wenn das Plugin initialisiert wird, fügt es eine localize()-Funktion zu jQuery hinzu. Wenn du $(selector).localize() aufrufst, lokalisiert das Plugin alle Elemente unter der ausgewählten Hierarchie. Für jedes Element wird, wenn ein data-i18n Attribut gefunden wird, die entsprechende Übersetzung für die aktive Sprache eingefügt.
Ein Beispiel:

// In unserem JavaScript
i18next.init({
  lng: "en",
  Ressourcen: {
    en: {
      translation: {
        "app-title": "jQuery + i18next",
      },
    },
    ar: {
      translation: {
        "app-title": "جي كويري + آي إيتين نيكست",
      },
    },
  },
});
jqueryI18next.init(i18next, $);
$("#main-title").localize();
// In unserem HTML
<h1 id="main-title" data-i18n="app-title"></h1>
// Wird gerendert als
<h1 id="main-title" data-i18n="app-title">jQuery + i18next</h1>

Einfach und schön 😊

Und wenn wir unsere Ausgangssprache auf Arabisch ändern, indem wir lng auf "ar" ändern, erhalten wir stattdessen einen arabischen Titel.

Asynchrones Laden von Übersetzungsdateien

„Wie wäre es, wenn wir unsere Übersetzungsdateien in separate Dateien aufteilen, eine pro Sprachvariante?“, höre ich dich fragen. Keine Sorge: Das offizielle i18next HTTP-Backend-Plugin deckt das ab.
Um das Plugin zu installieren, schnapp dir das minimierte Verteilungsskript von GitHub und leg es in dein js/lib Verzeichnis. Und natürlich sollten wir es auch in unser HTML einfügen.

<!DOCTYPE html>
<html lang="en">
<head>
   <!-- ... -->
</head>
<body>
  <div class="container">
    <!-- ... -->
  </div>
  <script src="./js/lib/jquery-3.6.0.min.js"></script>
  <script src="./js/lib/i18next.min.js"></script>
  <script src="./js/lib/i18nextHttpBackend.min.js"></script>
  <script src="./js/lib/jquery-i18next.min.js"></script>
  <script src="./js/scripts.js"></script>
</body>
</html>

Jetzt können wir unsere App skalierbar machen, indem wir die Übersetzungen in separate JSON-Dateien auslagern.

{
  "app-title": "Mit jQuery + i18next"
  "home": "Home",
  "about": "About"
}

{
  "app-title": "مع جي كويري و آي إيتين نيكست"
  "home": "الرئيسية",
  "about": "نبذة عنا"
}

Wir müssen unseren Setup-Code überarbeiten, um bei der Initialisierung von i18next das HTTP-Plugin use() zu verwenden. Warte auch, bis die Übersetzungsdatei deiner Ausgangssprache heruntergeladen ist, bevor du versuchst, die Seitenelemente zu übersetzen.

// Warten auf Übersetzungen, die über das Netzwerk übertragen werden,
// bevor das jQuery-Plugin initialisiert wird.
async function initI18n() {
  // Verwende das Http-Backend-Plugin, um Übersetzungen herunterzuladen
  await i18next.use(i18nextHttpBackend).init({
    lng: "en",
  // Entferne die `resources`-Option, da unsere Übersetzungen
  // sich jetzt in JSON-Dateien befinden.
  });
  jqueryI18next.init(i18next, $);
}
// Refaktorisieren zu Funktion
function translatePage() {
  $("body").localize();
}
// Init
(async function () {
  // Warten, bis i18next initialisiert ist
  // Seitenelemente übersetzen
  await initI18n();
  translatePage();
})();

Wenn wir unsere App neu laden, bemerken wir keinen Unterschied in der Ausgabe. Ein näherer Blick auf den Netzwerk-Tab der Entwicklertools zeigt eine wartungsfreundlichere „Lade es herunter, wenn du es brauchst“-Lösung für Übersetzungsdateien.

Sprachumschalter

Vielleicht ist dir aufgefallen, dass wir etwas HTML-Code haben, der wie eine Sprachumschalter-UI in unserer Demo aussieht.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <nav class="navbar">
      <div class="container">
        <!-- ... -->
        <div class="navbar-end">
          <img src="img/translation-icon@2x.png" class="translation-icon" />
          <select data-i18n-switcher class="locale-switcher">
            <option value="en">English</option>
            <option value="ar">Arabic (العربية)</option>
          </select>
        </div>
      </div>
    </nav>
    <!-- ... -->
  </div>
  <!-- ... -->
</body>
</html>

Lass uns das <select>-Element oben so verknüpfen, dass unsere App ihre Übersetzungen auf die vom User ausgewählte Sprache umschaltet.

// ...
function bindLocaleSwitcher() {
  const $switcher = $("[data-i18n-switcher]");
  // Anfangswert
  $switcher.val(i18next.language);
  $switcher.on("change", async function () {
    // Das Ändern der aktiven Sprache führt dazu, dass ihre
    // Übersetzungen aus dem Netzwerk laden. Also
    // warten wir auf das Laden, bevor wir
    // Seitenelemente aktualisieren.
    await i18next.changeLanguage($switcher.val());
    translatePage();
  });
}
(async function () {
  await initI18n();
  translatePage();
  bindLocaleSwitcher();
})();

Und schon haben wir einen funktionierenden Sprachumschalter.

Interpolation

Der Umgang mit dynamischen Werten in unseren Übersetzungen ist mit i18next sofort verfügbar. Wir müssen nur eine data-i18n-options JSON-Map im Element bereitstellen, für das wir Interpolationen haben.

<!-- ... -->
    <p data-i18n="lead" data-i18n-options='{"username": "Jackie"}'>
      Welcome to my little spot on the interwebs, {{username}}!
    </p>
<!-- ... -->

Das i18next jQuery-Plugin sucht standardmäßig nicht nach data-i18n-options; wir müssen seine useOptionsAttr-Konfigurationsoption verwenden, um die automatische Interpolation zu aktivieren.

async function initI18n() {
  await i18next.use(i18nextHttpBackend).init({ lng: "en" });
  jqueryI18next.init(i18next, $, { useOptionsAttr: true });
}
// ...

Lass uns sicherstellen, dass wir den Platzhalter {{variable}}haben, den i18next in unseren Übersetzungsnachrichten erwartet.

{
  "app-title": "Mit jQuery + i18next"
  "home": "Home",
  "about": "About",
  "lead": "Welcome to my little spot on the interwebs, {{username}}!"
}

{
  "app-title": "مع جي كويري و آي إيتين نيكست"
  "home": "الرئيسية",
  "about": "نبذة عنا",
  "lead": "أهلاً بك في مكاني الصغير على النت يا {{username}}."
}

Na also: Die Interpolationen wurden interpoliert.

Pluralformen

Wenn wir Pluralformen haben, verwenden wir dasselbe data-i18n-options-Attribut, um eine spezielle count-Zählervariable bereitzustellen.

🗒 Hinweis » Schau dir den vorherigen Abschnitt i18next ➞ Pluralformen an, wenn du wissen willst, wie die Bibliothek mit Pluralformen arbeitet.

<!-- ... -->
    <p data-i18n="new-messages" data-i18n-options='{"count": 3}'>
      You have {{count}} new messages
    </p>
<!-- ... -->

Wir verwenden eine key_form-Konvention, wenn wir unsere Pluralnachrichten angeben. Englisch hat zwei Pluralformen, one und other.

{
  // ...
  "new-messages_one": Du hast {{count}} neue Nachricht
  "new-messages_other": "Du hast {{count}} neue Nachrichten"
}

Arabisch hat sechs Pluralformen, und sie werden automatisch von i18next behandelt.

{
  // ...
  "new-messages_zero": "لا توجد لديك رسائل جديدة",
  "new-messages_one": "لديك رسالة جديدة",
  "new-messages_two": "لديك رسالتان جداد",
  "new-messages_few": "لديك {{count}} رسائل جديدة",
  "new-messages_many": "لديك {{count}} رسالة جديدة",
  لديك {{count}} رسالة جديدة
}

So bekommt unsere App ohne zusätzlichen Code eine komplexe Pluralunterstützung.

🔗 Ressource » Hol dir den voll funktionsfähigen Code für die obige App aus unserem GitHub-Repository.

🔗 Ressource » Wenn du nach einer Alternative zu i18next suchst, schau dir jQuery i18n für Fortgeschrittene an, der die jQuery.i18n-Bibliothek verwendet.

Wie lokalisiere ich eine Webseite mit dem ICU-Format unter Verwendung von Globalize?

Wenn du die nahezu vollständige Lokalisierungsabdeckung der International Components for Unicode (ICU) und des Unicode Common Locale Data Repository (CLDR) in deiner JavaScript-App haben möchtest, erledigt die Globalize-Bibliothek das auf jeden Fall. Lass uns gemeinsam betrachten, wie du Globalize installierst und damit unsere bescheidene Demo-App lokalisierst.

🔗 Ressource » Der fehlende Leitfaden zum ICU-Nachrichtenformat behandelt ICU und CLDR ausführlicher.

🗒 Hinweis » Im Gegensatz zu vielen anderen Bibliotheken, die wir in diesem Artikel behandeln, unterstützt Globalize tatsächlich Internet Explorer 9+.

Welche Demo?, fragst du. Unser zuverlässiger One-Pager natürlich.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <nav class="navbar">
      <div class="container">
        <ul class="navbar-list navbar-start">
          <li class="navbar-item">
            <a href="#" data-i18n-key="home" class="navbar-link">
              Home
            </a>
          </li>
          <li class="navbar-item">
            <a href="#" data-i18n-key="about" class="navbar-link">
              About
            </a>
          </li>
        </ul>
        <div class="navbar-end">
          <img src="img/translation-icon@2x.png" class="translation-icon" />
          <select data-i18n-switcher class="locale-switcher">
            <option value="en">English</option>
            <option value="ar">Arabic (العربية)</option>
          </select>
        </div>
      </div>
    </nav>
    <h1 data-i18n-key="app-title">With Globalize</h1>
    <p data-i18n-key="lead" data-i18n-opt='{"username": "Stella"}'>
      Welcome to my little spot on the interwebs, {username}!
    </p>
    <p data-i18n-key="new-messages" data-i18n-opt='{"count": 100}'>
      You have # new messages
    </p>
  </div>
</body>
</html>

Fangen wir der Lokalisierung an.

Installation

Globalize ist sehr modular, daher kann die Installation mit reinem JavaScript etwas umständlich sein. Dennoch ist es ein relativ einfaches Projekt.

• Lade die neueste Globalize-Version herunter
• Lade die neueste CLDR-Traverser (cldr.js)-Version herunter
• Lade die neueste CLDR JSON-Datenversion herunter. Achte darauf, dass du die -full Variante aus der Veröffentlichungsübersicht herunterlädst, um hier mitmachen zu können.

Das sollte uns drei ZIP-Dateien geben. Lass sie uns entpacken, ihre entpackten obersten Verzeichnisse umbenennen und in unser Projektverzeichnis verschieben. Ich habe meins unter dem Verzeichnis /lib in meinem Projekt abgelegt, sodass mein Projekt jetzt so aussieht:

.
├── css/
├── img/
├── lib/
│   ├── cldr/          << umbenannt von cldr-x.x.x
│   ├── cldr-json/     << umbenannt von cldr-x.x.x-json-full
│   └── globalize/     << umbenannt von globalize.x.x
└── index.html

🔗 Ressource » Die offizielle Dokumentation beschreibt verschiedene Möglichkeiten der Installation von Globalize.

Verwendung des Anforderungstools zur Bestimmung der benötigten Skripte

Wir benötigen immer einige Teile von Globalize und cldr.js; andere hängen von den Lokalisierungsfunktionen unserer App ab. Ein praktisches Tool, So What’cha Want, kann dir sagen, welche Dateien du je nach deinen ausgewählten Funktionen in dein Projekt holen solltest. Wir können beginnen, indem wir alle Funktionen abwählen, außer message.

Beachte die beiden Dateilisten am unteren Ende der Seite. Die Liste auf der linken Seite zeigt an, welche Dateien von Globalize und cldr.js importiert werden sollen; wir können <script>-Tags dafür verwenden.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <!-- ... -->
  </div>
  <!-- Globalize-Anforderungen -->
  <script src="./lib/cldr/dist/cldr.js"></script>
  <script src="./lib/cldr/dist/cldr/event.js"></script>
  <script src="./lib/cldr/dist/cldr/supplemental.js"></script>
  <script src="./lib/globalize/dist/globalize.js"></script>
  <script src="./lib/globalize/dist/globalize/message.js"></script>
  <!-- Unser App-Einstiegspunkt -->
  <script src="./index.js"></script>
</body>
</html>

Die Liste unten rechts von So What'cha Want enthält die CLDR JSON-Daten, die wir benötigen. Hol dir dieses JSON in deinen Code und gib es an Globalize über die load()-Funktion weiter.

// Wir fügen nach und nach mehr zu dieser Liste hinzu
const supplementals = ["likelySubtags"];
async function loadIntoGlobalize(featureUrls) {
  await Promise.all(
    featureUrls.map((url) => fetchJson(url))
  ).then((downloaded) =>
    downloaded.forEach((feature) => Globalize.load(feature))
  );
}
function supplementalUrlsFor(options) {
  return options.map(
    (feature) =>
      `/lib/cldr-json/cldr-core/supplemental/${feature}.json`
  );
}
async function fetchJson(url) {
  const response = await fetch(url);
  return await response.json();
}
(async function () {
  // Lade ergänzende Anforderungen
  await loadIntoGlobalize(
    supplementalUrlsFor(supplementals)
  );
})();

Das war's mit der Einrichtung. Okay, es ist nicht die einfachste Bibliothek zu installieren, aber für ein Projekt, das eine zuverlässige Lokalisierung benötigt, ist es die Mühe wert.

Grundlegende Übersetzungen

Die Verwendung von Globalize zur Übersetzung von Seitenelementen ist ein einfacher dreistufiger Prozess.

// ...
(async function () {
  await loadIntoGlobalize(
    supplementalUrlsFor(supplementals)
  );
  // 1. Lade Übersetzungsnachrichten
  Globalize.loadMessages({
    en: {
      "app-title": "Hello Globalize!",
    },
    ar: {
      "app-title": "أهلاً جلوبالايز",
    },
  });
  // 2. Setze die Standardsprache
  Globalize.locale("en");
  // 3. Verwende formatMessage(), um die Übersetzung anhand des Keys zu erhalten
  document.querySelector(
    "[data-i18n-key='app-title']"
  ).textContent = Globalize.formatMessage("app-title");
})();

🔗 Ressource » Die offizielle Globalize-Dokumentation hat einen praktischen API-Abschnitt, der verfügbare Funktionen auflistet.

Cooool. Unser Titel wird mit der Übersetzung unserer Standardsprache angezeigt.

Wenn wir den obigen Aufruf ändern, so dass er Globalize.locale("ar") lautet, erhalten wir den Titel unserer App auf Arabisch.

Umgang mit fehlenden Nachrichten

Verallgemeinere den Code, der Seitenelemente übersetzt, indem du eine translatePageElements()-Funktion schreibst. Im Gegensatz zu anderen i18n-Bibliotheken löst Globalize einen Fehler aus und stoppt, wenn bei einem bestimmten Key für formatMessage() eine Nachricht fehlt. Nichts, was ein wenig try/catch nicht abmildern könnte ...

// ...
function translatePageElements() {
  const elements = document.querySelectorAll(
    "[data-i18n-key]"
  );
  elements.forEach((element) => {
    const key = element.getAttribute("data-i18n-key");
    try {
      element.innerHTML = Globalize.formatMessage(key);
    } catch (error) {
      if (error.code === "E_MISSING_MESSAGE") {
        // Zeig Konsolenwarnungen bei fehlenden Nachrichten an,
        // anstatt zum Stillstand zu kommen.
        console.warn(error.message);
        // Zeige den Key-Wert auf der Seite für eine fehlende Nachricht an.
        element.innerHTML = key;
      } else {
        console.error(error);
      }
    }
  });
}
(async function () {
  // ...
  Globalize.loadMessages(/* ... */);
  Globalize.locale("en");
  translatePageElements();
})();

Weniger "Absturz bei fehlender Nachricht", und mehr "Key-Wert anzeigen und in der Konsole warnen".

Asynchrones Laden von Übersetzungsdateien

Wie wir es mit anderen Lösungen in diesem Artikel gemacht haben, lass uns unsere Übersetzungsnachrichten in JSON-Dateien pro Locale aufteilen, um Skalierbarkeit und Wartbarkeit zu gewährleisten.

{
  // Globalize erwartet, dass der Sprachcode der oberste Key ist
  "en": {
    "app-title": "Mit Globalize"
    "home": "Home",
    "about": "About"
  }
}

{
  "ar": {
    "app-title": "مع جلوبالايز",
    "home": "الرئيسية",
    "about": "نبذة عنا"
  }
}

Eine wiederverwendbare setLocale()-Funktion kann unsere Übersetzungsdatei laden, Globalize konfigurieren und unsere Seitenelemente neu rendern.

const defaultLocale = "en";
// ...
 async function setLocale(locale) {
  const messages = await fetchJson(`/lang/${locale}.json`);
  Globalize.loadMessages(messages);
  Globalize.locale(locale);
  translatePageElements();
}
// ...
(async function () {
  await loadIntoGlobalize(
    supplementalUrlsFor(supplementals)
  );
  setLocale(defaultLocale);
})();

Asynchrones Laden der Übersetzungsdateien: erledigt.

Sprachumschalter

Wir können die Funktion setLocale(), die wir gerade geschrieben haben, verwenden, um unsere Sprachumschaltung zum Laufen zu bringen. Vermutlich erinnerst du dich, dass unsere Demo-App bereits etwas HTML-Code für den Umschalter hat ...

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <nav class="navbar">
      <div class="container">
        <!-- ... -->
        <div class="navbar-end">
          <img src="img/translation-icon@2x.png" class="translation-icon" />
          <select data-i18n-switcher class="locale-switcher">
            <option value="en">English</option>
            <option value="ar">Arabic (العربية)</option>
          </select>
        </div>
      </div>
    </nav>
    <!-- ... -->
  </div>
  <!-- ... -->
  <script src="./index.js"></script>
</body>
</html>

Ein bisschen JavaScript bringt den Umschalter zum Umschalten.

const defaultLocale = "en";
// ...
function bindLocaleSwitcher() {
  const switcher = document.querySelector(
    "[data-i18n-switcher]"
  );
  // Globalize.locale() gibt das aktive Gebietsschema zurück.
  switcher.value = Globalize.locale().locale;
  switcher.onchange = (e) => {
    setLocale(e.target.value);
  };
}
(async function () {
  await loadIntoGlobalize(
    supplementalUrlsFor(supplementals)
  );
  await setLocale(defaultLocale);
  bindLocaleSwitcher(defaultLocale);
})();

Und damit kannst du die Sprache auswählen, die du bevorzugst.

Sprachbezeichnungen in der aktiven Sprache anzeigen

Eines der mächtigsten Features, wenn du eine ICU-Bibliothek wie Globalize nutzt, ist der Zugriff auf eine immens große Vielfalt an CLDR-Lokalisierungsdaten. Zum Beispiel könntest du die Sprachen in deinem Sprachumschalter im aktiven Gebietsschema anzeigen – Englisch wäre zum Beispiel „الإنجليزية“ auf Arabisch. Dazu müssten wir die Haupt-CLDR-Daten importieren und dann unseren Text select > option aktualisieren.

const defaultLocale = "ar";
const mains = {
    localenames: ["languages"],
};
const supplementals = "likelySubtags"];
async function setLocale(locale) {
  const messages = await fetchJson(`/lang/${locale}.json`);
  Globalize.loadMessages(messages);
  await loadIntoGlobalize(mainUrlsFor(mains, locale));
  Globalize.locale(locale);
  translatePageElements();
  setLocaleSwitcherDisplayNames();
}
// Given options = {
//   localenames: ["languages"],
//   Daten: ["ca-generic", "ca-gregorian"],
// }
// und locale = "en" gibt ein Array zurück wie folgt
// [
//    "/lib/cldr-json/cldr-localenames-full/main/en/languages.json",
//    "/lib/cldr-json/cldr-dates-full/main/en/ca-generic.json",
//    "/lib/cldr-json/cldr-dates-full/main/en/ca-gregorian.json"
// ]
function mainUrlsFor(options, locale) {
  const result = [];
  Object.keys(options).forEach((key) => {
    options[key].forEach((collection) => {
      result.push(
        `/lib/cldr-json/cldr-${key}-full/main/${locale}/${collection}.json`
      );
    });
  });
  return result;
}
function setLocaleSwitcherDisplayNames() {
  const options = document.querySelectorAll(
    "[data-i18n-switcher] option"
  );
  options.forEach((option) => {
    const localeCode = option.value;
    // Hol dir die CLDR-Hauptdaten über den Pfad
    option.textContent = Globalize.cldr.main(
      `localeDisplayNames/languages/${localeCode}`
    );
  });
}
// ...

Du kannst unseren Haupt-JSON-Ladecode verwenden, wann immer du die CLDR-JSON-Hauptdaten abrufen willst. Andernfalls sorgt ein wenig DOM-Manipulation dafür, dass wir beim Auswählen eines neuen Gebietsschemas lokalisierte Locale-Namen erhalten (so meta!).

🔗 Ressource » Die offiziellen cldr.js-Dokumente erklären ausführlicher, wie man CLDR-JSON-Daten abrufen kann.

Interpolation

Die Verarbeitung dynamischer Werte in unserer Nachricht erfolgt über das ICU-Nachrichtenformat mithilfe der Syntax {variable}.

{
  "en": {
    // ...
    "lead": "Welcome to my little spot on the interwebs, {username}!"
  }
}

{
  "ar": {
    // ...
    "lead": "أهلاً بك في مكاني الصغير على النت يا {username}."
  }
}

Dazu können wir Key/Wert-Ersatzpaare in unserem HTML bereitstellen.

<!-- ... -->
    <p data-i18n-key="lead" data-i18n-opt='{"username": "Stella"}'>
      Welcome to my little spot on the interwebs, {username}!
    </p>
<!-- ... -->

Und jetzt müssen wir nur noch diese Key/Wert-Paare lesen und sie an Globalize.formatMessage() übergeben.

// ...
function translatePageElements() {
  const elements = document.querySelectorAll(
    "[data-i18n-key]"
  );
  elements.forEach((element) => {
    const key = element.getAttribute("data-i18n-key");
    const interpolations =
      element.getAttribute("data-i18n-opt");
    const parsedInterpolations = interpolations
      ? JSON.parse(interpolations)
      : {};
    try {
      element.innerHTML = Globalize.formatMessage(
        key,
        parsedInterpolations
      );
    } catch (error) {
      if (error.code === "E_MISSING_MESSAGE") {
        console.warn(error.message);
      } else {
        console.error(error);
      }
    }
  });
}
// ...

Kein Problem.

Pluralformen

Die Handhabung von Pluralformen im ICU-Format ist unübertroffen und deckt komplexe Pluralformen wie die in Russisch oder Arabisch ab. Natürlich müssen wir die Pluralfunktion erst einrichten, bevor wir sie verwenden können.

Pluralanforderungen hinzufügen

Lass uns zu So What’cha Want gehen, um herauszufinden, was wir einbeziehen müssen, wenn wir plural aktivieren.

Gar nicht schlecht. Zuerst müssen wir ein <script>-Tag für die Funktion hinzufügen.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- ... -->
</head>
<body>
  <div class="container">
    <!-- ... -->
  </div>
  <script src="./lib/cldr/dist/cldr.js"></script>
  <script src="./lib/cldr/dist/cldr/event.js"></script>
  <script src="./lib/cldr/dist/cldr/supplemental.js"></script>
  <script src="./lib/globalize/dist/globalize.js"></script>
  <script src="./lib/globalize/dist/globalize/message.js"></script>
  <script src="./lib/globalize/dist/globalize/plural.js"></script>
  <script src="./index.js"></script>
</body>
</html>

Wir benötigen außerdem die ergänzende JSON für plurals und wahrscheinlich auch die für ordinals, wenn wir Formatierungen wie „3.“ und „4.“ in unseren Nachrichten abdecken wollen. Wir müssen nur die Anforderungen zu unserem supplementals-Konfigurationsarray hinzufügen. Unsere App ist bereits so eingerichtet, dass sie das entsprechende JSON für uns beim Start lädt.

const defaultLocale = "ar";
const supplementals = [
  "likelySubtags",
  "plurals",
  "ordinals",
];
// ...

Jetzt können wir unsere Pluralnachrichten hinzufügen. Die ICU-Plural-Syntax ist weitgehend intuitiv: Eine count-Variable bestimmt die gewählte Pluralform, und ein spezielles #-Symbol wird beim Anzeigen durch den count-Wert ersetzt.

{
  "en": {
    // ...
    "neue-nachrichten": [
      // Wir können `count` so nennen, wie wir wollen - solange wir
      // den Key in unserem Aufruf von formatMessage() abstimmen.
      "You have {count, plural,",
      "    one {# new message}",
      "  other {# new messages}",
      "}"
    ]
  }
}

🗒 Hinweis » Globalize ermöglicht es uns, mehrzeilige Nachrichten durch die Verwendung von Arrays aufzuteilen.

Die sechs Pluralformen im Arabischen werden durch das ICU-Format behandelt.

{
  "ar": {
    // ...
    "new-messages": [
      "{count, plural, ",
      "   zero {لا توجد لديك رسائل جديدة}",
          one {لديك رسالة جديدة}
          two {لديك رسالتان جداد}
          few {لديك # رسائل جديدة}
         many {لديك # رسالة جديدة}
      "  other {لديك # رسالة جديدة}",
      "}"
    ]
  }
}

🤿 Mehr Info » Wir behandeln ICU-Mehrzahlformen ausführlicher in "Der fehlende Leitfaden zum ICU-Nachrichtenformat".

Natürlich müssen wir sicherstellen, dass count an Globalize.formatMessage() übergeben wird.

<!-- ... -->
    <p data-i18n-key="new-messages" data-i18n-opt='{"count": 110}'>
      You have # new messages
    </p>
<!-- ... -->

Und damit sind die Pluralformen im Grunde erledigt.

🗒 Hinweis » Die ICU-Implementierung von Globalize bietet umfassende Datums- und Zahlenformatierung. Schau dir die offizielle Dokumentation an, um mehr zu erfahren.

🔗 Ressource » Wir behandeln weitere Globalize-Installationsoptionen und Anwendungsfälle in JS I18n mit Globalize.js.

Damit endet unser Leitfaden zur JavaScript-Lokalisierung.

Und das war's für dieses Mal. Wir hoffen, dir hat unser Ausflug in einige der beliebtesten JavaScript-Lokalisierungslösungen gefallen.

🔗 Ressource » Wenn du mit Ruby on Rails arbeitest, könnte dir JavaScript in Rails-Apps lokalisieren einiges bringen.

Und wenn du deinen Lokalisierungsprozess auf das nächste Level bringen willst, schau dir Phrase an. Phrase unterstützt das ICU-Format, alle anderen hier behandelten Übersetzungsformate und viele mehr. Mit seiner CLI und der Synchronisierung mit Bitbucket, GitHub und GitLab läuft deine i18n wie von selbst. Die voll ausgestattete Phrase-Webkonsole mit maschinellem Lernen und smarten Vorschlägen macht richtig Spaß beim Übersetzen. Und sobald die Übersetzungen bereit sind, können sie automatisch mit deinem Projekt synchronisiert werden. Einmal eingestellt, kannst du es vergessen und dich ganz auf deinen geliebten Code konzentrieren.

Schau dir alle Phrase-Funktionen für Entwickler an und überzeuge dich selbst, wie es deine Softwarelokalisierungs-Workflows vereinfachen kann.