Údržba integrací SDK v0
Seznamte se s pomocnými funkcemi LingoDotDevEngine a při migraci zachovejte jejich chování při práci se vstupy, výstupy, dávkováním a rušením požadavků.
Aplikace využívající LingoDotDevEngine se může spoléhat i na další funkce než jen překlad objektů: rozdělování požadavků na části, opětovné sestavování polí nebo parsování HTML. Při migraci je třeba toto chování cíleně zachovat. Samotná změna importu tyto funkce nenahradí.
Tato reference popisuje lingo.dev 0.138.10, jehož vstupní bod lingo.dev/sdk znovu exportuje @lingo.dev/_sdk 0.17.3. Při kontrole míst volání ponechte verzi zaznamenanou v souboru Lockfile aplikace. Pro nové serverové workflow použijte průvodce JavaScript API.
Stávající volání pro překlad objektů #
Původní podoba volání na straně serveru:
import { LingoDotDevEngine } from "lingo.dev/sdk";
const apiKey = process.env.LINGO_API_KEY;
const engineId = process.env.LINGO_ENGINE_ID;
if (!apiKey || !engineId) throw new Error("Configure a key and localization engine ID");
const client = new LingoDotDevEngine({ apiKey, engineId });
const translated = await client.localizeObject(
{ greeting: "Welcome back" },
{ sourceLocale: "en", targetLocale: "es" },
);Pomocná funkce vrací přímo přeložený záznam. Přihlašovací údaje uchovávejte na serveru. Úloha zpracování dokumentu má vlastní životní cyklus: vytvoření, spuštění a stažení. Odpověď na její vytvoření není přeloženým záznamem, který vrací tato pomocná funkce.
Konstruktor a nastavení dávkování #
| Volba | Původní chování |
|---|---|
apiKey | Povinný řetězec, který ověřuje konstruktor. |
apiUrl | Přepsání základní URL rozhraní API. |
engineId | Nepovinný výběr lokalizačního engine odesílaný spolu s překladem. |
batchSize | Výchozí hodnota 25, maximum 250. |
idealBatchItemSize | Výchozí hodnota 250, maximum 2500. |
maxRetries | Výchozí hodnota 3. |
retryDelayMs | Výchozí hodnota 500 milisekund. |
Nastavení dávkování určuje, jak klient sestavuje části požadavků, nikoli souběžné zpracování v celé aplikaci. Pomocná funkce pro opakování požadavků opakuje požadavky při síťových chybách a chybách 5xx s exponenciálně rostoucí prodlevou a náhodnou odchylkou. Při záměrném přerušení a běžných odpovědích 4xx požadavky neopakuje. Ostatní operace, například rozpoznávání a vyhledání účtu, používají vlastní cesty pro odesílání požadavků. Nepředpokládejte proto, že se jedna strategie opakování vztahuje na všechny metody.
Vstupy a návratové hodnoty pomocných funkcí #
| Pomocná funkce | Kontrakt |
|---|---|
localizeObject(object, params, progressCallback?, signal?) | Na vstupu záznam, na výstupu přeložený záznam. |
localizeText(text, params, progressCallback?, signal?) | Vloží text do položky objektu a vrátí přeložený řetězec. |
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?) | Pro každý jazyk odešle požadavek na překlad textu a vrátí řetězce v požadovaném pořadí jazyků. |
localizeStringArray(strings, params) | Používá dočasné klíče a znovu sestavuje pole řetězců; nemá veřejný parametr pro signál. |
localizeChat(messages, params, progressCallback?, signal?) | Překládá text ve zprávách { name, text } a zachovává jejich názvy. |
localizeHtml(html, params, progressCallback?, signal?) | Parsuje HTML pomocí jsdom, překládá vybraný obsah a serializuje výsledek. |
recognizeLocale(text, signal?) | Vrací hodnotu rozpoznaného jazyka. |
estimate(items, signal?) | Přijímá položky { targetLocale, sourceChars } a vrací přibližné souhrnné hodnoty a náklady podle jazyka. |
whoami(signal?) | Při běžných neúspěšných odpovědích týkajících se účtu vrací { email, id } nebo null; chyby serveru mohou vyvolat výjimku. |
Mezi společné parametry překladu patří sourceLocale (pro detekci může mít hodnotu null), targetLocale, nepovinný parametr fast, referenční data podle jazyka, pole nápověd pro jednotlivé klíče, filePath a triggerType (cli nebo ci). Jazyky se před použitím normalizují. Při mapování na novější schéma požadavku zachovejte význam každého vstupu.
Zpětná volání informující o průběhu hlásí dokončené části na straně klienta, včetně procenta dokončení a zdrojových i zpracovaných částí. Nejde o trvale uchovávané notifikace úloh na pozadí. AbortSignal zastaví práci klienta, ale nemůže vzít zpět zpracování, které server již přijal.
Cíleně zachovejte chování při zpracování HTML #
Pomocná funkce pro HTML překládá textové uzly mimo script a style a také meta.content, img.alt, input.placeholder a a.title. Nastaví jazyk dokumentu na cílový jazyk a serializuje DOM. Nepřekládá všechny atributy ani nezachovává původní bajty.
Otestujte tuto pomocnou funkci ve skutečném běhovém prostředí serveru, včetně vyhledání modulu při dynamickém importu jsdom. Než volání pro HTML nahradíte jinou transformací, porovnejte odkazy, strukturální značky, vybrané atributy a serializovaný výstup. Samotný strukturovaný požadavek JSON tyto kroky zpracování HTML neprovádí.
ReplexicaEngine a LingoEngine rozšiřují LingoDotDevEngine jako aliasy pro zpětnou kompatibilitu a vypisují varování o zastarání. Odstraněním varování souvisejícího s aliasem vyřešíte jen změnu názvu, nikoli migraci chování.
Přechod aplikace na úlohy zpracování dokumentů #
Pro novou integraci použijte životní cyklus úlohy API. Vložte obsah objektu do dokumentu JSON přímo v požadavku, spusťte úlohu a stáhněte každý dokončený cílový dokument. ID úlohy uchovávejte společně s revizí zdroje, dokud aplikace nepřijme její výsledek.
Zachovejte veškeré chování aplikace, které nyní závisí na vkládání textu do položky objektu, pořadí prvků pole, parsování HTML, dávkování nebo zpětných voláních informujících o průběhu. Pro překlad souborů lze použít odpovídající formát dokumentu. Změna způsobu přenosu automaticky nezajistí stejné transformace ani opakování požadavků na straně klienta.
Než ukládání dat aplikace přepnete na nový postup, porovnejte výsledná data a zpracování chyb. Průvodce workflow popisuje částečné výsledky a dokončování v jiném pořadí.