Eine echte Payload besteht selten nur aus Fließtext. Dasselbe Objekt, das ein title und ein body enthält, enthält auch ein id, ein slug, eine Asset-URL, einen Template-Namen, einen Enum-Code – also Werte, die Ihre Inhalte identifizieren oder verdrahten und die die Übersetzung exakt so verlassen müssen, wie sie hineingegangen sind. Das Risiko ist leise: Geben Sie einem Modell ein Feld namens id neben Text, den es gerade übersetzt, und es könnte entscheiden, dass "post-42" lokalisiert besser klingt, oder eine URL normalisieren oder ein Enum „korrigieren“. Schon eine einzige veränderte Kennung bedeutet einen kaputten Link oder einen fehlgeschlagenen Lookup in Produktion – in genau der Sprache, in der das Modell besonders hilfreich sein wollte.
lockedKeys nimmt das Rätselraten aus dem Spiel. Sie benennen die Schlüssel, die sich nicht ändern dürfen – per exaktem Namen oder per Glob – und die Lokalisierungs-Engine nimmt diese Werte von der Übersetzung aus und fügt die Quellwerte anschließend wortwörtlich in outputData für jede Zielsprache wieder ein. Ein gesperrter Wert wird nicht übersetzt, nicht normalisiert und nicht umgeschrieben. Gleiche Kennung rein, gleiche Kennung raus – in jeder Sprache.
lockedKeys ist ein Feld in der create-jobs-Anfrage. Unter Create jobs finden Sie die vollständige Request-Struktur und die 202-Antwort; auf dieser Seite geht es nur darum, was Sie in lockedKeys eintragen und wie das Matching funktioniert.
Einen Schlüssel nach Namen sperren#
Übergeben Sie lockedKeys zusammen mit Ihrem data. Jeder Eintrag ist ein Muster – im einfachsten Fall einfach der Name eines Schlüssels, den Sie unverändert beibehalten möchten.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"data": {
"id": "post-42",
"title": "How async APIs reduce latency",
"tags": ["performance", "infra"],
"author": { "id": "u_abc", "name": "Sam" },
"body": "Async APIs let your app stay responsive while translations process in the background."
},
"lockedKeys": ["id"]
}Das einfache Muster id trifft auf den Schlüssel id, wo immer er als vollständiges Segment vorkommt – hier sowohl auf das id der obersten Ebene als auch auf das verschachtelte author.id. In den outputData jedes deutschen und französischen Jobs bleiben "post-42" und "u_abc" exakt erhalten. Übersetzt werden nur title, name und body; tags bleibt unverändert, weil dort kein gesperrter Pfad enthalten ist, und seine String-Werte werden wie jeder andere Text übersetzt.
Gerade dieser letzte Punkt lohnt es sich festzuhalten, denn er beantwortet die erste Frage, die Skeptiker meistens stellen.
Wird ein gesperrter Wert übersetzt?
Nein. Ein Schlüssel, den Sie in lockedKeys angeben, wird von der Übersetzung ausgeschlossen, und sein Quellwert wird für jede Zielsprache wortwörtlich wieder in outputData eingefügt. Der Wert, den Sie gesendet haben, kommt unverändert zurück – nicht übersetzt, nicht normalisiert, nicht umgeschrieben. Das Sperren ist eine Garantie für das Ergebnis, ausgedrückt über lockedKeys, und kein bloßer Hinweis, den das Modell befolgen soll.
Nach Namen überall abgleichen – oder nach Position#
Ein einfaches Muster ist ein Schlüsselname, und es gleicht diesen Namen als vollständiges Segment, in jeder Tiefe und überall im Baum ab. Wenn audioSrc an zwölf Stellen unter verschiedenen Eltern verschachtelt vorkommt, sperrt das einzelne Muster audioSrc alle zwölf. Sie müssen also keine Pfade einzeln aufzählen, um jedes Vorkommen zu erfassen – das ist der Regelfall, und dafür reicht eine einzige Zeile.
Wenn Sie präzise Positionskontrolle brauchen – also ein Vorkommen sperren, aber ein anderes nicht, oder jedes Element eines Arrays, aber sonst nichts – verwenden Sie einen Glob mit / als Pfadtrennzeichen. Array-Indizes erscheinen dabei als gewöhnliche Segmente, daher sind users/0/email und users/*/email beide gültige Pfade.
| Muster | Was es sperrt |
|---|---|
audioSrc | Jedes audioSrc-Leaf im Baum, in jeder Tiefe |
metadata | Den gesamten metadata-Teilbaum, wo immer er vorkommt |
metadata/author | Die metadata/author-Sequenz, wo immer sie vorkommt, plus alles darunter |
users/*/email | Die email jedes Benutzers – * ist ein Segment und passt auf jeden Index |
users/0/email | Nur die E-Mail des ersten Benutzers |
**/{audioSrc,imageSrc} | Beide Leaf-Namen per Brace-Alternation |
Zwei der obigen Muster sperren absichtlich mehr als nur ein einzelnes Leaf. metadata sperrt den gesamten Teilbaum unter diesem Schlüssel – jeder Wert darunter, egal ob er übersetzbar aussieht oder nicht, bleibt erhalten. metadata/author sperrt diese Sequenz, wo immer sie vorkommt, und alles darunter. Greifen Sie zu einer Teilbaum-Sperre, wenn ein ganzer Block strukturell ist – etwa ein Konfigurationsobjekt oder ein roher Embed – und zu einer Leaf-Sperre (metadata/author/name), wenn nur ein einzelnes Feld innerhalb eines ansonsten übersetzbaren Blocks unverändert bleiben muss.
Glob, kein Regex
* gleicht genau ein Pfadsegment ab; ** umfasst beliebig viele Segmente; {a,b} steht für Brace-Alternation zwischen Alternativen. Es gibt keine Zeichenklassen und kein Matching auf Teil-Token-Ebene – Muster arbeiten mit ganzen Pfadsegmenten, nicht mit Teilstrings. Schreiben Sie users/*/email, nicht einen regulären Ausdruck.
Was zurückkommt#
Das Sperren ändert, was das Modell übersetzt – nicht die Form Ihres Ergebnisses. outputData spiegelt die Eingabestruktur exakt wider: Gesperrte Schlüssel bleiben an ihren ursprünglichen Positionen mit ihren ursprünglichen Werten stehen, und die übersetzbaren Strings drumherum werden übersetzt. Nichts wird entfernt, umbenannt oder neu angeordnet.
Für die obige Eingabe enthält outputData in jeder Sprache id: "post-42" und author.id: "u_abc" unverändert, während title, name und body in der Zielsprache zurückkommen. Die vollständige Job-Antwort – outputData, steps pro Phase und Status – ist unter Get a single job dokumentiert.
Ein Limit, direkt vorweg#
lockedKeys akzeptiert bis zu 100 Muster pro Anfrage. Das ist eine Obergrenze für die Anzahl der Muster, nicht für die Anzahl der Schlüssel, auf die sie passen – ein einzelnes audioSrc oder users/*/email kann in einer großen Payload Tausende Werte sperren und zählt trotzdem nur als ein Muster. Wenn Sie sich 100 unterschiedlichen Mustern nähern, ist das meist ein Zeichen dafür, dass ein breiterer Glob (**/{id,slug,href}) oder eine Teilbaum-Sperre dieselbe Absicht mit deutlich weniger Zeilen ausdrücken würde.
lockedKeys gilt außerdem pro Anfrage und ad hoc: Es sperrt Schlüssel nur für diese Job-Gruppe. Für Begriffe also, die in keinem Job übersetzt werden sollen – ein Produktname, ein markenrechtlich geschütztes Feature, eine Einheit, die wörtlich bleiben muss – ist der dauerhafte Ort ein nicht übersetzbarer Eintrag im Glossar Ihrer Engine, der bei jedem Aufruf automatisch angewendet wird. Siehe Glossaries. Verwenden Sie lockedKeys für strukturelle Felder, die an die Form einer bestimmten Payload gebunden sind; verwenden Sie das Glossar für Wortschatz, der in all Ihren Inhalten konstant bleibt.
