Vytvořte workflow pro překlad přes API
Překládejte záznamy aplikace na serveru a uchovávejte přijaté jazykové verze propojené s revizí zdroje, které odpovídají.
Když redaktor upraví popis produktu, musí se změna promítnout do každé přeložené verze. Odpověď API poskytne nový text. Vaše aplikace pak rozhodne, ke kterému záznamu patří, zda je zdroj stále aktuální a kdy se text zobrazí čtenářům.
Tento průvodce navazuje na první požadavek na překlad a ukazuje, jak z něj vytvořit opakovatelné backendové workflow. Hodí se pro záznamy, které spravuje vaše aplikace, například popisy produktů a záznamy nápovědy. Pro statické prostředky aplikace bývá vhodnější workflow pro soubory v CI, protože kompilace prostředků a kontrola v repozitáři už nabízejí prostor pro jejich ověření.
Odešlete ucelený obsah #
Vytvořte lokalizační úlohu s jedním vloženým dokumentem JSON pro záznam produktu. Seskupte související pole, aby kontext mohl popsat jejich účel. Zachovejte stabilní klíče, aby bylo možné stažený objekt přiřadit zpět k těmto polím.
Odešlete toto tělo požadavku na POST /v2/organizations/:orgId/localization/jobs s klíčem API a stabilní hodnotou Idempotency-Key pro tuto revizi:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "products/bottle.json",
"format": {
"type": "json",
"options": {
"context": "Product listing for a reusable drinks bottle",
"hints": {
"$.title": ["Catalog card title"],
"$.description": ["Short product description; do not add specifications"]
}
}
},
"source": {
"content": {
"title": "Insulated bottle",
"description": "Keeps drinks cold during your commute."
}
}
}
]
}Přihlašovací údaje uchovávejte v backendu a engine vyberte výslovně. Pro produktovou terminologii používejte sdílené pokyny z glosáře, pro toto konkrétní použití pak kontext dokumentu. Referenční dokumentace JSON popisuje nápovědy a chráněné cesty.
Zpracovávejte překlad na pozadí #
Než úlohu spustíte, uložte její vrácené ID. Nahrajte vše uvedené v uploads a pak zavolejte POST /v2/localization/jobs/:id/start. I vložený JSON vyžaduje tento výslovný krok spuštění.
Z pracovního procesu v backendu pravidelně zjišťujte stav úlohy a stahujte dokončené cílové výstupy z vrácených URL. Na redaktorův požadavek na uložení můžete odpovědět, jakmile aplikace tuto práci trvale zařadí do fronty. Požadavek nemusí zůstávat otevřený po dobu překladu ani lidské kontroly.
Pro přírůstkové aktualizace uchovávejte předchozí zdrojové artefakty i přijaté cílové artefakty a předejte je v dalším požadavku na dokument. Hranice opětovného použití vysvětluje část Aktualizace dokumentů.
Zaznamenejte práci po uložení zdroje #
Po potvrzení transakce se zdrojem vytvořte ve vlastním úložišti záznam práce s ID obsahu, revizí zdroje, cílovým jazykem, záznamem lokalizačního engine či konfigurace a stavem zpracování. Na základě tohoto záznamu zařaďte překlad do fronty. Zabráníte tak tomu, aby pracovní proces překládal úpravu, kterou transakce se zdrojem později vrátí zpět.
Pro každý cílový jazyk uchovávejte samostatný výsledek. Německý překlad už může být připravený, zatímco francouzský vyžaduje opakování nebo kontrolu. Jediný společný příznak „přeloženo“ by tento rozdíl skryl před aplikací, která rozhoduje, co zobrazit. Názvy stavů, které přidáte, patří do návrhu vaší aplikace, nikoli mezi termíny používané v odpovědích API.
Přijímejte výstup pouze pro zamýšlenou revizi #
Úpravy zdroje a dokončené překlady mohou přicházet v různém pořadí. Podívejte se na tuto posloupnost:
| Událost | Akce aplikace |
|---|---|
| Revize 12 je uložena | Zařadit revizi 12 do fronty na překlad do němčiny. |
| Revize 13 je uložena ještě před dokončením této práce | Zařadit revizi 13 do fronty a označit ji jako aktuální zdroj. |
| Překlad revize 13 je dokončen | Ověřit jej a přijmout pro revizi 13. |
| Překlad revize 12 je dokončen později | Uchovat zaznamenaný výsledek, ale nenahradit jím přijatý text revize 13. |
Při aktivaci porovnejte revizi zdroje v záznamu práce s aktuální revizí zdroje. V úložišti proveďte porovnání i zápis podmíněný touto revizí tak, aby mezi nimi nemohla nepozorovaně proběhnout další úprava zdroje. Pokud práce pro aktuální revizi nebyla zařazena do fronty nebo selhala, naplánujte zpracování aktuální revize. Nepřiřazujte k ní starší výsledek.
Při čtení si vyžádejte přijatý překlad pro požadovaný jazyk a revizi. Rozhodněte, co aplikace udělá, pokud překlad chybí: zobrazí zdrojový text, použije určený náhradní jazyk, poskytne výslovně evidovaný starší překlad, nebo pozastaví publikování. Správná volba závisí na tom, jaký dopad může mít zastaralý či nepřeložený text na čtenáře. Změna podmínky při dokončení nákupu může vyžadovat přísnější pravidla než běžný popis produktu.
Obnovte zpracování pomocí vzdáleného identifikátoru a lokálního záznamu #
Klíč idempotence požadavku trvale uložte před odesláním a ID úlohy ihned po obdržení odpovědi na její vytvoření. Po vypršení síťového časového limitu zopakujte nezměněný požadavek na vytvoření se stejným klíčem nebo načtěte evidovanou úlohu. Opakované volání spuštění se vztahuje ke stejné úloze.
Po dočasných chybách čtení pokračujte v dotazování s postupně se prodlužujícími intervaly. Vypršení časového limitu klienta ukončí čekání, nikoli práci na serveru. Dokončené cílové výstupy a podrobnosti o selhání jednotlivých cílů uchovávejte odděleně. I neúspěšná úloha může obsahovat použitelné dokončené soubory.
Chyby ověřování, neaktivní engine, neplatné vstupy a limity účtu vyžadují nápravu. Po vyřešení limitu pro přijetí ke zpracování lze čekající úlohu znovu spustit. Pokud práce selhala během zpracování, odstraňte příčinu a dotčené dokumenty či jazyky odešlete s novým klíčem idempotence.
Při přijímání proveďte stejnou kontrolu revize u každého výsledku, včetně těch načtených po obnovení zpracování. Dokončené stažení potvrzuje, že je text dostupný. O tom, zda jej lze publikovat, rozhodují vaše pravidla ověřování a kontroly.
Otestujte životní cyklus záznamu #
Použijte krátký záznam s proměnnou a vyzkoušejte aktualizaci zdroje, selhání překladu do jednoho jazyka i dokončení překladů v jiném pořadí. Kromě samotného textu zkontrolujte také uložené klíče polí a identifikátory jazyků. Aplikace by měla poskytovat pouze verzi přijatou podle vašich pravidel a osoba provádějící kontrolu by měla mít možnost dohledat její zdroj.
Pro měření kvality uchovávejte dvojici zdrojového a cílového textu spolu s kritériem použitým k jejich posouzení. Návrh měření platí nezávisle na workflow generování. Záznam pak může rozlišovat mezi vráceným textem, výsledkem měření, přijetím člověkem a publikováním, místo aby je slučoval do jediné události.