Wörterbücher

Wörterbücher bieten einen klassischen Ansatz, Übersetzungen in verschachtelten Objekten mit Schlüssel‑Wert‑Paaren zu organisieren. Zwar sind <T>‑Komponenten der empfohlene Ansatz, doch können Wörterbücher bei der Migration von anderen i18n‑Bibliotheken hilfreich sein oder wenn Sie eine zentrale Ablage für Übersetzungen bevorzugen.

Empfehlung: Verwenden Sie für neue Projekte <T>‑Komponenten. 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örterbuch-Pattern

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

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

Komponenten-Pattern

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

Kompromisse

Vorteile des Wörterbuchs

Zentralisierte Ablage – alle Übersetzungen an einem Ort
Industriestandard – vertrautes Muster aus anderen i18n‑Bibliotheken
Einfach zu migrieren – 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 in unserer App!'
  },
  navigation: {
    home: 'Startseite',
    about: 'Über uns',
    contact: 'Kontakt'
  }
};

export default dictionary;

Oder das JSON-Format verwenden:

dictionary.json

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

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

index.js

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: Verwendung in Komponenten

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

import { useTranslations } from 'gt-react';

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

Verwendung von Variablen

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

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Hallo, {name}!',
    itemCount: 'Sie haben {count} Artikel',
    orderTotal: 'Summe: ${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

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Willkommen zurück!',
      lastLogin: 'Letzter Login: {date}'
    },
    stats: {
      totalUsers: 'Benutzer insgesamt: {count}',
      activeUsers: 'Aktive Benutzer: {count}'
    }
  }
};

function DashboardHeader() {
  // Präfix beschränkt 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() {
  // Anderes 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 Ihrem Basiswörterbuch zu generieren:

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 anschließend eine Funktion loadTranslations, um die generierten Übersetzungs-files zu laden:

src/loadTranslations.ts

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

Übergebe es an deinen <GTProvider>:

src/index.tsx

import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

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

GT erstellt automatisch Übersetzungen für andere Sprachen auf Basis Ihres Basis-Wörterbuchs. Führen Sie npx gtx-cli translate aus, um Übersetzungen für alle konfigurierten Sprachen zu erstellen.

Manuelle Übersetzungs-files (Migration)

Für die Migration von anderen i18n-Bibliotheken oder für die manuelle Verwaltung von Übersetzungen 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

Den richtigen Ansatz wählen: Verwende loadTranslations für neue Projekte mit automatischer Generierung von Übersetzungen oder loadDictionary, wenn du bestehende Übersetzungsdateien migrierst.

Produktionssetup

Build-Prozess

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

package.json

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

Verhalten in Entwicklung vs. Produktion

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

Kombination mit Komponenten

Dictionaries und <T>-Komponenten können zusammenarbeiten:

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

Nächste Schritte

Sprachenleitfaden - Unterstützte Sprachen und Locale-Einstellungen konfigurieren
Leitfaden für dynamische Inhalte - Übersetzungsanforderungen zur Laufzeit erfüllen
API-Referenzen:
- useTranslations Hook

Empfehlung: Verwenden Sie für neue Projekte <T>‑Komponenten. 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örterbuch-Pattern

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

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

Komponenten-Pattern

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

Kompromisse

Vorteile des Wörterbuchs

Zentralisierte Ablage – alle Übersetzungen an einem Ort
Industriestandard – vertrautes Muster aus anderen i18n‑Bibliotheken
Einfach zu migrieren – 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 in unserer App!'
  },
  navigation: {
    home: 'Startseite',
    about: 'Über uns',
    contact: 'Kontakt'
  }
};

export default dictionary;

Oder das JSON-Format verwenden:

dictionary.json

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

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

index.js

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: Verwendung in Komponenten

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

import { useTranslations } from 'gt-react';

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

Verwendung von Variablen

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

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Hallo, {name}!',
    itemCount: 'Sie haben {count} Artikel',
    orderTotal: 'Summe: ${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

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Willkommen zurück!',
      lastLogin: 'Letzter Login: {date}'
    },
    stats: {
      totalUsers: 'Benutzer insgesamt: {count}',
      activeUsers: 'Aktive Benutzer: {count}'
    }
  }
};

function DashboardHeader() {
  // Präfix beschränkt 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() {
  // Anderes 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 Ihrem Basiswörterbuch zu generieren:

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 anschließend eine Funktion loadTranslations, um die generierten Übersetzungs-files zu laden:

src/loadTranslations.ts

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

Übergebe es an deinen <GTProvider>:

src/index.tsx

import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

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

Manuelle Übersetzungs-files (Migration)

Für die Migration von anderen i18n-Bibliotheken oder für die manuelle Verwaltung von Übersetzungen 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

Produktionssetup

Build-Prozess

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

package.json

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

Verhalten in Entwicklung vs. Produktion

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

Kombination mit Komponenten

Dictionaries und <T>-Komponenten können zusammenarbeiten:

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

Nächste Schritte

Sprachenleitfaden - Unterstützte Sprachen und Locale-Einstellungen konfigurieren
Leitfaden für dynamische Inhalte - Übersetzungsanforderungen zur Laufzeit erfüllen
API-Referenzen:
- useTranslations Hook

Empfehlung: Verwenden Sie für neue Projekte <T>‑Komponenten. 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örterbuch-Pattern

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

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

Komponenten-Pattern

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

Kompromisse

Vorteile des Wörterbuchs

Zentralisierte Ablage – alle Übersetzungen an einem Ort
Industriestandard – vertrautes Muster aus anderen i18n‑Bibliotheken
Einfach zu migrieren – 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 in unserer App!'
  },
  navigation: {
    home: 'Startseite',
    about: 'Über uns',
    contact: 'Kontakt'
  }
};

export default dictionary;

Oder das JSON-Format verwenden:

dictionary.json

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

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

index.js

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: Verwendung in Komponenten

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

import { useTranslations } from 'gt-react';

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

Verwendung von Variablen

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

dictionary.ts

const dictionary = {
  user: {
    greeting: 'Hallo, {name}!',
    itemCount: 'Sie haben {count} Artikel',
    orderTotal: 'Summe: ${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

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: 'Willkommen zurück!',
      lastLogin: 'Letzter Login: {date}'
    },
    stats: {
      totalUsers: 'Benutzer insgesamt: {count}',
      activeUsers: 'Aktive Benutzer: {count}'
    }
  }
};

function DashboardHeader() {
  // Präfix beschränkt 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() {
  // Anderes 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 Ihrem Basiswörterbuch zu generieren:

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 anschließend eine Funktion loadTranslations, um die generierten Übersetzungs-files zu laden:

src/loadTranslations.ts

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

Übergebe es an deinen <GTProvider>:

src/index.tsx

import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

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

Manuelle Übersetzungs-files (Migration)

Für die Migration von anderen i18n-Bibliotheken oder für die manuelle Verwaltung von Übersetzungen 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

Produktionssetup

Build-Prozess

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

package.json

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

Verhalten in Entwicklung vs. Produktion

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

Kombination mit Komponenten

Dictionaries und <T>-Komponenten können zusammenarbeiten:

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

Nächste Schritte

Sprachenleitfaden - Unterstützte Sprachen und Locale-Einstellungen konfigurieren
Leitfaden für dynamische Inhalte - Übersetzungsanforderungen zur Laufzeit erfüllen
API-Referenzen:
- useTranslations Hook

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