GitHub

Wörterbücher bieten einen traditionellen Ansatz, Übersetzungen in verschachtelten Objekten mit Schlüssel-Wert-Paaren zu organisieren. Obwohl <T>-Komponenten der empfohlene Ansatz sind, 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 <T>-Komponenten für neue Projekte. Wörterbücher werden in erster Linie zur Migration und zur 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>;
}

Komponentenmuster

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

Kompromisse

Vorteile des Wörterbuchs

Zentralisierte Speicherung – Alle Übersetzungen an einem Ort
Branchenstandard – Vertrautes Muster aus anderen i18n-Bibliotheken
Migrationsfreundlich – Bestehende Übersetzungen lassen sich leicht übernehmen

Nachteile des Wörterbuchs

Komplexität - Mehr Einrichtung und Konfiguration erforderlich
Wartbarkeit - Vom Einsatz getrennte Inhalte erschweren Updates
Debuggability - Übersetzungen lassen sich schwerer auf Komponenten zurückverfolgen
Lesbarkeit - Schlüssel geben den tatsächlichen Inhalt nicht wieder

Kurzstart

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 im JSON-Format:

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 Hook useTranslations 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 Einträgen im Wörterbuch mit der Syntax {variable} Variablen 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

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 gesamt: {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: 'Today' })}</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 für mehrere Sprachen

Automatische Übersetzung (empfohlen)

Die meisten Nutzer sollten loadTranslations verwenden, um Übersetzungen automatisch aus Ihrem 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;

Erstellen Sie anschließend eine Funktion loadTranslations, um die generierten Übersetzungsdateien zu laden:

src/loadTranslations.ts

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

Übergeben Sie es an Ihren <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 weitere Sprachen auf Basis Ihres Basis-Wörterbuchs. Führen Sie npx gtx-cli translate aus, um Übersetzungen für alle konfigurierten Sprachen zu erzeugen.

Manuelle Übersetzungsdateien (Migration)

Für die Migration von anderen i18n-Bibliotheken oder 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 Ihrem public/locales/-Verzeichnis:

es.json

fr.json

de.json

Wählen Sie den richtigen Ansatz: Verwenden Sie loadTranslations für neue Projekte mit automatischer Übersetzungsgenerierung oder loadDictionary beim Migrieren vorhandener Übersetzungsdateien.

Produktions-Setup

Build-Prozess

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

package.json

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

Verhalten in Entwicklung vs. Produktion

Entwicklung: Wörterbucheinträge werden bei Bedarf mit dem Dev-API-Schlüssel übersetzt
Produktion: Alle Wörterbuchübersetzungen werden 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 Zeichenketten */}
      <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 Formularfelder */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Nächste Schritte

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

Empfehlung: Verwenden Sie <T>-Komponenten für neue Projekte. Wörterbücher werden in erster Linie zur Migration und zur 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>;
}

Komponentenmuster

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

Kompromisse

Vorteile des Wörterbuchs

Zentralisierte Speicherung – Alle Übersetzungen an einem Ort
Branchenstandard – Vertrautes Muster aus anderen i18n-Bibliotheken
Migrationsfreundlich – Bestehende Übersetzungen lassen sich leicht übernehmen

Nachteile des Wörterbuchs

Komplexität - Mehr Einrichtung und Konfiguration erforderlich
Wartbarkeit - Vom Einsatz getrennte Inhalte erschweren Updates
Debuggability - Übersetzungen lassen sich schwerer auf Komponenten zurückverfolgen
Lesbarkeit - Schlüssel geben den tatsächlichen Inhalt nicht wieder

Kurzstart

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 im JSON-Format:

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 Hook useTranslations 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 Einträgen im Wörterbuch mit der Syntax {variable} Variablen 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

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 gesamt: {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: 'Today' })}</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 für mehrere Sprachen

Automatische Übersetzung (empfohlen)

Die meisten Nutzer sollten loadTranslations verwenden, um Übersetzungen automatisch aus Ihrem 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;

Erstellen Sie anschließend eine Funktion loadTranslations, um die generierten Übersetzungsdateien zu laden:

src/loadTranslations.ts

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

Übergeben Sie es an Ihren <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 Übersetzungsdateien (Migration)

Für die Migration von anderen i18n-Bibliotheken oder 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 Ihrem public/locales/-Verzeichnis:

es.json

fr.json

de.json

Produktions-Setup

Build-Prozess

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

package.json

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

Verhalten in Entwicklung vs. Produktion

Entwicklung: Wörterbucheinträge werden bei Bedarf mit dem Dev-API-Schlüssel übersetzt
Produktion: Alle Wörterbuchübersetzungen werden 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 Zeichenketten */}
      <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 Formularfelder */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Nächste Schritte

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

Empfehlung: Verwenden Sie <T>-Komponenten für neue Projekte. Wörterbücher werden in erster Linie zur Migration und zur 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>;
}

Komponentenmuster

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

Kompromisse

Vorteile des Wörterbuchs

Zentralisierte Speicherung – Alle Übersetzungen an einem Ort
Branchenstandard – Vertrautes Muster aus anderen i18n-Bibliotheken
Migrationsfreundlich – Bestehende Übersetzungen lassen sich leicht übernehmen

Nachteile des Wörterbuchs

Komplexität - Mehr Einrichtung und Konfiguration erforderlich
Wartbarkeit - Vom Einsatz getrennte Inhalte erschweren Updates
Debuggability - Übersetzungen lassen sich schwerer auf Komponenten zurückverfolgen
Lesbarkeit - Schlüssel geben den tatsächlichen Inhalt nicht wieder

Kurzstart

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 im JSON-Format:

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 Hook useTranslations 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 Einträgen im Wörterbuch mit der Syntax {variable} Variablen 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

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 gesamt: {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: 'Today' })}</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 für mehrere Sprachen

Automatische Übersetzung (empfohlen)

Die meisten Nutzer sollten loadTranslations verwenden, um Übersetzungen automatisch aus Ihrem 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;

Erstellen Sie anschließend eine Funktion loadTranslations, um die generierten Übersetzungsdateien zu laden:

src/loadTranslations.ts

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

Übergeben Sie es an Ihren <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 Übersetzungsdateien (Migration)

Für die Migration von anderen i18n-Bibliotheken oder 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 Ihrem public/locales/-Verzeichnis:

es.json

fr.json

de.json

Produktions-Setup

Build-Prozess

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

package.json

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

Verhalten in Entwicklung vs. Produktion

Entwicklung: Wörterbucheinträge werden bei Bedarf mit dem Dev-API-Schlüssel übersetzt
Produktion: Alle Wörterbuchübersetzungen werden 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 Zeichenketten */}
      <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 Formularfelder */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Nächste Schritte

Sprachleitfaden - 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

GitHubStern auf GitHub vergeben

GitHubStern auf GitHub vergeben

Stern auf GitHub vergeben

Stern auf GitHub vergeben