Was sind lokale Übersetzungen?

Lokale Übersetzungen werden im Bundle Ihrer App gespeichert, statt zur Laufzeit aus einem CDN (Content Delivery Network) abgerufen zu werden. Wenn Sie den Befehl gtx-cli translate in Ihren Build-Prozess integrieren, werden Übersetzungen im JSON-Format erzeugt. Der letzte Schritt besteht darin, diese Übersetzungen in Ihre App zu bringen, wo sie verwendet werden können.

Es gibt zwei Möglichkeiten:

1. Im Bundle Ihrer App (lokal): Übersetzungen nach der Generierung im App-Bundle speichern
2. In einem CDN (Standard): Übersetzungen zur Laufzeit aus einem CDN abrufen

Standardmäßig ruft gt-react Übersetzungen aus dem General Translation CDN ab. Wenn Sie Ihre App über unsere API übersetzen, werden die Übersetzungen automatisch in unserem CDN gespeichert.

Trade-offs

Vorteile lokaler Übersetzungen

• Schnellere Ladezeiten: Lokale Übersetzungen werden direkt aus Ihrer App bereitgestellt und laden schneller als Übersetzungen, die über ein CDN (Content Delivery Network) ausgeliefert werden
• Keine Abhängigkeit von externen Diensten: Die Fähigkeit Ihrer App, Übersetzungen zu laden, hängt nicht von der Verfügbarkeit des CDNs ab. Wenn für eine Locale keine Übersetzungen gefunden werden, fällt die App automatisch auf die Standardsprache zurück
• Funktioniert offline: Übersetzungen werden mit Ihrer App gebündelt

Nachteile lokaler Übersetzungen

• Größere Bundlegröße: Lokale Übersetzungen erhöhen die Bundlegröße deiner App und können das anfängliche Laden verlangsamen
• Content-Management: Um eine Übersetzung zu ändern, musst du deine App bei jeder Änderung mit der neuen Übersetzung erneut deployen

Setup

Schritt 1: Ladefunktion erstellen

Fügen Sie unter ./src eine Datei loadTranslations.[js|ts] mit folgendem Inhalt hinzu:

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

Schritt 2: GTProvider konfigurieren

Übergeben Sie loadTranslations als Prop an die Komponente <GTProvider>:

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

Schritt 3: CLI konfigurieren

Führen Sie den Konfigurationsbefehl aus und wählen Sie den lokalen Speicher aus:

npx gtx-cli konfigurieren

When prompted:

• In CDN speichern? Wähle „Nein“
• Übersetzungsverzeichnis: Die CLI (Kommandozeilenoberfläche) verwendet automatisch ./src/_gt

Alternativ kannst du die Datei gt.config.json manuell so konfigurieren, dass lokale Übersetzungen (local translations) verwendet werden. Siehe die CLI‑Konfigurationsdokumentation für weitere Informationen.

Schritt 4: Übersetzungen generieren

Wenn Sie jetzt den Befehl translate ausführen, werden die Übersetzungen automatisch heruntergeladen und in Ihren Code aufgenommen:

npx gtx-cli translate

Übersetzungen werden in src/_gt/ gespeichert und mit deiner App gebündelt.

Build-Integration

React-Build-Prozess

Fügen Sie Ihrem Build-Skript die Übersetzungsgenerierung hinzu:

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

CI/CD-Pipeline

# .github/workflows/deploy.yml
- name: Übersetzungen generieren
  run: npx gtx-cli translate
  
- name: Anwendung erstellen  
  run: npm run build

Häufige Probleme

Fehlende Übersetzungs-files

Stellen Sie sicher, dass die Übersetzungen vor dem Build generiert werden:

# ❌ Build ohne Übersetzungen
<...YOUR_BUILD_COMMAND...>

# ✅ Übersetzungen zuerst generieren
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

Fehler bei Importpfaden

Spiegeln Sie Ihre Verzeichnisstruktur in der load-Funktion wider:

// ❌ Falscher Pfad
const t = await import(`../translations/${locale}.json`);

// ✅ Korrigierter Pfad für src/_gt
const t = await import(`./_gt/${locale}.json`);

Große Bundlegröße

Erwägen Sie Code-Splitting für Apps mit vielen Sprachen:

// Übersetzungen nur bei Bedarf laden
export default async function loadTranslations(locale: string) {
  // Nur laden, wenn das Locale aktiv ist
  if (locale === getCurrentLocale()) {
    const translations = await import(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Nächste Schritte

• Sprachleitfaden – Unterstützte Sprachen konfigurieren