Wie man eine JSON-Sprachdatei übersetzt, ohne Schlüssel oder Platzhalter zu beschädigen

Um eine JSON-Sprachdatei wie en.json zu übersetzen, übergeben Sie die gesamte Datei einem Übersetzer, der JSON versteht. Den Rohtext in ein Chatfenster oder einen Web-Übersetzer einzufügen, ist der riskante Weg. Ein JSON-fähiger Übersetzer liest die Datei, übersetzt nur die Textwerte und schreibt dieselben Schlüssel zurück, sodass Ihre App die Datei weiterhin laden kann. Kopieren und Einfügen kann einen Schlüssel übersetzen, ein Anführungszeichen ändern oder eine Klammer verlieren. Jedes dieser Probleme macht die Datei unbrauchbar.

Die Schlüssel zu erhalten, ist der einfache Teil. Der meiste Ärger kommt danach: ein {name}-Platzhalter, der als {nom} zurückkommt, ein ICU-Plural, der seinen other-Fall verliert, eine URL, die wie jeder andere Text zur Übersetzung geschickt wird, und ein paar Änderungen, die der Übersetzer an der Datei selbst vornimmt. Diese Fälle behandelt dieser Leitfaden.

Wir haben eine Testdatei mit all diesen Fällen erstellt und einen kostenlosen Prüfer geschrieben, der eine Quelldatei mit ihrer Übersetzung vergleicht. Außerdem haben wir die Testdatei durch eine lokale Kopie des JSON-Parsing- und Schreibcodes geschickt, den BookTranslator verwendet, mit einem Marker anstelle eines Modells, sodass Sie genau sehen können, welche Werte gesendet werden und wie die Datei zurückkommt.

Kurzantwort: Was mit jedem Teil der Datei passiert

Der Rest dieser Anleitung zeigt, woher jede Zeile stammt und was du dagegen tun kannst.

Schritt 1: Prüfe die Quelldatei vor dem Hochladen

Führe den Checker für die Datei aus, die du übersetzen möchtest. Er benötigt Python 3 und sonst nichts:

python3 check_i18n_json.py en.json

Bei unserer Testdatei gab er Folgendes aus:

WARN  limits.projectId: 9007199254740993 is above 2^53 and can change in a JavaScript round trip; store IDs as strings
WARN  error.network: a flat key with dots and a nested key resolve to the same dot path; tools that address strings by dot path can mix them up
INFO  (root): 3 keys look like integers; JavaScript sorts those first and in numeric order when it rewrites the object
INFO  source: 17 strings, 2 numbers

Die beiden Warnungen und der Hinweis zu integer-ähnlichen Schlüsseln entsprechen jeweils einer Änderung, die wir beobachtet haben, als unsere Testdatei durch den Übersetzer lief. Wenn deine Datei keine davon erhält, kannst du direkt zu Schritt 3 springen.

Der Checker lehnt außerdem eine Datei ab, die kein striktes JSON ist, etwa mit Kommentaren oder nachgestellten Kommas, weil das das nächste Problem ist.

Was aus unserer Testdatei zurückkam

Der Test lief am 2. November 2026 gegen die aktuelle JSON-Verarbeitung im Backend von BookTranslator. Statt ein Modell aufzurufen, ersetzte der Test jeden Wert, der zur Übersetzung gesendet werden sollte, durch [ZH] plus den Originaltext. Das macht das Ergebnis vorhersagbar: Alles mit [ZH] davor wurde gesendet, alles ohne nicht. Beide Ausgaben sind veröffentlicht: die übersetzte Datei und die zweisprachige Datei.

Die übersetzte Datei

Jeder Schlüssel kam unverändert zurück, und die Datei ließ sich weiterhin parsen. Werte mit Buchstaben wurden gesendet, darunter {name}, %s, die ICU-Nachricht, der Tag <b> und die Hilfe-URL. Der Versionsstring "2.4.1", der Bindestrich und die leere Zeichenkette wurden nicht gesendet, da sie keine Buchstaben enthalten. Zahlen und boolesche Werte blieben unangetastet.

Vier weitere Dinge änderten sich:

1. Ein String landete im falschen Schlüssel. In unserem Test enthielt unsere Datei einen flachen Schlüssel "error.network" mit dem Text „Check your connection.“ und außerdem ein verschachteltes "error": { "network": "Network error" }. Der Übersetzer identifiziert jeden String über seinen Pfad mit Punkten zwischen den Teilen, sodass beide Strings dieselbe Adresse hatten: error.network. In der Ausgabe enthielten beide Schlüssel die Übersetzung von „Network error“. „Check your connection.“ war verschwunden. Das erfordert beide Stile in derselben Datei, was selten vorkommt, aber es schlägt still fehl. Der Prüfer warnt davor, bevor du hochlädst.
2. Ganzzahlähnliche Schlüssel wurden neu geordnet. "steps": { "10": ..., "2": ..., "1": ... } kam als "1", "2", "10" zurück. JavaScript listet ganzzahlähnliche Schlüssel beim Neuerstellen eines Objekts immer zuerst in numerischer Reihenfolge auf. Die Schlüssel und Werte stimmen weiterhin überein, deine App funktioniert also, aber ein Diff gegen die Quelldatei wird unübersichtlich.
3. Eine große ID verlor an Präzision. 9007199254740993 kam als 9007199254740992 zurück. JavaScript speichert Zahlen als 64-Bit-Gleitkommazahlen, und Ganzzahlen über 2^53 lassen sich nicht alle exakt darstellen (MDN zu Number.MAX_SAFE_INTEGER). Speichere lange IDs als Strings oder halte sie aus der Sprachdatei heraus.
4. Die Formatierung wurde neu geschrieben. Die Ausgabe verwendet eine Einrückung von zwei Leerzeichen und endet mit einem Zeilenumbruch. Wenn deine Quelle Tabs oder vier Leerzeichen verwendete, rechne mit Änderungen an Leerzeichen im Diff.

Unsere Testdatei hatte keine doppelten Schlüssel, aber es lohnt sich, sie zu kennen: Der JSON-Parser von JavaScript behält bei einem wiederholten Schlüssel nur den letzten Wert, sodass der frühere Text nie übersetzt wird. Deine App würde denselben letzten Wert laden, es bricht also nichts Sichtbares, aber der Prüfer listet doppelte Schlüssel auf, damit du sie bereinigen kannst.

Die zweisprachige Datei

Die zweisprachige Datei behält jeden Originalwert und fügt einen benachbarten Schlüssel mit _translated am Ende hinzu:

"greeting": "Welcome back, {name}!",
"greeting_translated": "[ZH] Welcome back, {name}!",

Das eignet sich gut zum Überprüfen, da Quelle und Übersetzung nebeneinander stehen. Es ist keine Datei, die deine App laden kann, da jeder Schlüssel nun einen Zwilling hat. Verwende die übersetzte Datei in deiner App.

Eine Lücke: Strings in Arrays erhalten keinen _translated-Zwilling, da Array-Elemente keinen Schlüssel haben, an den man einen anhängen könnte. In unserem Test kam "menu": ["Open", "Save", "Export as EPUB"] in der zweisprachigen Datei auf Englisch zurück, in der übersetzten Datei jedoch übersetzt. Wenn du anhand der zweisprachigen Datei prüfst, kontrolliere Arrays in der übersetzten Datei.

Dateien mit Kommentaren

Viele Projekte behalten Kommentare in ihren Sprachdateien (JSONC), was striktes JSON nicht erlaubt. Der Übersetzer versucht zuerst striktes JSON. Wenn das fehlschlägt, entfernt er Kommentare und nachgestellte Kommas und versucht es erneut. Kommentare entfernen bedeutet, alles nach // in einer Zeile zu löschen, und das schließt das // in https:// ein.

Unsere Datei mit einem Kommentar und einer URL ließ sich überhaupt nicht laden; das Parsen schlug beim ersten Kommentar fehl. Eine Datei mit Kommentaren, aber ohne // in einem Wert ließ sich problemlos laden, und die Kommentare wurden aus der Ausgabe entfernt.

Also: Wenn deine Datei Kommentare enthält, entferne sie vor dem Hochladen, oder behalte eine Kopie mit den Kommentaren und akzeptiere, dass die Übersetzung sie nicht enthalten wird.

Schritt 2: Die Datei vorbereiten

Du kannst die meisten dieser Probleme vor der Übersetzung beheben:

• Mach sie zu striktem JSON. Entferne Kommentare und nachgestellte Kommas. Wenn dein Build-Tool JSONC liest, behalte die kommentierte Datei als Quelle und exportiere eine saubere Kopie für die Übersetzung.
• Verwende einen Schlüsselstil. Entweder verschachtelst du Schlüssel oder flachst sie mit Punkten ab, nicht beides in einer Datei. Wenn du i18next verwendest, steuert dessen keySeparator-Option, wie Punkte in Schlüsseln gelesen werden, also prüfe diese Einstellung, bevor du etwas abflachst.
• Verschiebe Nicht-Text-Daten nach draußen. IDs, URLs, Feature-Flags und Limits gehören in die Konfiguration, nicht in die Sprachdatei. Wenn eine URL bleiben muss, behalte sie, aber rechne damit, sie nach der Übersetzung zu prüfen. Unser Leitfaden zu nicht zu übersetzenden Inhalten behandelt, wie du entscheidest, was sonst in der Originalsprache bleiben sollte.
• Schreibe Platzhalter überall gleich. Ein Stil wie {name} ist einfacher zu prüfen als eine Mischung aus {name}, {{name}} und %s.

Schritt 3: Die gesamte Datei übersetzen

Lade die bereinigte Datei in den Dokumentenübersetzer von BookTranslator hoch, der .json zusammen mit den anderen Lokalisierungs- und strukturierten Textformaten auflistet, die er akzeptiert. Der Preis wird vor dem Checkout angezeigt. Wenn die Aufgabe abgeschlossen ist, bietet deine Verlaufsseite die übersetzte Datei und die zweisprachige Datei als separate Downloads an.

Zwei Dinge bei der Übersetzung des Textes beeinflussen das Ergebnis:

• Das Modell sieht Ihre Schlüssel nicht. Jeder Wert wird als nummeriertes Segment ohne den Schlüsselnamen gesendet. Wenn "button.open" und "status.open" beide „Open“ lauten, kann das Modell nicht wissen, dass das eine ein Verb und das andere ein Adjektiv ist. Kurze, mehrdeutige Zeichenketten sollten Sie manuell prüfen.
• Jeder Wert wird einzeln übersetzt. Nichts verbindet zwei Schlüssel miteinander, sodass dasselbe Wort an zwei Stellen unterschiedlich zurückkommen kann und ein Wort, das zwei verschiedene Übersetzungen benötigt, gleich zurückkommen kann. Das optionale automatische Glossar von BookTranslator sammelt Namen, Orte und Fachbegriffe und hält sie konsistent, aber Sie können ihm keine eigenen festen Übersetzungen vorgeben. Für Begriffe, die auf eine exakte Weise übersetzt werden müssen, führen Sie eine Begriffsliste und prüfen Sie diese Zeichenketten nach der Übersetzung; unser Glossar-Leitfaden erklärt, wie Sie einen planen.

Inline-HTML-Tags werden nach der Übersetzung gezählt, und ein Segment, dessen Tags nicht übereinstimmen, wird erneut versucht. Platzhalter in geschweiften Klammern, Platzhalter im %s-Stil und ICU-Syntax werden als Teil des Textes gesendet, aber nicht auf dieselbe Weise geprüft. Führen Sie Schritt 4 bei jeder Übersetzung aus.

Wenn Sie lieber mit einem Chat-Modell oder einem lokalen Modell übersetzen möchten, senden Sie nur die Werte, niemals die Rohdatei, und fügen Sie sie mit einem Skript wieder per Schlüssel ein. Die folgenden Prüfungen gelten in beiden Fällen.

Schritt 4: Die übersetzte Datei prüfen

Vergleichen Sie die Übersetzung mit der Quelle:

python3 check_i18n_json.py en.json fr.json

Um zu zeigen, was er erkennt, haben wir eine französische Datei mit eingebauten Fehlern erstellt. Sie ist handgemacht, keine Modellausgabe. Nach denselben Quellwarnungen wie in Schritt 1 gab der Prüfer Folgendes aus:

ERROR app.greeting: placeholders differ; lost ['name'] extra ['nom']
ERROR app.help_url: urls differ; lost ['https://example.com/help'] extra ['https://example.com/aide']
ERROR app.items: ICU message has no 'other' case
ERROR app.legacy: placeholders differ; lost ['%d'] extra []
ERROR limits.maxFiles: type changed from int to str
ERROR limits.projectId: non-text value changed: 9007199254740993 -> 9007199254740992
INFO  menu[1]: identical to source: 'Save'
INFO  compared 20 source values, 1 unchanged strings

Jeder dieser Fehler würde in der App als Bug erscheinen: ein leerer Name, ein defekter Link, ein Absturz oder eine Rohmeldung bei der Darstellung des Plurals, eine fehlende Kapitelanzahl, ein als Text verglichenes Limit. Die INFO-Zeile listet Zeichenketten auf, die unverändert zurückkamen. Manche sind in Ordnung, wie Markennamen; „Save“ in einem französischen Menü ist es nicht.

Der Prüfer vergleicht Schlüssel, Werttypen, Nicht-Text-Werte, Platzhalter ({name}, {{name}}, %s, %1$s, %@), ICU-Argumentnamen, HTML-Tags und URLs. Die Übersetzung selbst beurteilt er nicht.

Pluralfälle sollen sich ändern

Ein ICU-Plural listet eine Nachricht pro Pluralkategorie auf. Englisch hat zwei Kategorien, one und other, aber viele Sprachen haben einen anderen Satz. Eine gute russische Übersetzung unserer items-Nachricht würde normalerweise one, few, many und other verwenden, eine japanische nur other. Eine Abweichung hier ist also nicht immer ein Fehler.

Die Kategorien stammen aus den Unicode-CLDR-Pluralregeln, und other ist diejenige, die jede Sprache hat. Dies sind die Kardinalkategorien, die von Intl.PluralRules in Node.js mit CLDR 48 gemeldet werden:

Französisch, Spanisch und Portugiesisch verwenden many nur für sehr große runde Zahlen wie eine Million, daher kann eine Meldung für kleine Anzahlen in der Regel darauf verzichten. Der Prüfer meldet ein fehlendes other als Fehler und jede andere Änderung der Kategorien als Warnung, die mit dieser Tabelle abgeglichen werden sollte. Sie können die Liste für jede Sprache selbst ausgeben lassen:

node -e 'console.log(new Intl.PluralRules("ru").resolvedOptions().pluralCategories)'

Dem Übersetzer werden die englischen Fälle vorgegeben, prüfen Sie also, was zurückkommt. Wenn eine russische oder arabische Meldung immer noch nur one und other enthält, ergänzen Sie die fehlenden Fälle von Hand oder lassen Sie es von einem Übersetzer erledigen.

Dann laden Sie sie in die App

Der Prüfer belegt, dass die Datei sicher geladen werden kann, nicht dass sie sich gut liest. Stellen Sie die App auf die neue Sprache um und sehen Sie sich die Bildschirme an: lange Wörter im Deutschen oder Finnischen, die aus einer Schaltfläche herauslaufen, von rechts nach links verlaufender Text im Arabischen oder Hebräischen und Datums- oder Zahlenangaben, die Ihr Code getrennt von der Sprachdatei formatiert. Unser Leitfaden zu Übersetzung versus Lokalisierung behandelt, was sich zwischen Märkten außer den Wörtern noch ändert.

Häufige Probleme

Die übersetzte Datei lässt sich in meiner App nicht laden. Führen Sie den Prüfer dafür aus. Wenn der Prüfer sie nicht parsen kann, wurde die Datei nach der Übersetzung bearbeitet oder war von Anfang an ungültig. Wenn sie geparst wird, suchen Sie nach ERROR-Zeilen zu Schlüsseln oder Typen.

Eine Zeichenkette erscheint als rohe ICU-Nachricht, etwa {count, plural, ...}. Die ICU-Syntax ist bei der Übersetzung kaputtgegangen, meist durch eine fehlende geschweifte Klammer oder einen fehlenden other-Fall. Übernehmen Sie die Struktur aus der Quelle und übersetzen Sie nur die Wörter innerhalb jedes Falls.

Meine Datei ist YAML, eine .po-Datei oder Markdown. BookTranslator akzeptiert auch diese, aber jedes Format hat seine eigenen Regeln. Für Dokumentation siehe unseren Markdown-Übersetzungsleitfaden; für Webseiten den HTML-Dateileitfaden.

Kann ich nur die neuen Schlüssel übersetzen? Nicht innerhalb eines Uploads; die ganze Datei wird übersetzt. Legen Sie die neuen Schlüssel in eine separate Datei, übersetzen Sie diese und führen Sie das Ergebnis nach Schlüssel zusammen. Der Prüfer bestätigt, dass die zusammengeführte Datei jeden Schlüssel enthält.

Sollte ich die Schlüssel übersetzen? Nein. Schlüssel sind Bezeichner, die Ihr Code nachschlägt. Nur die Werte sind Text, den Menschen lesen.