Übersetzungsdateien verwalten, ohne JSON von Hand zu editieren

Translation File Management (die Verwaltung von Übersetzungsdateien) ist die Praxis, die Dateien, aus denen eine Anwendung ihre Übersetzungen lädt (JSON, YAML, .resx, .po, .strings und ähnliche Formate), vollständig, gültig und synchron mit dem Code zu halten, der sie nutzt, ohne dass Entwickler oder Übersetzer diese Dateien von Hand editieren. In den meisten Setups existieren die Dateien weiterhin. Was sich ändert, ist ihre Rolle: Sie werden zum Ergebnis des Übersetzungsworkflows statt zu seiner Benutzeroberfläche.

Dieser Beitrag handelt davon, wie Teams beim manuellen Editieren von Übersetzungsdateien landen, was dabei kaputtgeht, wie die Alternativen tatsächlich aussehen, und was ein Wechsel nicht behebt.

Warum Teams beim Editieren von Übersetzungsdateien landen

Niemand wählt das als Strategie. Es beginnt als offensichtlich richtige Entscheidung: i18next, react-intl, vue-i18n und ihre Verwandten laden eine JSON-Datei pro Sprache, also legt der erste Entwickler en/common.json an, ergänzt de/common.json und bearbeitet beide im Code-Editor. Verschachtelte oder flache Keys, {{count}}-Platzhalter, _one- und _other-Pluralsuffixe: Mit einer Person und zwei Sprachen ist das Editieren der Datei das Übersetzungswerkzeug, und ein gutes.

Dann ändern sich die Nutzer dieses Werkzeugs, während das Werkzeug bleibt. Eine dritte Sprache kommt mit einer Kollegin, die sie spricht. Ein Product Manager will vor der Demo ein Label korrigieren. Eine Agentur-Übersetzerin liefert Polnisch. Jeder von ihnen bekommt dasselbe in die Hand wie der erste Entwickler: eine Datei mit strikter Syntax, ohne Kontext, mit einem Git-Workflow drumherum. Das Setup ist nicht schlechter geworden. Die Menschen, die es benutzen, sind keine Entwickler mehr.

Das Format selbst bringt Fallen mit, die unsichtbar sind, bis sie zuschnappen. JSON erlaubt keine abschliessenden Kommas, keine einfachen Anführungszeichen und keine nicht maskierten Anführungszeichen innerhalb von Strings. Pluralformen werden als Key-Suffixe codiert, die sich zwischen den i18next-JSON-Konventionen v3 und v4 unterscheiden (die JSON-Formatreferenz beschreibt beide). Ein in einer Sprache umbenannter Platzhalter wird wörtlich auf dem Bildschirm gerendert. Und weil die Datei zur Laufzeit geladen wird, lässt ein Syntaxfehler nicht den Build scheitern, sondern die Seite, für die Nutzer dieser Sprache, nach dem Deploy.

Was kaputtgeht

Merge-Konflikte auf der langweiligsten Datei im Repository

Zwei Feature-Branches fügen beide Keys zu common.json hinzu. JSON hat keine Merge-Semantik: Der Konflikt landet auf der schliessenden Klammer, jemand löst ihn von Hand, und die Keys eines Branches verschwinden stillschweigend. Sprachdateien sind in vielen Frontend-Repositories der Dateityp mit der höchsten Konfliktrate, gerade weil jedes Feature sie berührt und niemand sich für sie zuständig fühlt.

Drift zwischen Dateien und Code

Der Code referenziert Keys, die in keiner Datei stehen, also zeigt die Oberfläche den Key-Namen oder den englischen Fallback. Die Dateien enthalten Keys, die kein Code mehr referenziert, also übersetzen Übersetzer weiter tote Strings. Die englische Datei wurde aktualisiert, die deutsche nicht, und nichts markiert den deutschen Wert als veraltet. Über ein Jahr laufen die Sprachdateien strukturell auseinander, und der einzige Weg, das herauszufinden, ist ein manueller Diff.

Übersetzer in Git

Sobald eine Übersetzerin eine Datei bearbeitet, verlangt der Workflow einen Pull Request. Der Reviewer kann das Polnische nicht beurteilen, also prüft er den Diff auf Syntax. Die Übersetzerin sieht nicht, wo der String erscheint, was {{name}} enthalten wird oder ob der Button breit genug ist. In der Praxis reist die Korrektur als Chat-Nachricht, die ein Entwickler in die Datei kopiert, was manuelles Editieren mit einem zusätzlichen Umweg ist.

Keys, die niemandem gehören

Die Key-Benennung wird pro Pull Request entschieden. btn.save, actions.save und common.save existieren nebeneinander, und niemand weiss, ob sie sich unterscheiden sollen. Einen Key umzubenennen heisst, jede Sprachdatei anzufassen. Einen zu löschen heisst zu hoffen, dass kein Screen ihn noch nutzt. Die Datei hat keine Vorstellung davon, wer einen Key angelegt hat, wann oder warum.

Ein Deploy für jeden Tippfehler

In einem dateibasierten Setup ist eine Übersetzungsänderung eine Codeänderung: Commit, Build, Deploy. Ein falsches Label auf Italienisch fährt mit dem nächsten Release mit, es sei denn, jemand hotfixt die Produktion wegen eines Strings. Teams lernen, Übersetzungskorrekturen zu bündeln, was eine höfliche Umschreibung dafür ist, sie eine Weile kaputt zu lassen.

Konsistenz über Dateien hinweg ist unsichtbar

Derselbe Quellbegriff ist über Namespaces hinweg auf drei verschiedene Arten übersetzt, und kein Werkzeug auf Dateiebene kann Ihnen das zeigen, weil die Abweichung zwischen Dateien lebt, nicht in einer. Das ist die am weitesten verbreitete Defektklasse in echten Übersetzungsdaten, und die, die manuelles Review am schlechtesten findet; die Zahlen stehen in Was in Übersetzungen wirklich kaputtgeht.

Wie Teams Übersetzungsdateien heute verwalten

Die meisten Teams befinden sich in einem von fünf Setups, und das ehrliche Bild ist, dass jedes davon für jemanden richtig ist.

• Ein Code-Editor und Konventionen. VS Code mit JSON-Validierung und einer Erweiterung wie i18n Ally, die den Übersetzungsstatus pro Sprache anzeigt. Funktioniert für einen einzelnen Entwickler oder ein kleines Team, in dem jeder, der Text bearbeitet, das Format lesen kann. Funktioniert nicht mehr an dem Tag, an dem jemand ohne Entwicklerhintergrund einen String ändern muss. Wenn Sie hier stehen, ist die FAQ zum Öffnen und Bearbeiten von JSON-Dateien der pragmatische Leitfaden.
• Tabellen im Rundlauf. Die Datei in eine Tabelle exportieren, an Übersetzer schicken, das Ergebnis per Skript importieren. Vertraut für Übersetzer, und ein Snapshot-Problem für alle anderen: Tabelle und Datei laufen auseinander, während die Übersetzung unterwegs ist, und das Zurückführen ist wieder Handarbeit.
• Skripte und CI-Sync. Ein Werkzeug extrahiert Keys aus dem Quellcode (für i18next: i18next-cli extract), ein Skript oder eine GitHub Action schickt sie an einen Dienst und holt die übersetzten Dateien zurück, optional mit maschineller oder KI-Übersetzung dazwischen. Das hält die Dateien generiert und die Entwickler fern von ihnen. Es braucht trotzdem einen Editor auf der anderen Seite für die Menschen, die prüfen und korrigieren, und es beantwortet die Fragen nach Zuständigkeit und Konsistenz nicht von allein.
• Ein Translation-Management-System. Keys kommen aus dem Code, Übersetzer arbeiten in einem Editor mit Kontext und Terminologie, Dateien werden in den Formaten exportiert oder synchronisiert, die der Build erwartet, oder über ein CDN ausgeliefert, sodass der Build sie nicht mehr braucht. Das ist das Setup, in das die anderen vier hineinwachsen, sobald mehr als eine Person Text schreibt.
• Coding-Agents, die die Dateien bearbeiten. Die neueste Option: Ein Agent fügt den Key in alle zwölf Sprachdateien ein, entwirft die Übersetzungen und öffnet den Pull Request. Im mechanischen Teil ist er wirklich gut. Er führt aber auch das ursprüngliche Problem in höherer Geschwindigkeit wieder ein: Text, den niemand geprüft hat, Terminologie, die zwischen Läufen variiert, und keine Aufzeichnung ausser einem Commit von einem Bot. Was in reinen KI-Pipelines scheitert, und der Weg heraus, steht in Wenn KI-Übersetzungen kaputtgehen.

Was das manuelle Editieren wirklich abschafft

Unabhängig von der Werkzeugwahl trennen vier Eigenschaften einen Workflow, in dem niemand Übersetzungsdateien editiert, von einem, in dem es weiterhin jemand tut.

1. Keys entstehen im Code, nicht in Dateien. Entweder liest ein statischer Extraktionsschritt die Übersetzungsaufrufe, oder die laufende Anwendung meldet einen Key, wenn er zum ersten Mal verwendet wird. Beides bedeutet, dass ein Entwickler nie eine Sprachdatei öffnet, um einen Eintrag hinzuzufügen.
2. Die Menschen, die Text schreiben, bekommen einen Editor. Quelltext, Platzhalter, Screenshots, das Glossar, die Historie des Keys, alle Sprachen nebeneinander. Eine Übersetzerin, die den Button sehen kann, muss seine Breite nicht erraten.
3. Dateien werden erzeugt oder verschwinden. Entweder schreibt ein Sync- oder Download-Schritt die Dateien im Format, das der Build erwartet, und bewahrt Struktur und Pluralformen im Rundlauf, oder die Anwendung lädt Übersetzungen zur Laufzeit, und das Repository enthält gar keine Sprachdateien. Diff-basierter Sync ist hier wichtig: Ein Pull Request sollte nur die Keys übersetzen, die er hinzugefügt hat, nicht das ganze Projekt neu hochladen.
4. Jede Änderung hat einen Verantwortlichen und eine Aufzeichnung. Wer den Key angelegt hat, wer ihn übersetzt hat, wer ihn freigegeben hat, wann er veröffentlicht wurde. Eine Datei hat nichts davon; ein Pull Request einen Bruchteil.

Was das nicht löst

Der Verzicht auf das Editieren von Dateien beseitigt eine lästige Pflicht. Er beseitigt nicht die eigentlich schwierigen Teile der Lokalisierung, und ein Workflow-Wechsel sollte nicht so verkauft werden, als täte er das.

• Die Key-Strategie bleibt Ihre Sache. Natürlichsprachliche Keys oder stabile Bezeichner, Namespaces pro Feature oder pro Seite: Ein Werkzeug bewegt die Keys, es entwirft sie nicht. Die Abwägungen stehen im Leitfaden zur Benennung von i18n-Keys.
• Mehrdeutigkeit braucht weiterhin einen Menschen, der sie bemerkt. "Open" als Verb und "Open" als Status brauchen unter Umständen zwei Übersetzungen; kein Sync-Schritt erkennt das. Kontext-Features und Screenshots helfen der Übersetzerin, sobald jemand den Fall markiert hat.
• Qualität ist eine eigene Ebene. Terminologie, die nicht driften darf, Anrede, die nicht mitten in der App kippen darf, und die Frage, wer eine Übersetzung freigegeben hat, werden durch ein Glossar, einen Review-Workflow und automatische QA-Checks gelöst, nicht dadurch, wo die Dateien liegen.
• Manchmal ist die Datei das richtige Werkzeug. Ein Entwickler, zwei Sprachen, die er lesen kann, kein Umsatz, der am Text hängt: Ein Code-Editor ist das günstigste korrekte Setup. Das Signal für den Wechsel ist die zweite Person, die Text ändern muss.

Wie das in Locize funktioniert

Locize ist um die vier Eigenschaften oben herum gebaut, zuerst für das i18next-Ökosystem und über die CLI für andere Formate.

• Keys aus dem Code. Mit i18next-locize-backend und saveMissing: true (auf die Entwicklung beschränkt, damit die Produktion schreibgeschützt bleibt) wird jeder Key, den die Anwendung zum ersten Mal rendert, mit seinem Standardwert im Projekt angelegt; locizify macht dasselbe für statische Websites mit einem Script-Tag. Lieber eine statische Pipeline? i18next-cli extract gefolgt von locize-sync, oder locize sync für JSON, YAML, XLIFF, CSV, PO, RESX, Fluent, Properties und weitere Formate, wie in der CLI-Dokumentation beschrieben.
• Ein Editor für alle, die Text schreiben. Die CAT-Ansicht zeigt alle Sprachen eines Keys nebeneinander, mit Filtern für unübersetzte und zu prüfende Werte, Bulk-Aktionen, Import und Export in den unterstützten Formaten und einer Historie pro Key, die festhält, wer was wann geändert hat.

Der Locize-Übersetzungseditor: alle Sprachen eines Keys nebeneinander, mit Filtern, Bulk-Aktionen und dem KI-Assistenten

• Dateien erzeugt, oder gar keine. locize download und die GitHub Actions schreiben die Dateien, die Ihr Build erwartet; locize sync --changed-only beschränkt einen Pull Request auf die Keys, die er tatsächlich geändert hat (locize-cli 12.7 oder neuer, i18next-cli 1.72 oder neuer). Oder lassen Sie die Dateien weg: Übersetzungen werden standardmässig auf das CDN veröffentlicht, und die Anwendung lädt sie zur Laufzeit, sodass eine Korrektur ohne Commit und ohne Redeploy live geht.
• Erste Entwürfe, ebenfalls ohne Datei. Neue Keys in der Referenzsprache werden per automatischer Übersetzung in jede Zielsprache übersetzt, mit dem Projektglossar und dem Styleguide in der Anfrage, und als zu prüfen markiert, damit eine Person sie im Editor bestätigt statt in einem Diff.

Die JSON-Datei verschwindet nicht aus Ihrem Leben; sie hört auf, der Ort zu sein, an dem Übersetzung stattfindet. Wenn Sie den Unterschied an Ihrem eigenen Projekt sehen möchten: Erstellen Sie ein Projekt, importieren Sie die Dateien, die Sie heute haben, und sehen Sie zu, wie der nächste Key aus Ihrem Code kommt statt von Ihrer Tastatur.

Häufig gestellte Fragen

Wie verwalte ich Übersetzungsdateien, ohne JSON von Hand zu editieren? Machen Sie die Dateien zum Ergebnis des Workflows statt zu seiner Benutzeroberfläche. Keys entstehen aus dem Code, per Extraktion in der CI oder per Laufzeit-Meldung wie der saveMissing-Option von i18next; Übersetzer arbeiten in einem Editor mit Quelltext, Platzhaltern und Terminologie vor Augen; die JSON-, YAML- oder resx-Dateien werden per Sync- oder Download-Schritt erzeugt oder durch CDN-Auslieferung ersetzt.

Sollten Übersetzer JSON-Dateien direkt bearbeiten? Nein. Eine Übersetzungsdatei ist eine Build-Eingabe mit strikter Syntax, und eine ungültige Datei scheitert zur Laufzeit typischerweise lautlos. Übersetzer sehen ausserdem nicht, wo ein String erscheint, wofür ein Platzhalter steht oder wie der Begriff anderswo übersetzt wurde. Geben Sie ihnen einen Editor und lassen Sie die Datei daraus erzeugen.

Was ist der Unterschied zwischen Key-Extraktion und saveMissing? Die Extraktion durchsucht den Quellcode nach Übersetzungsaufrufen und schreibt die Keys in Dateien, deterministisch und ohne die Anwendung zu starten. saveMissing meldet einen fehlenden Key aus der laufenden Anwendung, wenn er zum ersten Mal verwendet wird, zusammen mit seinem Standardwert. Viele Teams nutzen saveMissing in der Entwicklung und die Extraktion als Prüfung in der CI.

Brauche ich weiterhin Übersetzungsdateien im Repository? Nur wenn Ihr Build sie braucht. Mit CDN-Auslieferung enthält das Repository gar keine Sprachdateien, und eine im Editor veröffentlichte Korrektur ist ohne Deploy live. Teams, die Dateien für Server-Side-Rendering oder statische Builds brauchen, laden sie in der CI als generierte Artefakte herunter, nie von Hand editiert.

Können KI-Coding-Agents meine Übersetzungsdateien verwalten? Sie können die Dateien schreiben und bearbeiten, was das Tippen abschafft, aber nicht die Drift: ungeprüfter Text, Terminologie, die zwischen Läufen variiert, keine Aufzeichnung darüber, wer was freigegeben hat. Agents funktionieren am besten als Beitragende zu einem verwalteten Workflow, indem sie neue Keys melden und Übersetzungen entwerfen, während Konsistenz, Review und Historie im Translation-Management-System leben.