Was sind lokale Übersetzungen?

Lokale Übersetzungen werden im Bundle deiner App gespeichert, statt zur Laufzeit aus 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 übernehmen, damit sie genutzt werden können.

Es gibt zwei Möglichkeiten:

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

Standardmäßig lädt gt-next Übersetzungen aus dem General Translation CDN. Wenn du deine App mit unserer API übersetzt, werden die Übersetzungen automatisch in unserem CDN gespeichert.

Trade-offs

Vorteile lokaler Übersetzungen

• Schnellere Ladezeiten: Lokale Übersetzungen werden direkt aus Ihrer App ausgeliefert und laden schneller als Übersetzungen, die über ein CDN (Content Delivery Network, Inhaltsauslieferungsnetzwerk) 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 zusammen mit Ihrer App gebündelt

Nachteile von lokalen Übersetzungen

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

Einrichtung

Schritt 1: Load-Funktion erstellen

Fügen Sie unter ./src die 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 die Datei loadTranslations.[js|ts] automatisch im src/-Verzeichnis oder im Projektstamm.

Schritt 2: CLI konfigurieren

Führen Sie den Konfigurationsbefehl aus und wählen Sie „lokale Speicherung“:

npx gtx-cli configure

Wenn Sie dazu aufgefordert werden:

• 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 Sie jetzt den Befehl translate ausführen, werden die Übersetzungen automatisch heruntergeladen und in Ihren Code integriert:

npx gtx-cli translate

Übersetzungen werden in public/_gt/ gespeichert und mit deiner App ausgeliefert.

Build-Integration

Next.js-Buildprozess

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

{
  "scripts": {
    "build": "npx gtx-cli translate && <...IHR_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 erzeugen
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`);

// ✅ Richtiger 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 das 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: