维护 SDK v0 集成

了解 LingoDotDevEngine 辅助方法,并在迁移时保留其输入、输出、批处理和取消行为。

使用 LingoDotDevEngine 的应用往往不只依赖对象翻译,还可能会将请求拆分为多个分块、重建数组或解析 HTML。迁移时,需要有意识地保留这些行为。仅修改导入语句,并不能替代这些功能。

本参考文档适用于 lingo.dev 0.138.10,其 lingo.dev/sdk 入口重新导出了 @lingo.dev/_sdk 0.17.3。在检查应用中的调用位置时,请沿用应用 Lockfile 中记录的版本。如需搭建新的服务端工作流,请参阅 JavaScript API 指南。

现有的对象翻译调用 #

旧版服务端调用方式如下:

ts
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" },
);

该辅助方法会直接返回翻译后的记录。请务必将凭据保留在服务端。文档任务拥有独立的创建、启动和下载生命周期,其创建响应并不是此辅助方法返回的翻译记录。

构造函数与批处理控制 #

选项旧版行为
apiKey必填字符串,由构造函数校验。
apiUrl覆盖 API 基础 URL。
engineId可选的本地化引擎选择,随翻译请求一同发送。
batchSize默认值为 25,最大值为 250。
idealBatchItemSize默认值为 250,最大值为 2500。
maxRetries默认值为 3。
retryDelayMs默认值为 500 毫秒。

批处理选项控制的是客户端如何构建分块,而非整个应用的并发量。其重试辅助方法会针对网络错误和 5xx 错误进行重试,并采用带随机抖动的指数退避策略。主动中止的请求和普通的 4xx 响应不会经由该辅助方法重试。识别、账户查询等其他操作各自使用独立的请求路径,因此请勿默认所有方法都遵循同一种重试策略。

辅助方法的输入与返回值 #

辅助方法输入输出约定
localizeObject(object, params, progressCallback?, signal?)输入一条记录,输出翻译后的记录。
localizeText(text, params, progressCallback?, signal?)将文本包装为一个字段,并返回翻译后的字符串。
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)为每个语言区域分别发起文本请求,并按请求的语言区域顺序返回字符串。
localizeStringArray(strings, params)借助临时键重建字符串数组;不提供公开的 signal 参数。
localizeChat(messages, params, progressCallback?, signal?)翻译 { name, text } 消息中的 text,并保留其名称。
localizeHtml(html, params, progressCallback?, signal?)使用 jsdom 解析 HTML,翻译选定内容,然后序列化结果。
recognizeLocale(text, signal?)返回识别出的语言区域值。
estimate(items, signal?)接收 { targetLocale, sourceChars } 项,并返回估算总计及各语言区域的费用。
whoami(signal?)对于一般的账户请求失败响应,返回 { email, id } 或 null;服务器错误则可能抛出异常。

常用翻译参数包括 sourceLocale(可设为空以启用自动检测)、targetLocale、可选的 fast、按语言区域提供的参考数据、各键的提示数组、filePath 以及 triggerType(cli 或 ci)。语言区域在使用前会先经过标准化处理。将各项输入映射到新版请求结构时,请确保其含义保持不变。

进度回调会报告已完成的客户端分块,包括完成百分比以及源分块和已处理分块。这些回调并非持久化的后台任务通知。AbortSignal 可以停止客户端的工作,但无法撤销服务器已接受的处理。

明确保留 HTML 行为 #

HTML 辅助方法会翻译 script 和 style 之外的文本节点,以及 meta.content、img.alt、input.placeholder 和 a.title。它会将文档语言设为目标语言,并对 DOM 进行序列化。它不会翻译所有属性,也不会保留原始字节。

请在实际的服务端运行环境中测试此辅助方法,包括其动态 jsdom 导入能否正常解析。在将 HTML 调用迁移到其他转换方式之前,请对比链接、结构标记、选定属性及序列化输出。仅凭结构化 JSON 请求,并不会执行这些 HTML 处理步骤。

ReplexicaEngine 和 LingoEngine 作为兼容性别名扩展了 LingoDotDevEngine,并会发出弃用警告。消除别名警告只是名称上的变更,并不代表行为迁移已经完成。

将应用迁移到文档任务 #

如需构建新的集成,请采用 API 任务生命周期。将对象内容放入内联 JSON 文档中,启动任务,然后逐一下载已完成的目标结果。在应用确认采纳任务结果之前,请将任务 ID 与源修订版本一并保留。

对于应用当前依赖的文本包装、数组顺序、HTML 解析、批处理或进度回调等行为,请全部予以保留。文件翻译可使用相应的文档格式。更换传输方式并不会自动重现客户端的转换或重试逻辑。

在将应用存储切换到新流程之前,请对比生成的数据及失败处理方式。工作流指南介绍了如何处理部分结果和乱序完成的情况。