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
• Laden von Dictionaries für andere Sprachen
• Verwendung von Dictionaries
• Ü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.

Unser Rat

Wir empfehlen die Verwendung der <T>-Komponente aufgrund ihrer Einfachheit, besonders wenn Sie neu im Bereich 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 Next.js-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 (.ts oder .json) Datei, die alle Inhalte enthält, die Sie übersetzen möchten. Erstellen Sie das Wörterbuch in Ihrem src/ Verzeichnis.

Wenn Sie keinen src/ Ordner verwenden, können Sie das Verzeichnis des Wörterbuchs auch in der next.config.js Datei angeben.

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

const dictionary = {
  greetings: {
    goodbye: 'Goodbye, World!'
  },
}
export default dictionary;

{
  "greetings": {
    "goodbye": "Goodbye, World!"
  }
}

Schritt 2: Auf das Wörterbuch zugreifen

Es gibt verschiedene Möglichkeiten, das Wörterbuch zu verwenden, abhängig vom Kontext, in dem Sie das Wörterbuch nutzen möchten. Wenn Sie beispielsweise in einer clientseitigen Komponente sind, verwenden Sie den useDict() Hook und für serverseitige Komponenten verwenden Sie await getDict().

Hier ist ein Beispiel, wie Sie das Wörterbuch in einer clientseitigen Komponente verwenden können:

"use client";
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
 
  const d = useDict(); // auf der Clientseite verwenden Sie den useDict Hook
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Und hier ist ein Beispiel, wie Sie auf die Übersetzungen in einer serverseitigen Komponente zugreifen können:

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
 
  const d = await getDict(); // auf der Serverseite müssen Sie auf ein Promise warten
 
  return (
    <div>
      {d('greetings.hello')}
    </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-next 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: 'Hello, {name}!',
    goodbye: 'Goodbye, {name}!'
  },
}
export default dictionary;

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  const d = await getDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'World' }})}
      {d('greetings.goodbye', { variables: { name: 'World' }})}
    </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() und getDict() 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: 'Hello, World!',
      goodbye: 'Goodbye, World!'
    },
  },
}
export default dictionary;

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  // Alle Übersetzungspfade wie 'hello' werden mit 'greetings' vorangestellt
  const d = await getDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

Teilmengen mit <GTProvider>

Sie können auch ein Präfix im <GTProvider>-Komponente angeben. Dies wird eine Teilmenge des Wörterbuchs an den Client übergeben, sodass das gesamte Wörterbuch nicht geladen werden muss. Dies gilt nur für clientseitige Komponenten.

import { GTProvider } from 'gt-next';
 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                <GTProvider id="nested.dictionary.key"> // [!code highlight]
                    {children}
                </GTProvider> // [!code highlight]
            </body>
        </html>
    );
}

Sie müssen immer noch den gesamten Pfad angeben, wenn Sie einen Schlüssel im Wörterbuch referenzieren.

"use client";
 
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('nested.dictionary.key.greeting')} // [!code highlight]
    </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 Next.js-Anwendung verwenden können.
• Lernen Sie, wie Sie mit unserem Bereitstellungsleitfaden in die Produktion gehen.