Maintain SDK v0 integrations
Understand LingoDotDevEngine helpers and preserve their input, output, batching, and cancellation behavior when migrating.
An application using LingoDotDevEngine may rely on more than object translation: it can split requests into chunks, rebuild arrays, or parse HTML. A migration needs to preserve those behaviors deliberately. Changing the import alone does not replace them.
This reference covers lingo.dev 0.138.10, whose lingo.dev/sdk entry re-exports @lingo.dev/_sdk 0.17.3. Keep the version recorded in the application's lockfile while checking its call sites. For a new server workflow, use the JavaScript API guide.
Existing object-translation calls #
The historical server-side shape is:
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" },
);The helper returns the translated record directly. Keep credentials on the server. A document job has a separate creation, start, and download lifecycle; its create response is not this helper's translated record.
Constructor and batching controls #
| Option | Historical behavior |
|---|---|
apiKey | Required string, validated by the constructor. |
apiUrl | API base URL override. |
engineId | Optional localization engine selection sent with translation. |
batchSize | Default 25, maximum 250. |
idealBatchItemSize | Default 250, maximum 2500. |
maxRetries | Default 3. |
retryDelayMs | Default 500 milliseconds. |
Batch options control the client's chunk construction, not application-wide concurrency. Its retry helper retries network and 5xx failures with exponential jitter. Intentional aborts and ordinary 4xx responses are not retried through that helper. Other operations, such as recognition and account lookup, use their own request paths; do not assume one retry policy covers every method.
Helper inputs and return values #
| Helper | Contract |
|---|---|
localizeObject(object, params, progressCallback?, signal?) | A record in and a translated record out. |
localizeText(text, params, progressCallback?, signal?) | Wraps the text as a field and returns the translated string. |
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?) | Runs a text request for each locale and returns strings in the requested locale order. |
localizeStringArray(strings, params) | Uses temporary keys and rebuilds a string array; no public signal parameter. |
localizeChat(messages, params, progressCallback?, signal?) | Translates text in { name, text } messages and retains their names. |
localizeHtml(html, params, progressCallback?, signal?) | Parses HTML with jsdom, translates selected content, and serializes the result. |
recognizeLocale(text, signal?) | Returns the locale value from recognition. |
estimate(items, signal?) | Accepts { targetLocale, sourceChars } items and returns approximate totals and per-locale costs. |
whoami(signal?) | Returns { email, id } or null for ordinary unsuccessful account responses; server errors can throw. |
Common translation parameters are sourceLocale (nullable for detection), targetLocale, optional fast, reference data by locale, per-key hint arrays, filePath, and triggerType (cli or ci). Locales are normalized before use. Preserve the meaning of each input when mapping it to a newer request schema.
Progress callbacks report completed client chunks, including the completed percentage and source/processed chunks. They are not durable background-job notifications. An AbortSignal stops client work but cannot undo processing the server already accepted.
Preserve HTML behavior explicitly #
The HTML helper translates text nodes outside script and style, plus meta.content, img.alt, input.placeholder, and a.title. It sets the document language to the target and serializes the DOM. It does not translate every attribute or preserve the original bytes.
Test this helper in the actual server runtime, including resolution of its dynamic jsdom import. Compare links, structural markup, selected attributes, and serialized output before migrating an HTML call to a different transformation. A structured JSON request alone does not perform those HTML steps.
ReplexicaEngine and LingoEngine extend LingoDotDevEngine as compatibility aliases and emit deprecation warnings. Removing an alias warning is a naming change; it does not complete a behavioral migration.
Move an application to document jobs #
For a new integration, use the API job lifecycle. Put object content in an inline JSON document, start the job, and download each completed target. Keep the job ID with the source revision until the application accepts its result.
Preserve any application behavior that currently depends on text wrapping, array order, HTML parsing, batching, or progress callbacks. File translation can use the corresponding document format. A change of transport does not automatically recreate client-side transformations or retries.
Compare the resulting data and failure handling before switching application storage to the new flow. The workflow guide covers partial results and out-of-order completion.