JSON
Übersetze verschachtelte Zeichenfolgen und lege fest, welche Pfade kopiert, beibehalten, ausgelassen oder aktualisiert werden.
In einem JSON-Katalog schlägt die Anwendung einen Schlüssel nach und zeigt dessen Wert an. Der json-Dateihandler ändert Zeichenfolgen, während Objektschlüssel, Array-Positionen, Zahlen, boolesche Werte und null-Werte als Daten erhalten bleiben. Er baut das Ziel aus der aktuellen Quelle neu auf und setzt dabei neue Übersetzungen oder beibehaltenen Zieltext ein.
Der Handler unterstützt Kataloge mit verschachtelten Objekten und Arrays sowie eine einzelne Zeichenfolge auf der obersten Ebene. Die CLI leitet json aus .json ab. Konfiguriere die Quelle über die CLI-Konfiguration oder die GitHub App.
Was zur Übersetzungsaufgabe wird #
Zum Beispiel:
{
"checkout": {
"title": "Complete your order",
"delivery": "Delivery within {days} days"
},
"plans": [
{ "name": "Personal", "seats": 1 },
{ "name": "Team", "seats": 10 }
],
"enabled": true
}Der Handler wählt checkout.title, checkout.delivery, plans[0].name und plans[1].name aus. Die Zahlen in seats und den booleschen Wert in enabled lässt er unverändert. Schütze Kennungen, die als Zeichenfolgen gespeichert sind, ausdrücklich: Am JSON-Typ eines Werts erkennt der Handler, dass es sich um Text handelt – nicht aber, ob dieser für Menschen zum Lesen bestimmt ist.
Die Kurzschreibweise für Pfade verwendet Punkte zum Navigieren durch Objekte und eckige Klammern für Array-Positionen: checkout.title wählt einen verschachtelten Wert aus und plans[0].name den Namen des ersten Tarifs. Verwende für einen Schlüssel, der wörtlich checkout.title heißt, die JSONPath-Schreibweise mit Anführungszeichen $['checkout.title']. Die Auswahlsyntax findest du unter Schlüsselsteuerung.
Wie vorhandene Übersetzungen bei Aktualisierungen wiederverwendet werden #
Ein inkrementeller Durchlauf nutzt drei unterschiedliche Eingaben:
| Eingabe | Rolle |
|---|---|
| Aktuelle Quelle | Legt die Struktur und die Zeichenfolgen für die neue Ausgabe fest. |
| Vorherige Quelle | Dient dazu, Änderungen an einer Quellzeichenfolge unter demselben Pfad zu erkennen. |
| Vorhandenes Ziel | Liefert Übersetzungen, die beibehalten werden können. |
Wenn die vorherige Quelle und das vorhandene Ziel verfügbar sind, wird jede neue oder geänderte Quellzeichenfolge zur Übersetzungsaufgabe. Für eine unveränderte Quellzeichenfolge lässt sich der vorhandene Zielwert am entsprechenden Pfad wiederverwenden. Zwei Schlüssel mit demselben englischen Text bleiben separate Datensätze. Da sie unterschiedliche Kontexte haben, können auch ihre akzeptierten Übersetzungen voneinander abweichen.
Änderst du beispielsweise checkout.title, muss checkout.delivery nicht allein deshalb erneut übersetzt werden. Ist dessen Quellwert unverändert und der Zielwert verfügbar, lässt sich dieser übernehmen. Ändert sich eine Zahl oder ein anderer Bestandteil der Strukturdaten, kann dennoch ein Neuaufbau der Datei nötig sein – auch wenn keine neuen Zeichenfolgen zu übersetzen sind.
Bewahre die vorherige Quelle zusammen mit dem zugehörigen akzeptierten Ziel auf. Fehlt eines von beiden, behandelt der Handler die Zeichenfolgen wie bei einem ersten Durchlauf. Lockfile und Cache der CLI verknüpfen diese Eingaben über mehrere Durchläufe hinweg.
Lege fest, was mit geschützten Pfaden geschieht #
Diese Steuerungsoptionen wirken sich unterschiedlich auf die Ausgabe aus:
| Steuerungsoption | Verhalten bei der Übersetzung | Verhalten bei der Ausgabe |
|---|---|---|
| Gesperrter Pfad | Von der Übersetzung ausgeschlossen. | Übernimmt den Wert aus der aktuellen Quelle. |
| Beibehaltener Pfad | Von der Übersetzung ausgeschlossen. | Behält den vorhandenen Zielwert bei, wenn der Pfad im Ziel existiert; andernfalls bleibt der Quellwert erhalten. |
| Ignorierter Pfad | Von der Übersetzung ausgeschlossen. | Entfernt den Pfad aus dem erzeugten Ziel. |
| Einfügen der Sprache | Das konfigurierte Sprachfeld ist von der Übersetzung ausgeschlossen. | Schreibt die Zielsprache in dieses Feld. |
Sperre eine gemeinsam genutzte Kennung, wenn jede Sprache den Quellwert verwenden muss. Behalte eine zielspezifische URL bei, wenn jede Sprache ihr eigenes URL-Ziel hat. Ignoriere eine nur für die Quelle bestimmte Notiz, wenn sie nicht in der übersetzten Datei erscheinen darf. Diese Optionen sind nicht gleichbedeutend mit „nicht übersetzen“.
Am selben Pfad hat das Sperren Vorrang vor dem Beibehalten. Steht ein Wert in beiden Listen, wird er also aus der Quelle übernommen. Das Ignorieren entfernt den Wert auch dann, wenn er zugleich gesperrt, zur Beibehaltung vorgesehen oder zum Einfügen der Sprache ausgewählt ist. Eine eingefügte Sprache hat an ihrer Position Vorrang vor dem Sperren und Beibehalten. Lege möglichst für jeden Wert nur eine zuständige Regel fest und sieh dir die Ausgabe an, wenn sich Regeln innerhalb eines Objekts oder Arrays überschneiden.
Wird ein Array-Element entfernt, verschieben sich die Positionen der nachfolgenden Elemente. Berücksichtige bei der Prüfung des resultierenden Arrays nicht nur den übersetzten Text, sondern auch die Datenstruktur. Beim Einfügen der Sprache können fehlende Objektcontainer erstellt werden. Verwende beim Schreiben in ein Array ein vorhandenes Element oder die Position direkt nach dem letzten Element. Ein Pfad, der Lücken erzeugt oder über einen inkompatiblen Wert führt, schlägt fehl.
Lege diese Steuerungsoptionen über die Felder der CLI-Dateieinträge oder die Optionen der GitHub-Dateieinträge fest.
Umfang und Grenzen des Neuaufbaus #
Eine Schlüsselaktualisierung führt die ausgewählten Übersetzungen mit dem vorhandenen Ziel zusammen. Nicht ausgewählte Zielwerte, nur im Ziel vorhandene Schlüssel und Auslassungen bleiben erhalten. Schlüssel, die nur in der Quelle vorhanden sind und außerhalb des ausgewählten Bereichs liegen, werden nicht hinzugefügt. Schreibvorgänge in Arrays dürfen keine Lücken erzeugen. Wählst du beispielsweise das zweite Array-Element aus, wird ein fehlendes erstes Element dadurch nicht automatisch ergänzt. Sieh dir nach einer Teilaktualisierung das vollständige Ziel an.
Die JSON-Ausgabe wird mit einer Einrückung von zwei Leerzeichen und einem abschließenden Zeilenumbruch serialisiert. Verlasse dich nicht darauf, dass Leerraum oder Kommentare bytegenau erhalten bleiben. Lies bei Quelldateien mit Kommentaren den Abschnitt JSONC und kläre die Anforderungen des verarbeitenden Systems, bevor du eine neu geschriebene Datei als gleichwertig behandelst.
Der Übersetzungs-Workflow kontrolliert die unterstützten Platzhalter- und ICU-Strukturen, einschließlich geänderter oder fehlender Argumente. Sieh dir gemeldete Warnungen oder Fehler an und rendere anschließend die akzeptierte Vorlage mit den Werten der Anwendung. Diese Kontrollen stellen nicht fest, ob die übersetzte Nachricht die beabsichtigte Bedeutung vermittelt.
Lade die Ausgabe mit repräsentativen Werten in der Anwendung. Stelle sicher, dass geschützte Pfade die vorgesehenen Quell- oder Zieldaten beibehalten und die Liefernachricht nach dem Ersetzen der Platzhalter weiterhin dasselbe Versprechen vermittelt. Das Parsen validiert die JSON-Syntax. Durch Rendern und Lesen stellst du sicher, dass die Nachricht so ankommt, wie sie gemeint ist.