Was sind lokale Übersetzungen?

Lokale Übersetzungen werden im Bundle deiner App gespeichert, statt von einem CDN (Content Delivery Network) geladen zu werden. Wenn du den Befehl gtx-cli translate in deinen Build-Prozess integrierst, werden Übersetzungen im JSON-Format erzeugt. Der letzte Schritt besteht darin, diese Übersetzungen in deine App zu bringen, damit sie verwendet werden können.

Es gibt zwei Möglichkeiten:

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

Standardmäßig lädt gt-next Übersetzungen vom General Translation CDN. Wenn du deine App über unsere API übersetzt, werden Übersetzungen automatisch in unserem CDN gespeichert.

Kompromisse

Vorteile lokaler Übersetzungen

• Schnellere Ladezeiten: Lokale Übersetzungen werden direkt aus Ihrer App ausgeliefert und laden schneller als Übersetzungen, die von einem CDN (Content Delivery Network) bereitgestellt werden
• Keine Abhängigkeit von externen Diensten: Die Fähigkeit Ihrer App, Übersetzungen zu laden, hängt nicht von der Verfügbarkeit des CDN 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 von local translations

• Größeres Bundle: Local translations vergrößern das Bundle Ihrer App und können das anfängliche Laden verlangsamen
• Content-Management: Um eine Übersetzung zu bearbeiten, müssen Sie Ihre App bei jeder Änderung mit der neuen Übersetzung erneut deployen

Einrichtung

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 translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

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

Schritt 2: CLI konfigurieren

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

npx gtx-cli configure

Bei der Aufforderung:

• In CDN speichern? Wählen Sie „Nein“
• Übersetzungsverzeichnis: Geben Sie ./public/_gt ein

Alternativ können Sie die Datei gt.config.json manuell so konfigurieren, dass lokale Übersetzungen verwendet werden. Weitere Informationen finden Sie in der CLI-Konfigurationsdokumentation.

Schritt 3: Übersetzungen generieren

Wenn du jetzt den Befehl translate ausführst, werden die Übersetzungen automatisch heruntergeladen und in deinen Code integriert:

npx gtx-cli translate

Übersetzungen werden in public/_gt/ gespeichert und mit Ihrer App gebündelt.

Build-Integration

Next.js-Buildprozess

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

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

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 Übersetzungsdateien

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

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

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

Importpfadfehler

Stimmen Sie die Verzeichnisstruktur in der load-Funktion ab:

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

// ✅ Korrekter Pfad für public/_gt
const t = await import(`../public/_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 locale aktiv ist
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Nächste Schritte

• Middleware Guide - Spracherkennung und Routing
• Languages Guide - Unterstützte Sprachen konfigurieren
• API Reference: