Wörterbücher

Wörterbücher bieten einen klassischen Ansatz, Übersetzungen in verschachtelten Objekten mit Schlüssel-Wert-Paaren zu organisieren. Obwohl <T> components der empfohlene Ansatz sind, können Wörterbücher bei der Migration von anderen i18n-Bibliotheken oder wenn eine zentrale Ablage der Übersetzungen bevorzugt wird, hilfreich sein.

Empfehlung: Verwenden Sie für neue Projekte <T> components. Wörterbücher werden in erster Linie für Migration und Kompatibilität mit bestehenden Übersetzungs-Workflows unterstützt.

Wörterbuch vs. Komponentenübersetzung

Wörterbuchmuster

// dictionary.ts
export default {
  greetings: {
    hello: 'Hallo, Welt!',
    welcome: 'Willkommen, {name}!'
  }
};

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

Komponentenpattern

// Direkte Komponentennutzung – empfohlen
function MyComponent() {
  return <T><div>Hallo, Welt!</div></T>;
}

Kompromisse

Vorteile des Wörterbuchs

Zentrale Ablage – alle Übersetzungen an einem Ort
Branchenstandard – bekanntes Muster aus anderen i18n-Bibliotheken
Migrationsfreundlich – bestehende Übersetzungen lassen sich leicht übernehmen

Nachteile von Wörterbüchern

Komplexität - Mehr Einrichtung und Konfiguration nötig
Wartbarkeit - Vom Einsatz getrennte Inhalte erschweren Aktualisierungen
Debuggability - Übersetzungen lassen sich schwerer bis zu den Komponenten zurückverfolgen
Lesbarkeit - Schlüssel geben den tatsächlichen Inhalt nicht wieder

Schnellstart

Schritt 1: Wörterbuch erstellen

Erstellen Sie eine Wörterbuchdatei im Projektstammverzeichnis oder im Verzeichnis src:

dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Hallo, Welt!',
    welcome: 'Willkommen bei unserer App!'
  },
  navigation: {
    home: 'Startseite',
    about: 'Über uns',
    contact: 'Kontakt'
  }
};

export default dictionary;

Oder verwenden Sie das JSON‑Format:

dictionary.json

{
  "greetings": {
    "hello": "Hallo, Welt!",
    "welcome": "Willkommen in unserer App!"
  },
  "navigation": {
    "home": "Startseite",
    "about": "Über uns",
    "contact": "Kontakt"
  }
}

Die Funktion withGTConfig erkennt automatisch die Wörterbuchdatei im Projektstammverzeichnis oder im Verzeichnis src.

Schritt 2: Verwendung in Komponenten

Der Hook useTranslations ermöglicht den Zugriff auf Wörterbucheinträge:

Client-Komponenten

import { useTranslations } from 'gt-next';

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

Serverkomponenten

import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Verwendung von Variablen

Fügen Sie Wörterbucheinträgen Variablen mit der Syntax {variable} hinzu:

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Hallo, {name}!',
    itemCount: 'Sie haben {count} Artikel',
    orderTotal: 'Gesamt: ${amount}'
  }
};

function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Verwendung von Präfixen

Begrenzen Sie den Wörterbuchzugriff auf bestimmte Abschnitte mithilfe von Präfixen:

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Willkommen zurück!',
      lastLogin: 'Letzte Anmeldung: {date}'
    },
    stats: {
      totalUsers: 'Gesamtzahl der Nutzer: {count}',
      activeUsers: 'Aktive Nutzer: {count}'
    }
  }
};

function DashboardHeader() {
  // Präfix begrenzt den Zugriff auf „dashboard.header“
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Heute' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Abweichendes Präfix für den Statistikbereich
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}

Unterstützung mehrerer Sprachen

Automatische Übersetzung (empfohlen)

Die meisten Nutzer sollten loadTranslations verwenden, um Übersetzungen automatisch aus dem Basis‑Wörterbuch zu erzeugen:

dictionary.ts

const dictionary = {
  common: {
    save: 'Speichern',
    cancel: 'Abbrechen',
    delete: 'Löschen'
  },
  forms: {
    required: 'Dieses Feld ist erforderlich',
    email: 'Bitte geben Sie eine gültige E‑Mail‑Adresse ein'
  }
};

export default dictionary;

Erstelle eine loadTranslations-Funktion, um generierte Übersetzungs-files zu laden:

src/loadTranslations.ts

export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

withGTConfig erkennt automatisch die Datei loadTranslations.[js|ts] in deinem src/-Verzeichnis oder im Projektstammverzeichnis.

GT erstellt automatisch Übersetzungen für andere Sprachen auf Grundlage deines Basis‑Wörterbuchs. Führe npx gtx-cli translate aus, um Übersetzungen für alle konfigurierten Sprachen zu erzeugen.

Manuelle Übersetzungs-files (Migration)

Für die Migration von anderen i18n‑Bibliotheken oder die manuelle Übersetzungsverwaltung verwenden Sie loadDictionary:

src/loadDictionary.ts

export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

Dies lädt JSON-Übersetzungsdateien aus deinem Verzeichnis public/locales/:

es.json

fr.json

de.json

Wähle den richtigen Ansatz: Verwende loadTranslations für neue Projekte mit automatischer Übersetzungsgenerierung oder loadDictionary, wenn du bestehende Übersetzungsdateien migrierst.

Produktionsumgebung einrichten

Build-Prozess

Fügen Sie Übersetzungen zu Ihrer Build-Pipeline hinzu:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...IHR_BUILD_COMMAND...>"
  }
}

Verhalten in Entwicklung vs. Produktion

Entwicklung: Wörterbucheinträge bei Bedarf mit Dev API key übersetzt
Produktion: Alle Wörterbuchübersetzungen während des Build-Schritts vorab erstellt

Kombination mit Komponenten

Dictionaries und <T>-Komponenten lassen sich kombinieren:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Wörterbuch für einfache Zeichenfolgen */}
      <h1>{d('page.title')}</h1>
      
      {/* T-Komponente für komplexes JSX */}
      <T>
        <p>Dies ist eine <strong>komplexe Meldung</strong> mit <a href="/link">Links</a>.</p>
      </T>
      
      {/* Wörterbuch für Formularlabels */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Nächste Schritte

Sprachenleitfaden - Unterstützte Sprachen und Locale-Einstellungen konfigurieren
Leitfaden für dynamische Inhalte - Übersetzungen zur Laufzeit verarbeiten
API-Referenzen:
- useTranslations Hook
- getTranslations Function

Empfehlung: Verwenden Sie für neue Projekte <T> components. Wörterbücher werden in erster Linie für Migration und Kompatibilität mit bestehenden Übersetzungs-Workflows unterstützt.

Wörterbuch vs. Komponentenübersetzung

Wörterbuchmuster

// dictionary.ts
export default {
  greetings: {
    hello: 'Hallo, Welt!',
    welcome: 'Willkommen, {name}!'
  }
};

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

Komponentenpattern

// Direkte Komponentennutzung – empfohlen
function MyComponent() {
  return <T><div>Hallo, Welt!</div></T>;
}

Kompromisse

Vorteile des Wörterbuchs

Zentrale Ablage – alle Übersetzungen an einem Ort
Branchenstandard – bekanntes Muster aus anderen i18n-Bibliotheken
Migrationsfreundlich – bestehende Übersetzungen lassen sich leicht übernehmen

Nachteile von Wörterbüchern

Komplexität - Mehr Einrichtung und Konfiguration nötig
Wartbarkeit - Vom Einsatz getrennte Inhalte erschweren Aktualisierungen
Debuggability - Übersetzungen lassen sich schwerer bis zu den Komponenten zurückverfolgen
Lesbarkeit - Schlüssel geben den tatsächlichen Inhalt nicht wieder

Schnellstart

Schritt 1: Wörterbuch erstellen

Erstellen Sie eine Wörterbuchdatei im Projektstammverzeichnis oder im Verzeichnis src:

dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Hallo, Welt!',
    welcome: 'Willkommen bei unserer App!'
  },
  navigation: {
    home: 'Startseite',
    about: 'Über uns',
    contact: 'Kontakt'
  }
};

export default dictionary;

Oder verwenden Sie das JSON‑Format:

dictionary.json

{
  "greetings": {
    "hello": "Hallo, Welt!",
    "welcome": "Willkommen in unserer App!"
  },
  "navigation": {
    "home": "Startseite",
    "about": "Über uns",
    "contact": "Kontakt"
  }
}

Die Funktion withGTConfig erkennt automatisch die Wörterbuchdatei im Projektstammverzeichnis oder im Verzeichnis src.

Schritt 2: Verwendung in Komponenten

Der Hook useTranslations ermöglicht den Zugriff auf Wörterbucheinträge:

Client-Komponenten

import { useTranslations } from 'gt-next';

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

Serverkomponenten

import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Verwendung von Variablen

Fügen Sie Wörterbucheinträgen Variablen mit der Syntax {variable} hinzu:

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Hallo, {name}!',
    itemCount: 'Sie haben {count} Artikel',
    orderTotal: 'Gesamt: ${amount}'
  }
};

function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Verwendung von Präfixen

Begrenzen Sie den Wörterbuchzugriff auf bestimmte Abschnitte mithilfe von Präfixen:

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Willkommen zurück!',
      lastLogin: 'Letzte Anmeldung: {date}'
    },
    stats: {
      totalUsers: 'Gesamtzahl der Nutzer: {count}',
      activeUsers: 'Aktive Nutzer: {count}'
    }
  }
};

function DashboardHeader() {
  // Präfix begrenzt den Zugriff auf „dashboard.header“
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Heute' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Abweichendes Präfix für den Statistikbereich
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}

Unterstützung mehrerer Sprachen

Automatische Übersetzung (empfohlen)

Die meisten Nutzer sollten loadTranslations verwenden, um Übersetzungen automatisch aus dem Basis‑Wörterbuch zu erzeugen:

dictionary.ts

const dictionary = {
  common: {
    save: 'Speichern',
    cancel: 'Abbrechen',
    delete: 'Löschen'
  },
  forms: {
    required: 'Dieses Feld ist erforderlich',
    email: 'Bitte geben Sie eine gültige E‑Mail‑Adresse ein'
  }
};

export default dictionary;

Erstelle eine loadTranslations-Funktion, um generierte Übersetzungs-files zu laden:

src/loadTranslations.ts

export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

withGTConfig erkennt automatisch die Datei loadTranslations.[js|ts] in deinem src/-Verzeichnis oder im Projektstammverzeichnis.

Manuelle Übersetzungs-files (Migration)

Für die Migration von anderen i18n‑Bibliotheken oder die manuelle Übersetzungsverwaltung verwenden Sie loadDictionary:

src/loadDictionary.ts

export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

Dies lädt JSON-Übersetzungsdateien aus deinem Verzeichnis public/locales/:

es.json

fr.json

de.json

Wähle den richtigen Ansatz: Verwende loadTranslations für neue Projekte mit automatischer Übersetzungsgenerierung oder loadDictionary, wenn du bestehende Übersetzungsdateien migrierst.

Produktionsumgebung einrichten

Build-Prozess

Fügen Sie Übersetzungen zu Ihrer Build-Pipeline hinzu:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...IHR_BUILD_COMMAND...>"
  }
}

Verhalten in Entwicklung vs. Produktion

Entwicklung: Wörterbucheinträge bei Bedarf mit Dev API key übersetzt
Produktion: Alle Wörterbuchübersetzungen während des Build-Schritts vorab erstellt

Kombination mit Komponenten

Dictionaries und <T>-Komponenten lassen sich kombinieren:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Wörterbuch für einfache Zeichenfolgen */}
      <h1>{d('page.title')}</h1>
      
      {/* T-Komponente für komplexes JSX */}
      <T>
        <p>Dies ist eine <strong>komplexe Meldung</strong> mit <a href="/link">Links</a>.</p>
      </T>
      
      {/* Wörterbuch für Formularlabels */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Nächste Schritte

Sprachenleitfaden - Unterstützte Sprachen und Locale-Einstellungen konfigurieren
Leitfaden für dynamische Inhalte - Übersetzungen zur Laufzeit verarbeiten
API-Referenzen:
- useTranslations Hook
- getTranslations Function

Empfehlung: Verwenden Sie für neue Projekte <T> components. Wörterbücher werden in erster Linie für Migration und Kompatibilität mit bestehenden Übersetzungs-Workflows unterstützt.

Wörterbuch vs. Komponentenübersetzung

Wörterbuchmuster

// dictionary.ts
export default {
  greetings: {
    hello: 'Hallo, Welt!',
    welcome: 'Willkommen, {name}!'
  }
};

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

Komponentenpattern

// Direkte Komponentennutzung – empfohlen
function MyComponent() {
  return <T><div>Hallo, Welt!</div></T>;
}

Kompromisse

Vorteile des Wörterbuchs

Zentrale Ablage – alle Übersetzungen an einem Ort
Branchenstandard – bekanntes Muster aus anderen i18n-Bibliotheken
Migrationsfreundlich – bestehende Übersetzungen lassen sich leicht übernehmen

Nachteile von Wörterbüchern

Komplexität - Mehr Einrichtung und Konfiguration nötig
Wartbarkeit - Vom Einsatz getrennte Inhalte erschweren Aktualisierungen
Debuggability - Übersetzungen lassen sich schwerer bis zu den Komponenten zurückverfolgen
Lesbarkeit - Schlüssel geben den tatsächlichen Inhalt nicht wieder

Schnellstart

Schritt 1: Wörterbuch erstellen

Erstellen Sie eine Wörterbuchdatei im Projektstammverzeichnis oder im Verzeichnis src:

dictionary.ts

const dictionary = {
  greetings: {
    hello: 'Hallo, Welt!',
    welcome: 'Willkommen bei unserer App!'
  },
  navigation: {
    home: 'Startseite',
    about: 'Über uns',
    contact: 'Kontakt'
  }
};

export default dictionary;

Oder verwenden Sie das JSON‑Format:

dictionary.json

{
  "greetings": {
    "hello": "Hallo, Welt!",
    "welcome": "Willkommen in unserer App!"
  },
  "navigation": {
    "home": "Startseite",
    "about": "Über uns",
    "contact": "Kontakt"
  }
}

Die Funktion withGTConfig erkennt automatisch die Wörterbuchdatei im Projektstammverzeichnis oder im Verzeichnis src.

Schritt 2: Verwendung in Komponenten

Der Hook useTranslations ermöglicht den Zugriff auf Wörterbucheinträge:

Client-Komponenten

import { useTranslations } from 'gt-next';

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

Serverkomponenten

import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Verwendung von Variablen

Fügen Sie Wörterbucheinträgen Variablen mit der Syntax {variable} hinzu:

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Hallo, {name}!',
    itemCount: 'Sie haben {count} Artikel',
    orderTotal: 'Gesamt: ${amount}'
  }
};

function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Verwendung von Präfixen

Begrenzen Sie den Wörterbuchzugriff auf bestimmte Abschnitte mithilfe von Präfixen:

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Willkommen zurück!',
      lastLogin: 'Letzte Anmeldung: {date}'
    },
    stats: {
      totalUsers: 'Gesamtzahl der Nutzer: {count}',
      activeUsers: 'Aktive Nutzer: {count}'
    }
  }
};

function DashboardHeader() {
  // Präfix begrenzt den Zugriff auf „dashboard.header“
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Heute' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Abweichendes Präfix für den Statistikbereich
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}

Unterstützung mehrerer Sprachen

Automatische Übersetzung (empfohlen)

Die meisten Nutzer sollten loadTranslations verwenden, um Übersetzungen automatisch aus dem Basis‑Wörterbuch zu erzeugen:

dictionary.ts

const dictionary = {
  common: {
    save: 'Speichern',
    cancel: 'Abbrechen',
    delete: 'Löschen'
  },
  forms: {
    required: 'Dieses Feld ist erforderlich',
    email: 'Bitte geben Sie eine gültige E‑Mail‑Adresse ein'
  }
};

export default dictionary;

Erstelle eine loadTranslations-Funktion, um generierte Übersetzungs-files zu laden:

src/loadTranslations.ts

export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

withGTConfig erkennt automatisch die Datei loadTranslations.[js|ts] in deinem src/-Verzeichnis oder im Projektstammverzeichnis.

Manuelle Übersetzungs-files (Migration)

Für die Migration von anderen i18n‑Bibliotheken oder die manuelle Übersetzungsverwaltung verwenden Sie loadDictionary:

src/loadDictionary.ts

export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

Dies lädt JSON-Übersetzungsdateien aus deinem Verzeichnis public/locales/:

es.json

fr.json

de.json

Wähle den richtigen Ansatz: Verwende loadTranslations für neue Projekte mit automatischer Übersetzungsgenerierung oder loadDictionary, wenn du bestehende Übersetzungsdateien migrierst.

Produktionsumgebung einrichten

Build-Prozess

Fügen Sie Übersetzungen zu Ihrer Build-Pipeline hinzu:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...IHR_BUILD_COMMAND...>"
  }
}

Verhalten in Entwicklung vs. Produktion

Entwicklung: Wörterbucheinträge bei Bedarf mit Dev API key übersetzt
Produktion: Alle Wörterbuchübersetzungen während des Build-Schritts vorab erstellt

Kombination mit Komponenten

Dictionaries und <T>-Komponenten lassen sich kombinieren:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Wörterbuch für einfache Zeichenfolgen */}
      <h1>{d('page.title')}</h1>
      
      {/* T-Komponente für komplexes JSX */}
      <T>
        <p>Dies ist eine <strong>komplexe Meldung</strong> mit <a href="/link">Links</a>.</p>
      </T>
      
      {/* Wörterbuch für Formularlabels */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Nächste Schritte

Sprachenleitfaden - Unterstützte Sprachen und Locale-Einstellungen konfigurieren
Leitfaden für dynamische Inhalte - Übersetzungen zur Laufzeit verarbeiten
API-Referenzen:
- useTranslations Hook
- getTranslations Function

Wörterbücher

Auf dieser Seite

Wörterbücher

Auf dieser Seite

Wörterbücher

Auf dieser Seite

GitHubAuf GitHub mit Stern markieren

GitHubAuf GitHub mit Stern markieren

Auf GitHub mit Stern markieren

Auf GitHub mit Stern markieren