JSON übersetzen
Reiche ein JSON-Objekt mit Kontext, Hinweisen und geschützten Pfaden ein und lade anschließend die Übersetzungen herunter.
Sende ein JSON-Objekt direkt in einem Lokalisierungsauftrag, wenn die Quelldaten deiner Anwendung bereits im Speicher vorliegen. Lingo.dev speichert das Objekt als JSON-Dokument und erstellt für jede Zielsprache eine Ausgabe.
Der Schnellstart enthält ein vollständiges Programm. Diese Referenz erläutert die JSON-spezifischen Anfragefelder.
Ein Inline-Dokument einreichen #
Erstelle den Auftrag unter POST /v2/organizations/:orgId/localization/jobs mit einem API-Schlüssel in X-API-Key und einem stabilen Idempotency-Key für diese Einreichung:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "settings.json",
"format": {
"type": "json",
"options": {
"context": "Settings dialog in a team collaboration application",
"hints": { "$.save": ["Button that saves the edited settings"] },
"lockedKeys": ["$.productName"]
}
},
"source": {
"content": {
"save": "Save changes",
"cancel": "Cancel",
"productName": "Acme"
}
}
}
]
}Die Quelle muss ein JSON-Objekt sein und kann verschachtelte Objekte und Arrays enthalten. Zeichenfolgen an Blattknoten kommen für die Übersetzung infrage; Zahlen, boolesche Werte und null-Werte behalten ihre JSON-Typen bei. Schütze Kennungen, Produktnamen oder URLs, die als Zeichenfolgen vorliegen und unverändert bleiben sollen.
Inline-Quellen verwenden format.type: "json". Bei JSONC oder einem anderen Dateiformat lade die Datei als Bytes hoch.
Kontext hinzufügen und Inhalte auswählen #
Trage die JSON-Optionen im Dokument unter format.options ein:
| Option | Wirkung |
|---|---|
context | Nicht leerer Text, der den Zweck oder die Zielgruppe des Inhalts beschreibt. |
hints | JSONPath-Abfragen, denen nicht leere Arrays mit nicht leeren Hinweisen zugeordnet sind. Alle passenden Hinweise werden für die ausgewählten Zeichenfolgen gesammelt. Standardmäßig ein leeres Objekt. |
lockedKeys | Ausgewählte Quellwerte ohne Übersetzung kopieren. Standardwert: []. |
preservedKeys | Ausgewählte Werte aus der vorherigen Zielversion wiederverwenden, sofern vorhanden; andernfalls die Quellwerte kopieren. Standardwert: []. |
ignoredKeys | Ausgewählte Werte aus der Ausgabe entfernen. Standardwert: []. |
keyScope | Zeichenfolgen neu generieren, die über eine nicht leere Liste von JSONPath-Abfragen ausgewählt werden. Erfordert eine vorherige Übersetzung für jede Zielsprache. |
termScope | Zeichenfolgen neu generieren, die Begriffe aus einer nicht leeren Liste von Quellbegriffen enthalten. Erfordert eine vorherige Übersetzung für jede Zielsprache. |
injectLocale | Die Zielsprache an einer einzelnen JSONPath-Position eintragen, etwa $.meta.locale. Dieser Teilbaum ist vor der Übersetzung geschützt. |
Verwende JSONPath in API-Anfragen. $.title wählt eine Eigenschaft auf der obersten Ebene aus; $.nav.home eine verschachtelte Eigenschaft; $['nav.home'] einen wörtlich angegebenen Schlüssel, der einen Punkt enthält; $..productName diese Eigenschaft auf jeder Verschachtelungsebene. Die Auswahl eines Objekts oder Arrays schließt alle untergeordneten Zeichenfolgen ein. Reine Schlüsselnamen sind keine gültigen API-Abfragen.
Die Steuerungsregeln für Schlüssel werden vor der Übersetzung angewendet. Ignorierte Werte werden entfernt; gesperrte Quellwerte haben Vorrang vor beibehaltenen Zielwerten. Die Auswahl des Übersetzungsumfangs setzt diese Regeln nicht außer Kraft. Informationen zur Zusammenstellung der Ausgabe und zu ICU-Nachrichten findest du in der Referenz zum JSON-Format.
termScope sucht in Quellzeichenfolgen nach Teilzeichenfolgen und beachtet dabei die Groß- und Kleinschreibung. Jeder aufgeführte Begriff kann eine Zeichenfolge auswählen: "cat" findet auch "catalog", während "login" nicht auf "Login" zutrifft. Die gesamte ausgewählte Zeichenfolge wird neu generiert, nicht nur der passende Begriff. Wenn sowohl keyScope als auch termScope vorhanden sind, muss eine Zeichenfolge beide Bedingungen erfüllen. Verwende eine präzise JSONPath-Schlüsselauswahl, wenn eine Teilzeichenfolge auch Nachrichten erfassen würde, die nicht dazugehören.
Starten und Ergebnis abrufen #
Speichere id aus der Antwort auf die Auftragserstellung. Wenn der Auftrag auch auf vorherige Dateien oder andere Dokumente verweist, lade jeden Eintrag in uploads hoch und rufe anschließend POST /v2/localization/jobs/:id/start auf.
Rufe GET /v2/localization/jobs/:id ab und sieh dir für jedes Dokument targets an. Ein Ziel mit status._tag: "Completed" hat eine status.downloadUrl. Lade das JSON-Objekt über diese URL mit derselben Authentifizierung herunter. Die Auftragsantwort selbst enthält den Fortschritt und die Adressen der Artefakte, nicht das übersetzte Objekt.
Reiche für Aktualisierungen die vorherigen Quell- und Zielartefakte ein, wie unter Ein vorhandenes Dokument aktualisieren beschrieben. Bewahre die neue Quellrevision zusammen mit der Auftrags-ID auf, damit ein verzögertes Ergebnis keine neueren Inhalte ersetzen kann.