Lingo.dev SDK 集成实战深入 Replexica 仓库的 LingoDotDevEngine 本地化 API 完全指南【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexicaLingo.dev SDK 是 Lingo.dev 官方提供的 JavaScript/TypeScript 本地化引擎客户端封装了 Lingo.dev 平台的 API 调用支持对象、文本、字符串数组、聊天序列、HTML 文档等多种内容形态的批量翻译。本文基于当前仓库packages/sdk的真实源码完整讲解 SDK 的安装方式、LingoDotDevEngine的配置参数、全部公开 API 的用法与底层实现原理读者读完即可在自己的 Node.js/TypeScript 工程中接入并完成一次端到端的本地化调用。一、SDK 定位与包结构packages/sdk是本仓库Replexica / Lingo.dev 开源工程中的核心包之一负责把 Lingo.dev 平台 API 的调用逻辑独立成可复用的 SDK。在 package.json 中可以看到它的完整元数据包名lingo.dev/_sdk版本0.17.3许可证 Apache-2.0type: module且sideEffects: false对外同时提供build/index.mjsESM与build/index.cjsCJS两种产物并有build/index.d.ts类型声明运行时依赖仅四个lingo.dev/_spec语言代码与配置规范、paralleldrive/cuid2会话 ID 生成、jsdomHTML 本地化、posthog-node使用遥测外加zod参数校验。构建配置见 tsup.config.ts入口为src/index.ts同时产出 cjs 与 esm 两种格式zod与posthog-node被标记为 external不打进产物并开启dts类型声明生成。SDK 的全部公开实现都集中在 src/index.ts核心是一个LingoDotDevEngine类另有两个为了向后兼容而保留的废弃类ReplexicaEngine与LingoEngine构造时会输出弃用警告见 src/index.ts。二、安装与引入官方 READMEpackages/sdk/README.md给出的安装命令为npm i lingo.dev安装完成后在你的工程中引入import { LingoDotDevEngine } from lingo.dev/sdk;如果你的项目使用其他包管理器也可以等价地使用 pnpm 或 yarn 安装。由于包同时提供 ESM 与 CJS 产物无论是import还是require均可正常工作。三、快速开始创建引擎实例LingoDotDevEngine的构造函数接收一个配置对象内部通过 zod schema 做严格校验见 src/index.tsconst engine new LingoDotDevEngine({ apiKey: your-api-key, });最简单的用法只需要apiKey一个必填项。完整配置参数及其默认值如下表全部取自engineParamsSchema参数类型默认值说明apiKeystring必填Lingo.dev API 密钥请求时以X-API-Key请求头发送apiUrlstringURLhttps://api.lingo.devAPI 服务地址可指向私有部署或代理batchSizenumber整数1–25025每个请求批次最多包含的翻译条目数idealBatchItemSizenumber整数1–2500250每个请求批次理想的词数上限超限即切分engineIdstring可选无指定引擎 ID用于路由到对应的 vNext 引擎maxRetriesnumber整数≥03瞬时故障5xx 或网络错误时的重试次数0表示不重试retryDelayMsnumber整数≥0500重试指数退避的基准延迟毫秒注意schema 末尾带有.passthrough()即额外传入的未知配置项会被透传保留而不会报错。从 src/index.ts 可以看到每次请求都会携带固定的请求头Content-Type: application/json; charsetutf-8与X-API-Key: apiKey。四、核心本地化 API 详解LingoDotDevEngine根据内容形态提供了多个高层方法内部统一收敛到_localizeRaw与localizeChunk完成分块、请求与合并。所有本地化方法共享一组参数sourceLocale源语言代码可为null此时由服务端自动检测语言targetLocale目标语言代码必填fast可选布尔值开启快速模式更快但质量可能略低reference可选的参考翻译字典形如{ targetLocale: { key: value } }用于引导翻译风格与术语hints可选的提示词集合形如{ key: string[] }filePath可选的源文件路径元数据随请求上报triggerTypecli或ci标识本次调用的触发场景。以上 schema 定义见 src/index.ts。下面逐一介绍各方法。4.1 localizeObject翻译普通 JS 对象localizeObject接收一个任意结构的对象提取其中所有字符串值进行翻译并返回结构完全相同、字符串值已被翻译的新对象。适用于 JSON 词典、配置文案等结构化数据的本地化const result await engine.localizeObject( { greeting: Hello, world!, buttons: { submit: Submit, cancel: Cancel }, }, { sourceLocale: en, targetLocale: es, fast: true, }, ); // result 结构与输入一致字符串值已被翻译为西班牙语实现位于 src/index.ts。可以看到该方法内部会先上报遥测事件再调用_localizeRaw成功与失败都会上报对应事件并重新抛出错误。4.2 localizeText / batchLocalizeText翻译单条文本localizeText将单条字符串包装为{ text }发送返回翻译后的字符串const translated await engine.localizeText(Hello, world!, { sourceLocale: en, targetLocale: fr, });batchLocalizeText则一次性将同一条文本翻译到多个目标语言内部使用Promise.all并发调用localizeText返回一个与targetLocales顺序对应的翻译结果数组const results await engine.batchLocalizeText(Hello!, { sourceLocale: en, targetLocales: [es, fr, de], }); // results[0] 为西班牙语results[1] 为法语results[2] 为德语实现见 src/index.ts。4.3 localizeStringArray翻译字符串数组并保持顺序localizeStringArray接收字符串数组内部将其映射为item_0、item_1…… 形式的键值对后统一翻译再按Object.values恢复原顺序const translated await engine.localizeStringArray( [Hello, Goodbye, How are you?], { sourceLocale: en, targetLocale: es }, ); // 返回顺序与原数组一致对应测试见 src/index.spec.ts模拟翻译后断言结果[ES:Hello, ES:Goodbye, ES:How are you?]与输入顺序一致且空数组输入返回空数组。4.4 localizeChat翻译聊天序列并保留说话人localizeChat接收{ name, text }[]形式的聊天消息数组仅将每条消息的text提取为chat_0、chat_1…… 发送翻译返回时按索引还原name字段从而保证说话人名称不被翻译、消息顺序不被打乱const translated await engine.localizeChat( [ { name: Alice, text: Hello! How are you? }, { name: Bob, text: Im doing great, thanks! }, ], { sourceLocale: en, targetLocale: es }, );测试验证src/index.spec.ts确认只有text被发送翻译、name原样保留。实现见 src/index.ts。4.5 localizeHtml翻译 HTML 文档并保持结构与格式localizeHtml是 SDK 中最复杂的高层方法src/index.ts它使用jsdom解析 HTML提取可翻译内容后翻译并回写保证标签结构、属性和格式不被破坏。其工作流程为用JSDOM解析 HTML 字符串遍历head与body节点为每个可翻译文本节点和属性生成形如body/1/1/3#alt的路径键将全部提取内容作为对象交给_localizeRaw统一翻译按路径键将翻译结果回写到 DOM 对应节点把html的lang属性更新为目标语言代码最后dom.serialize()输出完整 HTML。其中可本地化的属性白名单与忽略标签在源码中明确写死const LOCALIZABLE_ATTRIBUTES: Recordstring, string[] { meta: [content], img: [alt], input: [placeholder], a: [title], }; const UNLOCALIZABLE_TAGS [script, style];也就是说meta content、img alt、input placeholder、a title会被翻译而script与style内部的文本会被完整跳过。测试用例src/index.spec.ts覆盖了标题、meta、图片 alt、链接 title、input placeholder、嵌套加粗斜体文本、script内容忽略以及html langes的更新等场景。五、进度回调与取消操作所有本地化方法除localizeStringArray与batchLocalizeText外都支持两个可选参数progressCallback进度回调本地化过程中以 0–100 的整数百分比触发localizeObject/_localizeRaw的回调还会附带当前批次的源数据块与处理后的数据块便于实时展示进度条signalAbortSignal来自标准AbortController用于取消长时间运行的本地化操作。const controller new AbortController(); const result await engine.localizeObject(obj, params, (progress) { console.log(Progress: ${progress}%); }, controller.signal); // 需要取消时 controller.abort();底层实现中进度百分比按((i 1) / chunkedPayload.length) * 100计算src/index.ts每完成一个批次即回调一次。sleep工具函数与fetchWithRetry都会监听signal一旦中止会立即抛出Operation was aborted错误且被中止的请求绝不重试见 src/index.ts 与 src/index.ts。六、分块机制大字典如何被切分_localizeRaw在处理大 payload 前会调用extractPayloadChunks将内容切成若干批次src/index.ts切分依据是配置中的两个参数当前批次的条目数达到batchSize默认 25即切分当前批次的累计词数超过idealBatchItemSize默认 250即切分到达 payload 末尾时收尾切分。词数统计由countWordsInRecord递归完成src/index.ts对数组递归累加对对象遍历值递归对字符串按空白拆分计数其他类型计为 0。切分后的每个批次依次调用localizeChunksrc/index.ts请求POST {apiUrl}/process/localize最后通过Object.assign({}, ...chunks)合并所有批次结果。这一机制同时兼顾了请求体积与并发粒度既有条目数上限又有词数上限避免单个批次过大触发平台限流。CHANGELOGpackages/sdk/CHANGELOG.md中也记录了降低默认批次大小以避免触发速率限制的历史调整。七、网络重试与错误处理7.1 指数退避重试自 0.16.5 版本起SDK 对瞬时故障引入了自动重试。fetchWithRetrysrc/index.ts的决策规则非常明确仅对 5xx 响应与网络/传输层错误重试4xx 等不可重试的响应立即返回由调用方处理重试采用**指数退避 全抖动full jitter**策略延迟为[0, retryDelayMs * 2 ** attempt]之间的随机值src/index.ts随机抖动可以让大量客户端在服务恢复时不会同时发起请求造成二次雪崩重试前会先res.body?.cancel()排空即将丢弃的响应体把底层连接释放回连接池被AbortSignal中止的请求绝不重试。7.2 错误信息解析throwOnHttpError与extractErrorMessagesrc/index.ts会把服务端返回的 JSON 错误信息解析为可读文本5xx抛出Server error (503): msg. This may be due to temporary service issues.400抛出Invalid request: msg服务端返回_tag NotFoundError结构时会格式化为entityType not found: id流式响应中错误会出现在响应体的error字段localizeChunk会检测jsonResponse.error并抛出src/index.ts。八、辅助 API语言识别、成本预估与身份查询除了翻译方法SDK 还提供三个实用 API。8.1 recognizeLocale自动识别文本语言recognizeLocale将文本 POST 到{apiUrl}/process/recognize返回识别出的语言代码如en、es适用于sourceLocale未知或需要自动检测的场景const locale await engine.recognizeLocale(Bonjour tout le monde); // locale fr实现见 src/index.ts。8.2 estimate翻译前预估成本estimate用于在提交翻译前预估成本——它纯粹是服务端计算不会翻译、存储或计费。入参是每个目标语言的可翻译源字符数列表const estimate await engine.estimate([ { targetLocale: es, sourceChars: 1200 }, { targetLocale: fr, sourceChars: 1200 }, ]);返回值CostEstimate类型定义见 src/index.ts包含approximate: true标记、按语言拆分的byLocale明细与totals汇总源字符数、预估输出 token 数、预估 LLM 成本、预估本地化成本与总成本的美元估值。注意其approximate恒为true——这是字符数到 token 的启发式估算并非正式报价实际费用可能不同。该方法与 CLI 的lingo.dev run --estimate命令对应见 CHANGELOG.md 0.17.0 条目。8.3 whoami查询当前 API Key 身份whoami向{apiUrl}/users/me发起 GET 请求返回{ email, id }未认证非 5xx时返回null5xx 时抛出服务端错误src/index.ts。自 0.16.1 起网络错误会直接向上传播不再被静默吞掉。九、语言代码规范化与 schema 校验SDK 对语言代码的校验是宽松的但发送到 API 时必须是规范的 BCP 47 形式src/index.ts。sourceLocale、targetLocale以及reference字典的键都会经过localeCodeSchema.transform(normalizeLocale)变换后再发出。normalizeLocale实现于 packages/spec/src/locales.tsexport function normalizeLocale(locale: string): string { return locale.replaceAll(_, -).replace(/([a-z]{2,3}-)r/, $1); }它将下划线替换为连字符pt_PT→pt-PT并去掉安卓地区码中的r前缀pt-rPT→pt-PT。这是 0.16.4 版本修复的问题此前安卓格式pt-rPT与下划线格式pt_PT虽然能通过配置校验但原样发送会被 API 以 400 拒绝。规范化只发生在网络传输层文件路径不受影响因此 CLI 仍可用原始代码命名安卓资源目录如values-pt-rPT/。十、使用遥测与隐私开关SDK 默认会通过 PostHoghttps://eu.i.posthog.com上报方法调用事件事件定义见 src/utils/tracking-events.tssdk.localize.start / success / error与sdk.recognize.start / success / error。遥测实现src/utils/observability.ts提供两个环境变量开关DO_NOT_TRACK1完全禁用遥测上报DEBUGtrue在控制台打印遥测相关的调试日志。遥测身份解析会先调用{apiUrl}/whoami获取userId个人密钥或keyId服务密钥以及organizationId接口失败时回退为对 apiKey 做 SHA-256 哈希取前 16 位生成apikey-hash的匿名 ID。身份结果按 apiKey 缓存缓存失败分支不缓存避免瞬时故障污染整个进程生命周期。十一、在 CLI 中的实际集成SDK 的真实调用场景SDK 并非孤立存在本仓库的 CLI 就是它的典型使用方可以作为集成参考。在 packages/cli/src/cli/localizer/lingodotdev.ts 中CLI 用用户认证信息构造引擎实例const triggerType process.env.CI ? ci : cli; const engine new LingoDotDevEngine({ apiKey: settings.auth.apiKey, apiUrl: settings.auth.apiUrl, ...(engineId { engineId }), });可以看到triggerType由环境变量CI自动推导在 CI 环境运行则标记为ci本地运行则为cli。在 packages/cli/src/cli/processor/lingo.ts 中CLI 处理器同样创建LingoDotDevEngine并调用localizeObject完成批量文案翻译。这印证了 SDK 的设计目标把 API 调用逻辑下沉到 SDKCLI 只负责文件格式的读取、变更检测与结果落盘。十二、测试与验证SDK 使用 Vitest 编写测试pnpm test运行测试文件位于 src/index.spec.ts通过 mock_localizeRaw来验证各高层方法的组装逻辑不依赖真实网络localizeHtml验证路径键提取body/1/1/3#alt等、script内容忽略、回写后的 HTML 结构与lang属性更新localizeStringArray验证顺序保持与空数组边界localizeChat验证说话人保留与文本翻译分离。此外仓库中还有 src/abort-controller.spec.ts、src/utils/observability.spec.ts 与 src/utils/tracking-events.spec.ts 等测试文件分别覆盖取消操作与遥测逻辑。从 CHANGELOG.md 可以看到localizeStringArray0.11.0与AbortController支持0.10.0等能力都是伴随完整测试一起引入的。十三、版本演进要点速览CHANGELOG.md 完整记录了 SDK 的能力演进脉络可作为选型与升级参考0.5.0新增recognizeLocale与localizeHtml0.6.0新增 fast 模式0.7.0新增batchLocalizeText0.7.23自动源语言检测0.10.0全部公开方法支持AbortController0.11.0新增localizeStringArray0.12.0新增 hints 支持0.13.0所有依赖锁定精确版本防范供应链攻击0.16.0统一迁移到api.lingo.dev端点与X-API-Key鉴权新增engineId配置0.16.1改进错误信息解析whoami网络错误直接传播0.16.4语言代码在传输层规范化为 BCP 470.16.5新增maxRetries/retryDelayMs重试机制0.17.0新增estimate()成本预估方法。十四、总结Lingo.dev SDK 以LingoDotDevEngine一个类覆盖了对象、文本、字符串数组、聊天序列、HTML 五种内容形态的本地化辅以语言识别、成本预估与身份查询等能力并通过 zod 校验、自动分块、指数退避重试与AbortController取消机制保证了工程上的健壮性。其设计上的两个显著特点是内部所有翻译路径统一收敛到分块 合并的管线翻译质量相关的reference、hints、fast等参数在服务端处理客户端保持轻量。若要深入了解实现细节可直接研读 packages/sdk/src/index.ts 及其配套测试或参考 packages/cli 中 SDK 与 CLI 的协作方式。【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考