Váš obsah se mění a teď se musí dostat do všech jazyků, ve kterých produkt nabízíte. Ve školicím modulu přibude nová lekce. V CMS se uloží nový záznam. Upraví se popis produktu. Překlad by se měl rozběhnout do němčiny, francouzštiny, japonštiny a dalších zhruba deseti jazyků – a vaše aplikace by se kvůli tomu neměla zablokovat.
Asynchronní lokalizační API je navržené přesně pro takovou situaci: jeden požadavek, všechny jazyky, výsledky průběžně podle dokončení. Obsah s cílovými jazyky odešlete přes POST jen jednou, okamžitě dostanete zpět 202 a platforma pak překládá každý jazyk jako samostatnou úlohu na pozadí. Zachováte si svůj glosář, hlas značky i konfiguraci modelu – stejný engine, který používá i synchronní API – a přestanete sami řešit opakované pokusy.
Na této stránce
Problém#
Školicí platformy, systémy pro správu obsahu a e-learningové nástroje často potřebují překládat obsah do desítek jazyků ve chvíli, kdy vznikne nebo se aktualizuje. Synchronní lokalizační API funguje, ale ve větším měřítku vás nutí ke kompromisu.
Představte si školicí modul vytvořený v angličtině, který se má dostat k uživatelům ve 14 jazycích. Se synchronním API máte dvě možnosti – a obě něco stojí:
Spustíte 14 paralelních volání – jeden požadavek pro každý cílový jazyk, pokaždé se stejnými zdrojovými daty. Jednotlivé jazyky můžete vykreslovat hned po návratu, ale spravujete 14 síťových round-tripů s redundantními daty a při selhání některého z nich je logika opakovaných pokusů na vás.
Přeložíte všech 14 v jednom synchronním volání – méně round-tripů, ale čekáte na nejpomalejší jazyk, než můžete zobrazit byť jen jeden z nich.
V obou případech je vaše aplikace během zpracování překladů vázaná. Pokud se vám server během běhu restartuje, rozpracované překlady zmizí. Pokud jeden jazyk selže, řešení částečného selhání je na vás. A ani jedna cesta uživatelům jasně nesignalizuje, že překlady právě běží.
Asynchronní API tenhle kompromis odstraňuje. Jeden požadavek vytvoří skupinu úloh, ve které má každý cílový jazyk vlastní úlohu. Každá úloha běží nezávisle přes váš lokalizační engine jako odolný workflow na pozadí – takže restart serveru na vaší straně nic neztratí, protože zpracování neběží ve vašem procesu. Výsledky se doručují po jednotlivých jazycích hned, jakmile jsou hotové. Vaše aplikace zůstává responzivní. Selhání zůstávají izolovaná. Platforma přebírá opakované pokusy i doručení.
Jeden jazyk a sekunda čekání nevadí? Použijte sync.
Asynchronní API dává největší smysl, když pracujete s mnoha jazyky, dlouhým obsahem nebo UI, které má zobrazovat průběh. Pokud potřebujete jen jeden jazykový pár a zvládnete počkat na jeden round-trip, synchronní endpoint Localize je jednodušší volba – jeden požadavek, přeložená data rovnou v odpovědi a žádný webhook endpoint k provozu. Po asynchronní variantě sáhněte ve chvíli, kdy je úloha příliš velká, příliš pomalá nebo zahrnuje příliš mnoho jazyků na to, aby na ni šlo blokovat.
Jak to funguje#
Jsou to tři kroky – a jen ten první proběhne ve vašem request/response cyklu. Zbylé dva se odehrají na platformě, vlastním tempem.
Odešlete jeden požadavek
Odešlete obsah a cílové jazyky přes POST na /jobs/localization. API ověří payload, vytvoří skupinu úloh s jednou úlohou pro každý jazyk a vrátí 202 s ID skupiny a shrnutím úloh. Vaše aplikace může okamžitě pokračovat – v rámci tohoto volání se nic nepřekládá. Kompletní podobu požadavku a odpovědi najdete v Create jobs.
Platforma zpracuje každý jazyk nezávisle
Každá úloha běží přes váš lokalizační engine jako odolný workflow na pozadí a používá stejný výběr modelu, glosář, hlas značky i instrukce jako synchronní API. Volitelně může každá úloha projít i pipeline fázemi pre-edit, human review, post-edit, rephrase a back-translation. Úloha se přesouvá z queued do processing a pak do koncového stavu: completed, completed_with_warnings nebo failed – a výsledek jednoho jazyka nikdy neblokuje jiný.
Výsledky dostávejte průběžně podle dokončení
Jakmile je některý jazyk hotový, platforma doručí jeho výsledek na vaši webhook URL. Pokud chcete ve svém UI zobrazovat živý průběh – třeba počítadlo „3 ze 14 připraveno“, které se aktualizuje s dokončováním úloh – připojte se ke skupinovému WebSocket. Pokud raději výsledky stahujete, pollujte skupinu v pravidelných intervalech.
Autentizace
Každý požadavek – REST i WebSocket – se autentizuje pomocí hlavičky X-API-Key. Klíče jsou navázané na organizaci a mají přístup ke každému engine v rámci organizace. Podrobnosti najdete v Authentication a nový klíč vytvoříte v API Keys.
Model skupiny úloh#
Jedno odeslání vytvoří jednu skupinu, která obsahuje jednu úlohu pro každý cílový jazyk. To je celý mentální model – a právě díky němu dávají odpovědi na složité otázky smysl.
Skeptický čtenář už si nejspíš v hlavě odškrtává seznam: co se stane, když jeden jazyk selže, a co se mezitím děje s mojí aplikací? Model skupiny odpovídá na oboje.
- Selhání jsou izolovaná, protože každý jazyk má vlastní úlohu. Pokud němčina uspěje a japonština selže, německý překlad se doručí normálně a japonská úloha ponese vlastní
errorMessage. Skupina bude hlásitpartiala úspěšně dokončená práce se přesto doručí. Selhání v jednom jazyce nemůže vrátit zpět jiný jazyk, který už byl hotový. Kompletní význam stavů najdete na stránce Track a job group. - Rozpracovaná práce přežije restart, protože neběží ve vašem procesu. Každá úloha je odolný workflow na pozadí na platformě. Pokud se váš server restartuje, nic rozpracovaného se neztratí – znovu se připojíte nebo začnete pollovat a skupina bude přesně tam, kde jste ji opustili.
- Skupina je model průběhu, který můžete napojit na UI. Uložte si
groupIdz202a pak řiďte indikátor průběhu pomocí doručení přes webhook nebo snapshotů z WebSocket. „3 ze 14 jazyků připraveny“ je prostě počítadlo nad podřízenými úlohami skupiny.
Poctivě řečeno, tenhle model má i svou cenu: vezmete na sebe malou část integrace, kterou synchronní volání nevyžaduje. Abyste mohli přijímat výsledky, musíte provozovat HTTPS webhook endpoint nebo držet server-side WebSocket a zpracovávat jednotlivé jazyky ve chvíli, kdy dorazí, místo abyste přeložená data četli přímo z jediné odpovědi. Výměnou za to platforma přebírá opakované pokusy, izolaci selhání i doručení – a vaše aplikace se nikdy neblokuje kvůli překladu.
Přesně pro takový kompromis je asynchronní API navržené: jeden požadavek, všechny jazyky, výsledky průběžně podle dokončení. Následující stránky jsou slovesy této věty.
