Was sind lokale Übersetzungen?

Lokale Übersetzungen werden im Bundle Ihrer App gespeichert, statt zur Laufzeit aus einem CDN (Content Delivery Network) geladen 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, damit sie verwendet werden können.

Es gibt zwei Möglichkeiten:

1. Im Bundle Ihrer App (lokal): Speichern Sie die Übersetzungen nach der Generierung im Bundle Ihrer App
2. In einem CDN (Standard): Laden Sie die Übersetzungen zur Laufzeit aus einem CDN

Standardmäßig lädt gt-react Übersetzungen aus dem General Translation CDN. Wenn Sie Ihre App über unsere API übersetzen, werden die Ü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 über ein 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
• Offline nutzbar: Übersetzungen werden mit Ihrer App gebündelt

Nachteile von lokalen Übersetzungen

• Größere Bundle-Größe: Lokale Übersetzungen vergrößern die Bundle-Größe 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 erneut bereitstellen

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 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 lokalen Speicher:

npx gtx-cli configure

Bei der Eingabeaufforderung:

• In CDN speichern? Wähle „No“
• Übersetzungsverzeichnis: Die CLI verwendet automatisch ./src/_gt

Alternativ kannst du die Datei gt.config.json manuell so konfigurieren, dass lokale Übersetzungen verwendet werden. Weitere Informationen findest du in der CLI-Konfigurationsdokumentation.

Schritt 4: Übersetzungen erzeugen

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

npx gtx-cli translate

Übersetzungen werden in src/_gt/ gespeichert und mit Ihrer App ausgeliefert.

Build-Integration

React-Build-Prozess

Fügen Sie die Übersetzungsgenerierung zu Ihrem Build-Skript 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 generiert werden:

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

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

Fehler bei Importpfaden

Stimme die Verzeichnisstruktur in der load-Funktion ab:

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

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

Große Bundle-Größ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(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Nächste Schritte

• Sprachleitfaden – Unterstützte Sprachen konfigurieren