Skutečný payload je málokdy jen souvislý text. Stejný objekt, který obsahuje title a body, často nese i id, slug, URL assetu, název šablony nebo enum kód – hodnoty, které váš obsah identifikují nebo propojují a z překladu musí vyjít přesně tak, jak do něj vstoupily. Riziko je nenápadné: když modelu předáte pole s názvem id vedle textu, který překládá, může se rozhodnout, že "post-42" bude znít lépe lokalizovaně, znormalizuje URL nebo „opraví“ enum. Jediný změněný identifikátor znamená rozbitý odkaz nebo neúspěšné vyhledání v produkci – v jakémkoli jazyce, kde se model rozhodl být nápomocný.
lockedKeys z tohohle dělá jistotu. Určíte klíče, které se nesmějí změnit – přesným názvem nebo globem – a lokalizační engine tyto hodnoty z překladu vynechá, potom zdrojové hodnoty doslovně vrátí do outputData pro každý cílový jazyk. Uzamčená hodnota se nepřekládá, nenormalizuje ani nepřepisuje. Stejný identifikátor na vstupu, stejný identifikátor na výstupu, v každém jazyce.
lockedKeys je pole v requestu create-jobs. Úplný tvar requestu a odpověď 202 najdete v Create jobs; tato stránka pokrývá jen to, co patří do lockedKeys a jak funguje párování.
Uzamčení klíče podle názvu#
Předejte lockedKeys spolu se svým data. Každá položka je vzor – v nejjednodušší podobě prostý název klíče, který chcete zachovat.
{
"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"]
}Prostý vzor id odpovídá klíči id všude, kde se objeví jako samostatný segment – tady jak na nejvyšší úrovni v id, tak ve vnořeném author.id. outputData v každé německé a francouzské úloze tak zachová "post-42" a "u_abc" beze změny. Překládají se jen title, name a body; tags zůstává tak, jak je, protože neobsahuje žádnou uzamčenou cestu, a jeho řetězcové hodnoty se překládají jako jakýkoli jiný text.
Ten poslední bod stojí za to zdůraznit, protože odpovídá na první otázku, kterou si skeptik položí.
Překládá se uzamčená hodnota?
Ne. Klíč, který uvedete v lockedKeys, je z překladu vyloučen a jeho zdrojová hodnota se vrátí do outputData doslovně pro každý cílový jazyk. Hodnota, kterou jste poslali, se vrátí beze změny – nepřeložená, nenormalizovaná, nepřepsaná. Uzamčení je záruka výsledku vyjádřená pomocí lockedKeys, ne nápověda, kterou má model respektovat.
Shoda podle názvu kdekoli – nebo podle pozice#
Prostý vzor je název klíče a odpovídá tomuto názvu jako samostatnému segmentu, v libovolné hloubce a kdekoli ve stromu. Pokud se audioSrc objeví na dvanácti místech vnořených pod různými rodiči, jediný vzor audioSrc uzamkne všech dvanáct. Nemusíte vypisovat cesty, abyste zachytili každý výskyt – to je běžný případ a stačí na něj jeden řádek.
Když potřebujete řízení podle pozice – uzamknout jeden výskyt, ale ne jiný, nebo každý prvek pole a nic dalšího – použijte glob s / jako oddělovačem cesty. Indexy polí se chovají jako běžné segmenty, takže users/0/email i users/*/email jsou platné cesty.
| Vzor | Co uzamkne |
|---|---|
audioSrc | Každý list audioSrc ve stromu, v libovolné hloubce |
metadata | Celý podstrom metadata všude, kde se objeví |
metadata/author | Sekvenci metadata/author kdekoli, kde se objeví, a vše pod ní |
users/*/email | Každý email uživatele – * je jeden segment a odpovídá libovolnému indexu |
users/0/email | Jen e-mail prvního uživatele |
**/{audioSrc,imageSrc} | Oba názvy listů pomocí alternace ve složených závorkách |
Dva vzory výše záměrně uzamykají víc než jeden list. metadata uzamkne celý podstrom pod tímto klíčem – zachová se každá hodnota pod ním, ať už vypadá přeložitelně, nebo ne. metadata/author uzamkne tuto sekvenci všude, kde se vyskytne, a všechno pod ní. Po uzamčení podstromu sáhněte tehdy, když je celý blok strukturální – třeba konfigurační objekt nebo raw embed – a po uzamčení listu (metadata/author/name) tehdy, když se má zachovat jen jedno pole uvnitř jinak přeložitelného bloku.
Glob, ne regex
* odpovídá přesně jednomu segmentu cesty; ** pokrývá libovolný počet segmentů; {a,b} znamená alternaci mezi možnostmi ve složených závorkách. Neexistuje shoda podle znakových tříd ani částečných tokenů – vzory pracují s celými segmenty cesty, ne s podřetězci. Pište users/*/email, ne regulární výraz.
Co se vrátí#
Uzamčení mění to, co model překládá – nemění ale tvar výsledku. outputData přesně kopíruje vstupní strukturu: uzamčené klíče zůstávají na svých původních místech se svými původními hodnotami a přeložitelné řetězce kolem nich se přeloží. Nic se nevynechá, nepřejmenuje ani nepřeskupí.
U výše uvedeného vstupu nese outputData v každém jazyce id: "post-42" a author.id: "u_abc" beze změny, zatímco title, name a body jsou v cílovém jazyce. Úplná odpověď úlohy – outputData, steps po jednotlivých fázích a stav – je zdokumentovaná na stránce Get a single job.
Jedno omezení, rovnou na začátku#
lockedKeys přijímá až 100 vzorů na request. Je to strop pro počet vzorů, ne pro počet klíčů, kterým odpovídají – jeden audioSrc nebo users/*/email může ve velkém payloadu uzamknout tisíce hodnot a stále se počítá jako jeden vzor. Pokud se blížíte 100 různým vzorům, obvykle je to signál, že širší glob (**/{id,slug,href}) nebo uzamčení podstromu vyjádří stejný záměr v mnohem menším počtu řádků.
lockedKeys je také ad hoc a platí pro každý request zvlášť: uzamkne klíče jen pro tuto skupinu úloh. Takže pro termíny, které se nemají překládat v žádné úloze – název produktu, ochranná známka funkce, jednotka, která musí zůstat doslovná – je trvalým řešením nepřeložitelná položka ve slovníčku vašeho engine, která se automaticky použije při každém volání. Viz Glossaries. lockedKeys používejte pro strukturální pole svázaná s tvarem konkrétního payloadu; slovníček používejte pro slovní zásobu, která je konstantní napříč veškerým vaším obsahem.
