Wörterbücher

Übersicht

In diesem Leitfaden stellen wir Ihnen Wörterbücher vor. Sie können gerne nach Bedarf auf dieser Seite hin und her springen. Wir behandeln die folgenden Themen:

Was ist ein Wörterbuch?

Ein Wörterbuch ist ein verschachteltes Objekt mit Zeichenfolgenwerten, das verwendet werden kann, um übersetzbare Inhalte zu speichern. Sie können in einer .ts-, .js- oder .json-Datei gespeichert werden.

gt-react ermöglicht es Ihnen, Wörterbücher eigenständig oder in Verbindung mit <T>-Komponenten zu verwenden.

Wörterbuch vs <T>-Komponenten

Das Wörterbuch-Muster bietet einige Vorteile gegenüber der <T>-Komponente:

1. Zentralisierte Speicherung: Wörterbücher speichern alle übersetzbaren Inhalte in einer einzigen Datei.
2. Historischer Präzedenzfall: Das Wörterbuch-Muster ist ein gängiges Designmuster in der Branche und wird von vielen anderen i18n-Bibliotheken verwendet.

Gleichzeitig hat es mehrere wesentliche Nachteile:

1. Komplexität: Wörterbücher sind komplexer einzurichten und zu verwenden als die <T>-Komponente.
2. Lesbarkeit: Wörterbücher sind weniger lesbar als die <T>-Komponente, da der Inhalt nicht inline ist.
3. Wartbarkeit: Wörterbücher sind schwieriger zu warten als die <T>-Komponente, da der Inhalt nicht inline ist, sondern separat gespeichert wird. Dies macht die Pflege und Aktualisierung von Übersetzungen deutlich schwieriger.
4. Fehlerbehebung: Aus demselben Grund sind Wörterbücher schwieriger zu debuggen als die <T>-Komponente. Wenn Sie versuchen, eine React-Komponente zu debuggen, müssen Sie herausfinden, wo der Inhalt im Wörterbuch verwendet wird, anstatt einfach direkt in Ihrem Code nach dem Inhalt zu suchen.

Beide Designmuster werden von unserer Bibliothek unterstützt und schließen sich nicht gegenseitig aus. Sie können ein Wörterbuch zusammen mit <T>-Komponenten verwenden.

Unsere Empfehlung

Wir empfehlen die Verwendung der <T>-Komponente aufgrund ihrer Einfachheit, insbesondere wenn Sie neu im Bereich Internationalisierung (i18n) sind. Wir bieten Wörterbuch-Unterstützung für diejenigen an, die dieses Designmuster aus früheren Erfahrungen bevorzugen oder um die Integration in bestehende Codebasen zu erleichtern.

Wie man Wörterbücher verwendet

In diesem Abschnitt zeigen wir Ihnen, wie Sie eine grundlegende Wörterbuch-Implementierung in Ihrer React-Anwendung einrichten. Wir werden die folgenden Schritte durchgehen:

Schritt 1: Ein Wörterbuch erstellen

Der erste Schritt ist die Erstellung eines Wörterbuchs. Dies ist eine dictionary.[js|ts|json] Datei, die alle Inhalte enthält, die Sie übersetzen möchten.

Fügen Sie den folgenden Inhalt zu Ihrer dictionary Datei hinzu:

const dictionary = {
  greetings: {
    hello: 'Hello, world!'
  },
}

export default dictionary;

{
  "greetings": {
    "hello": "Hello, world!"
  }
}

Dann übergeben Sie es an Ihre <GTProvider> Komponente:

import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

Schritt 2: Das Wörterbuch referenzieren

Sie können auf Wörterbucheinträge mit dem useTranslations() Hook zugreifen. Verwenden Sie einfach die vom Hook zurückgegebene Funktion, um über den Schlüssel auf die Wörterbucheinträge zuzugreifen.

import { useTranslations } from 'gt-react';

export default function MyComponent() {
  const d = useTranslations();
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Wörterbücher für andere Sprachen laden

Standardmäßig stellen Entwickler nur ein Wörterbuch für die Standardsprache bereit.

General Translation generiert automatisch Wörterbücher für andere Sprachen und lädt sie mit der loadTranslations Funktion.

Wenn Sie jedoch von einer anderen i18n-Bibliothek migrieren oder bereits Wörterbücher für andere Sprachen haben, können Sie diese an die loadDictionary Funktion übergeben.

gt-react lädt automatisch das entsprechende Wörterbuch für die angeforderte Locale, wenn Sie den useTranslations() Hook oder die getDict() Funktion verwenden.

Weitere Informationen finden Sie in der API-Referenz.

Wörterbücher verwenden

Variablen

Sie können Variablen zu Ihrem Wörterbuch hinzufügen, indem Sie die {variable} Syntax verwenden:

const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',    // -> Hello, Alice!
    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
  },
}
export default dictionary;

import { useTranslations } from 'gt-react';

export default async function MyComponent() {
  const d = useTranslations();
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'Alice' }})}
      {d('greetings.goodbye', { variables: { name: 'Bob' }})}
    </div>
  );
}

Lesen Sie mehr über das Hinzufügen von Variablen zu Ihrem Wörterbuch im DictionaryTranslationOptions Typ.

Präfixe

Zusätzlich können Sie mit useTranslations() ein Präfix an die Funktion übergeben, um einen gemeinsamen Pfad im Wörterbuch zu spezifizieren. Dies ist nützlich, wenn Sie einen gemeinsamen Pfad in Ihrem Wörterbuch haben, den Sie in mehreren Komponenten verwenden möchten.

const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, world!',
      goodbye: 'Goodbye, world!'
    },
  },
}
export default dictionary;

import { useTranslations } from 'gt-react';

export default async function MyComponent() {
  // Alle Übersetzungspfade wie 'hello' werden mit 'greetings.common.' vorangestellt
  const d = useTranslations('greetings.common'); 

  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

Produktionsüberlegungen

Bereitstellung in der Produktion

Stellen Sie sicher, dass Sie den translate-Befehl vor der Bereitstellung in der Produktion ausführen, damit alle Übersetzungen zur Laufzeit verfügbar sind. Wir empfehlen, ihn zu Ihrer CD-Pipeline hinzuzufügen oder als Teil Ihres Build-Skripts zu verwenden.

{
  "scripts": {
    "build": "npx gtx-cli translate && <YOUR_BUILD_COMMAND>",
  }
}

Für eine detailliertere Anleitung zur Bereitstellung Ihrer Anwendung lesen Sie bitte den Deployment Leitfaden. Für weitere Informationen zum Befehl lesen Sie bitte den CLI Tool Referenzleitfaden.

Verhalten: Entwicklung vs. Produktion

In der Entwicklung übersetzt die von dem useTranslations() Hook zurückgegebene Funktion Wörterbucheinträge bei Bedarf. Das bedeutet, dass beim Rendern der Komponente sofort eine Übersetzung durchgeführt wird. Wir tun dies der Bequemlichkeit halber, um die Entwicklung mit anderen Sprachen zu erleichtern.

Um dieses Verhalten zu aktivieren, fügen Sie einfach einen Dev API key zu Ihrer Umgebung hinzu.

In der Produktion übersetzt die d() Funktion Inhalte zur Build-Zeit. Das bedeutet, dass Sie den Übersetzungsbefehl vor der Bereitstellung Ihrer Anwendung ausführen müssen.

Hinweise

• Wörterbücher sind eine Alternative zur <T> Komponente. Sie können zusammen mit <T> Komponenten oder eigenständig verwendet werden.
• Wörterbuchübersetzungen erfolgen zur Build-Zeit, daher müssen Sie den translate Befehl in Ihren Build-Prozess aufnehmen.
• Wörterbücher können mit Präfixen verwendet werden, um einen Teil des Wörterbuchs anzugeben.

Nächste Schritte

• Erfahren Sie mehr über die <T> Komponente und wie Sie sie in Ihrer React-Anwendung verwenden können.
• Lernen Sie, wie Sie mit unserer Bereitstellungsanleitung in die Produktion gehen.