Wörterbücher Referenz

Überblick

In diesem Referenzleitfaden stellen wir Ihnen das Dictionary-Muster vor. Bitte zögern Sie nicht, auf dieser Seite nach Bedarf zu navigieren. Wir werden Folgendes behandeln:

• Was ist ein Dictionary?
• Wie man Dictionaries verwendet
• Dictionaries für andere Sprachen laden
• Dictionaries verwenden
• Überlegungen für den Produktionseinsatz

Was ist ein Wörterbuch?

General Translation ermöglicht es, übersetzbare Inhalte in einer Wörterbuchdatei zu speichern. Ein Wörterbuch ist ein verschachteltes Objekt mit String-Werten, das zur Speicherung übersetzbarer Inhalte verwendet werden kann. Diese Wörterbuchdatei (.ts, .js oder .json) wird dann zur Generierung einer Übersetzung verwendet.

Wörterbücher können eigenständig oder in Verbindung mit <T>-Komponenten verwendet werden.

Wörterbuch vs. <T>-Komponenten

Das Wörterbuchmuster hat einige Vorteile gegenüber der <T>-Komponente:

1. Zentralisierte Speicherung: Wörterbücher speichern alle übersetzbaren Inhalte in einer einzigen Datei, was die Verwaltung und Aktualisierung erleichtert.
2. Historischer Präzedenzfall: Das Wörterbuchmuster ist ein gängiges Entwurfsmuster in der Branche und wird von vielen anderen Bibliotheken verwendet.

Gleichzeitig hat es auch einige 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 das Debuggen und die Wartung von Übersetzungen viel schwieriger.

Beide Entwurfsmuster 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, besonders wenn Sie neu in der Internationalisierung (i18n) sind. Wir bieten Wörterbuchunterstützung für diejenigen an, die dieses Entwurfsmuster aus früheren Erfahrungen bevorzugen oder für eine einfachere Integration in bestehende Codebasen.

Wie man Wörterbücher verwendet

In diesem Abschnitt zeigen wir Ihnen, wie Sie eine einfache Wörterbuch-Implementierung in Ihrer React-Anwendung einrichten können. 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 (.json)-Datei, die alle Inhalte enthält, die Sie übersetzen möchten.

Fügen Sie den folgenden Inhalt zu Ihrer dictionary.js-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";
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);

Schritt 2: Auf das Wörterbuch verweisen

Sie können auf Wörterbucheinträge mit dem useDict()-Hook zugreifen. Verwenden Sie einfach die d()-Funktion, um auf die Wörterbucheinträge über deren Bezeichner zuzugreifen.

import { useDict } from 'gt-react';
 
export default function MyComponent() {
 
  const d = useDict(); 
 
  return (
    <div>
      {d('greetings.hello')} // [!code highlight]
    </div>
  );
}

Laden von Wörterbüchern für andere Sprachen

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 Funktion loadTranslations.

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 Funktion loadDictionary übergeben.

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

Weitere Informationen finden Sie in der API-Referenz.

Verwendung von Wörterbüchern

Variablen

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

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

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  const d = useDict();
 
  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 Typ DictionaryTranslationOptions.

Präfixe

Zusätzlich können Sie mit useDict() ein Präfix an die Funktion übergeben, um einen gemeinsamen Pfad im Wörterbuch anzugeben. 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: 'Hallo, Welt!',
      goodbye: 'Auf Wiedersehen, Welt!'
    },
  },
}
export default dictionary;

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  // Alle Übersetzungspfade wie 'hello' werden mit 'greetings' vorangestellt
  const d = useDict('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 Übersetzungsbefehl ausführen, bevor Sie in die Produktion bereitstellen, damit alle Übersetzungen zur Laufzeit verfügbar sind. Wir empfehlen, ihn in Ihre CD-Pipeline oder als Teil Ihres Build-Skripts aufzunehmen.

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

Das war's! Sie haben Ihre Anwendung erfolgreich ins Französische, Spanische und Japanische übersetzt.

Für eine detailliertere Anleitung zur Bereitstellung Ihrer Anwendung lesen Sie bitte den Bereitstellungsleitfaden. Für weitere Informationen zum Befehl lesen Sie bitte die CLI-Tool Referenzanleitung.

Verhalten: Entwicklung vs Produktion

In der Entwicklung wird die d() Funktion Wörterbucheinträge bei Bedarf übersetzen. Das bedeutet, dass beim Rendern der Komponente sofort eine Übersetzung durchgeführt wird. Wir tun dies aus Bequemlichkeit, um die Entwicklung mit anderen Sprachen zu erleichtern.

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

In der Produktion wird die d() Funktion Inhalte zur Build-Zeit übersetzen. Das bedeutet, dass Sie den Übersetzungsbefehl ausführen müssen, bevor Sie Ihre Anwendung bereitstellen.

Notizen

• Wörterbücher sind eine Alternative zur <T> Komponente. Sie können in Verbindung 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 integrieren.
• 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 unserem Bereitstellungsleitfaden in die Produktion gehen.