So übersetzen Sie i18next JSON-Dateien in React & Next.js (2026)

Sie haben gerade eine React-App fertiggestellt, die bis nächsten Freitag in 12 Sprachen ausgeliefert werden muss. Ihre Lokalisierungsdateien befinden sich unter public/locales/en/common.json, Sie haben 340 Schlüssel pro Gebietsschema, und die Token in Ihren Zeichenfolgen sehen aus wie {{userName}} und {{count}}, verstreut über verschachtelte Objekte. Sie fügen das JSON in ChatGPT ein, und es kommt mit {{ nombreUsuario }}, zusätzlichen Leerzeichen und der Hälfte der umbenannten Pluralisierungsschlüssel zurück. Ihre App stürzt beim Build ab.

Wenn Sie versucht haben, die i18next JSON-Übersetzung zu automatisieren, kennen Sie diesen Schmerz. Das JSON-Format ist flexibel, weshalb die meisten Übersetzungstools es verstümmeln. Das eigentliche Problem ist nicht die Qualität des Sprachmodells – es ist, dass KI-Tools für Endverbraucher die strukturellen Regeln von i18next nicht verstehen.

Dieser Leitfaden erklärt, was i18next JSON von anderen Lokalisierungsformaten unterscheidet, warum naive Übersetzungsansätze React- und Next.js-Anwendungen zum Absturz bringen und wie man die Übersetzung sicher über Dutzende von Gebietsschemata hinweg automatisiert, ohne jeden Schlüssel manuell überprüfen zu müssen.

Was ist i18next JSON und warum die Übersetzung knifflig ist

i18next ist die am weitesten verbreitete i18n-Bibliothek im JavaScript-Ökosystem. Sie treibt React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue und Node-Backend-Dienste an. Sie speichert übersetzbare Zeichenfolgen in flachen oder verschachtelten JSON-Dateien, eine pro Gebietsschema.

Eine typische Datei sieht so aus:

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

Das sieht einfach aus, aber drei Dinge machen die Übersetzung mit generischer KI gefährlich.

Interpolations-Token sind strukturell, nicht Text

Die Sequenz {{userName}} ist kein Wort – es ist ein Platzhalter, den die Laufzeit durch Daten ersetzt. Fügen Sie ein Leerzeichen hinzu ({{ userName }}), benennen Sie es um oder übersetzen Sie den inneren Bezeichner, und die Laufzeit schlägt entweder stillschweigend fehl oder wirft einen Fehler. Manche Übersetzer wandeln {{count}} freundlicherweise in {{conteo}} im Spanischen um. Ihre App versucht nun, eine Variable zu interpolieren, die nicht existiert, und rendert den rohen Platzhalter für Ihren Benutzer.

Pluralisierungsschlüssel sind magische Suffixe

i18next erkennt Pluralformen anhand von Suffixen: _zero, _one, _two, _few, _many, _other. Dies sind keine beliebigen Zeichenfolgen – sie müssen den CLDR-Pluralkategorien für das Zielgebietsschema entsprechen. Englisch verwendet nur _one und _other. Russisch, Arabisch und Polnisch verwenden bis zu sechs Kategorien. Wenn Ihr Übersetzer _other weglässt oder umbenennt, bricht die Fallback-Kette.

Verschachtelte Schlüssel müssen intakt bleiben

Im Gegensatz zu Gettext .po-Dateien, die flache Schlüssel-Wert-Paare sind, können i18next-Dateien beliebig verschachtelt sein. Ein fauler Übersetzer könnte die Struktur abflachen, Schlüsselnamen an den übersetzten Text anpassen oder Objekte neu anordnen. Ihr t('cart.items_other')-Aufruf im Code wird dann nicht mehr aufgelöst.

Schlechte Lösungen, die Entwickler zuerst ausprobieren

Jedes Team durchläuft denselben dreistufigen Fehlerzyklus, bevor es in eine echte Lösung investiert.

Phase Eins: In ChatGPT einfügen

Sie kopieren 200 Schlüssel in ChatGPT, fragen „Übersetzen Sie dieses JSON ins Spanische“ und fügen das Ergebnis zurück ein. Es funktioniert für 180 Schlüssel. Zwanzig haben Leerzeichen innerhalb von {{...}} hinzugefügt, drei haben Plural-Suffixe neu geschrieben, und ein <strong>-Tag wurde in <fuerte> übersetzt. Ihr Build schlägt entweder fehl oder liefert stillschweigend fehlerhafte Zeichenfolgen in die Produktion aus.

Phase Zwei: Google Translate API

Sie binden die Google Translate REST API ein, iterieren über Ihr JSON und senden jeden Wert. Die Geschwindigkeit ist großartig. Die Qualität nicht. Googles API behandelt jede Zeichenfolge isoliert – kein Kontext zu Ihrer App, kein Verständnis, dass {{count}} ein Platzhalter ist, kein Bewusstsein, dass der Schlüssel cart.empty sich von cart.items_one unterscheidet. Sie benötigen immer noch eine manuelle Überprüfung für jeden Schlüssel.

Phase Drei: Kommerzielle TMS-Plattformen

Sie melden sich für ein Übersetzungsmanagement-System an. Sie berechnen pro Wort, erfordern GitHub-Integrationen und binden Sie an monatliche Lizenzen. Für ein Nebenprojekt oder eine Indie-App brechen die wirtschaftlichen Vorteile schnell zusammen – und Sie stoßen immer noch auf die gleichen Probleme mit der Platzhalterbeschädigung, wenn deren Engine das i18next-Format nicht explizit parst.

Dieselben Fehlerbilder treten auch in Gettext-Workflows auf. Unser Leitfaden zum Übersetzen von .po-Dateien ohne Code-Variablen zu beschädigen behandelt das parallele Problem für WordPress und andere Gettext-basierte Stacks.

Der sichere Ansatz: Syntaxbewusste Übersetzung

Der einzige zuverlässige Weg, i18next JSON in großem Umfang zu übersetzen, ist mit einem Tool, das das Format zuerst parst, die Syntax sperrt und nur den übersetzbaren Text an die KI sendet.

So funktioniert die syntaxbewusste Verarbeitung unter der Haube:

1. Parst das JSON in einen abstrakten Baum und bewahrt dabei Schlüsselpfade und Verschachtelung.
2. Identifiziert Interpolations-Token ({{name}}, {{count, number}}, {{date, datetime}}) und ersetzt sie durch Platzhalter-IDs.
3. Identifiziert HTML-Tags innerhalb von Trans-Komponenten (<0>, <strong>, <br/>) und sperrt sie.
4. Erkennt Pluralschlüssel anhand von Suffixen und ordnet sie den CLDR-Regeln für das Zielgebietsschema zu.
5. Sendet nur den bereinigten Text an das LLM mit Kontext zum Schlüsselpfad.
6. Fügt die ursprünglichen Token und Tags an ihren exakten Positionen wieder ein.
7. Validiert die Ausgabe – wenn ein Platzhalter fehlt oder fehlerhaft ist, wird zur Quelle zurückgewechselt.

Dies ist dasselbe Prinzip, das die cloudbasierte PO-Übersetzung sicher macht. Wenn Sie neugierig auf die zugrunde liegende Architektur sind, erklärt unser Vergleich der KI-Übersetzungsqualität, wie verschiedene LLMs mit diesen Einschränkungen umgehen.

Schritt für Schritt: i18next JSON mit SimplePoTranslate übersetzen

SimplePoTranslate unterstützt i18next JSON nativ in den Pro- und Lifetime-Plänen. Die kostenlose Stufe umfasst derzeit .po und .pot – führen Sie ein Upgrade durch oder nutzen Sie eine Testversion, um auf JSON zuzugreifen.

1. Ihre Quelldatei vorbereiten

Verwenden Sie Ihre englische (oder die Quelldatei Ihres Gebietsschemas) als Master. Stellen Sie sicher, dass es sich um gültiges JSON handelt und alle Schlüssel enthält, die Ihre App verwendet. Ein häufiger Fehler ist das Belassen von veralteten oder ungenutzten Schlüsseln, was Ihr Übersetzungs-Kontingent für Zeichenfolgen verbraucht, die Sie niemals rendern werden.

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. Auf SimplePoTranslate hochladen

Melden Sie sich in Ihrem Dashboard an, klicken Sie auf Neue Übersetzung und laden Sie common.json hoch. Die Plattform erkennt das i18next-Format automatisch. Wählen Sie Ihre Zielsprache aus den 41 unterstützten Gebietsschemata aus, wählen Sie einen Ton (professionell, locker, Marketing) und senden Sie ab.

3. Lassen Sie die Engine arbeiten

Unter der Haube wird die Datei geparst, in sichere Batches aufgeteilt und parallel übersetzt. Interpolations-Token sind gesperrt. Plural-Suffixe bleiben erhalten und werden den CLDR-Regeln des Zielgebietsschemas zugeordnet. HTML innerhalb von Trans-Komponenten bleibt intakt.

4. Die ZIP-Datei herunterladen

Sie erhalten eine ZIP-Datei mit dem übersetzten JSON plus alternativen Formaten (.php für PHP-Apps, .po für die Kompatibilität zwischen Tools). Legen Sie das JSON in public/locales/es/common.json ab und stellen Sie es erneut bereit.

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. Wiederholen oder im Stapel verarbeiten

Für alle 12 Zielgebietsschemata reichen Sie 12 Aufträge ein. Die Kontingente des Pro-Plans decken Dutzende typischer SaaS-Anwendungen ab. Für Monorepos mit mehreren Namespace-Dateien laden Sie jede einzeln hoch oder verarbeiten sie sequenziell im Stapel.

Übersetzungen wieder in Ihre App integrieren

Sobald Sie JSON-Dateien übersetzt haben, ist die Integration der einfache Teil. Ein paar Fallstricke:

• Plural-Kategorien überprüfen. Führen Sie einen schnellen Rauchtest pro Gebietsschema durch: Rendern Sie eine Komponente mit count={0}, count={1}, count={5} und bestätigen Sie, dass alle drei die richtige Zeichenfolge erzeugen.
• RTL-Gebietsschemata prüfen. Wenn Sie ins Arabische, Hebräische oder Persische übersetzt haben, benötigt Ihre Benutzeroberfläche RTL-fähiges CSS. Unser WordPress RTL-Übersetzungsleitfaden behandelt die CSS-Muster, die auch für React-Apps gelten.
• Eine Fallback-Kette einrichten. Konfigurieren Sie i18next so, dass es auf Englisch zurückgreift, wenn ein Schlüssel fehlt, damit Zwischen-Deploy-Zustände die Benutzer nicht abstürzen lassen.
• Ihre Quelldatei in CI sperren. Fügen Sie eine Überprüfung hinzu, die Pull-Requests ablehnt, bei denen sich en/common.json ändert, ohne andere Gebietsschemata neu zu generieren. Übersetzungsdrift ist die größte Ursache für i18n-Fehler in der Produktion.

Für Teams, die über React, Next.js und serverseitig ausliefern, ist die Erstellung jedes Formats aus einer Quelle ein großer Gewinn. Unser Beitrag über eine Datei rein, fünf Formate raus erklärt, warum Multi-Format-Ausgabe für die langfristige Wartung wichtig ist.

Wenn JSON nicht ausreicht: Komplexe Fälle behandeln

Einige Randfälle erfordern besondere Sorgfalt.

ICU MessageFormat

Wenn Ihr Projekt ICU-Syntax verwendet ({count, plural, one {1 item} other {# items}}), behandelt i18next dies als Interpolation, aber die Struktur ist komplexer. Stellen Sie sicher, dass Ihr Übersetzungstool ICU-Parameter erkennt und keine Kategorienamen wie one, other oder Format-Bezeichner wie plural, number, date übersetzt.

Trans-Komponente mit React Nodes

<Trans> rendert React-Komponenten innerhalb übersetzter Zeichenfolgen, indiziert nach Index (<0>, <1>). Der Übersetzer muss die genaue Tag-Reihenfolge beibehalten. Die Syntax-Sperre von SimplePoTranslate handhabt dies, aber wenn Sie ein anderes Tool verwenden, überprüfen Sie dies vor der Auslieferung.

Namespace-Dateien

Große Apps teilen Lokalisierungen in Namespaces auf: common.json, dashboard.json, checkout.json. Übersetzen Sie jede Datei unabhängig – führen Sie sie nicht zusammen. Die Kontextqualität ist höher, wenn die Schlüsselpfade jedes Namespaces begrenzt bleiben.

Zusammenfassung

Die Übersetzung von i18next JSON für eine React- oder Next.js-App besteht nicht darin, das beste KI-Modell auszuwählen. Es geht darum, die strukturellen Regeln des Formats zu respektieren: Interpolationen, Plural-Suffixe, verschachtelte Schlüssel und HTML-Tags müssen den Roundtrip überleben. KI-Tools für Endverbraucher behandeln JSON als unstrukturierten Text. Syntaxbewusste Tools parsen es als strukturierte Daten und bearbeiten nur übersetzbare Oberflächen.

Wenn Sie eine mehrsprachige App ausliefern und JSON in Chat-Schnittstellen kopiert und eingefügt haben, kennen Sie bereits die Kosten: Stunden manueller Überprüfung pro Gebietsschema, zufällige Produktionsfehler und ein wachsender Stapel fehlerhafter Pluralformen. Eine formatbewusste Pipeline beseitigt all diese Fehlerursachen.

Bereit, Ihre i18next JSON-Dateien sicher zu übersetzen? SimplePoTranslate kostenlos testen – keine Kreditkarte erforderlich. Einmal hochladen, in 41 Sprachen ausliefern.