从 lingo.dev/_sdk 变更日志看 Lingo.dev 本地化 SDK 的核心能力与工程演进【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica本篇技术指南以 Replexica 仓库现 Lingo.dev中 packages/sdk/CHANGELOG.md 的版本演进为脉络结合packages/sdk的真实源码实现系统讲解 LingoDotDevEngine 的配置参数、请求管线、重试与错误处理、locale 规范化、成本估算、可观测性及取消机制等核心能力。读完本文你将理解 SDK 每个关键特性的底层实现原理并能参照源码在真实项目中正确配置与使用它。一、SDK 是什么从replexica/sdk到lingo.dev/_sdkCHANGELOG 记录了这个包的完整生命周期。在0.1.0PR #142中项目将API 调用从 CLI 中抽取为独立的 SDK 包0.7.11PR #419时项目完成品牌更名Replexica is now Lingo.dev包名也从replexica/sdk统一为lingo.dev/_sdk同时依赖的replexica/spec也同步更名为lingo.dev/_spec。当前包配置见 packages/sdk/package.json包名lingo.dev/_sdk版本0.17.3协议 Apache-2.0产物同时提供build/index.mjsESM、build/index.cjsCJS与build/index.d.ts类型sideEffects: false便于 tree-shaking运行时依赖lingo.dev/_specworkspace 内部依赖负责 locale 校验与规范化、zod参数校验、posthog-node使用追踪、jsdomHTML 本地化、paralleldrive/cuid2会话 ID 生成。二、核心类 LingoDotDevEngine 与引擎参数SDK 的核心是LingoDotDevEngine类定义于 packages/sdk/src/index.ts。它的全部请求都通过统一的api.lingo.dev域名与X-API-Key请求头认证0.16.0将旧版分散端点统一迁移到该架构见 packages/sdk/src/index.ts。2.1 引擎参数engineParamsSchema引擎构造参数由engineParamsSchema校验packages/sdk/src/index.ts完整参数如下参数类型默认值约束说明apiKeystring—必填平台 API 密钥用于X-API-Key认证apiUrlstringhttps://api.lingo.dev合法 URLAPI 基础地址batchSizenumber25整数1 ≤ n ≤ 250单个请求批次最多容纳的翻译条目数idealBatchItemSizenumber250整数1 ≤ n ≤ 2500单个批次的理想词数上限engineIdstring可选—指定翻译引擎 ID0.16.0起由旧vNext自动迁移maxRetriesnumber3整数≥ 0瞬时失败5xx/网络错误后的最大重试次数0关闭重试retryDelayMsnumber500整数≥ 0指数退避的基础延迟毫秒CHANGELOG 中0.7.1曾将默认batchSize调低以避免触发平台限流0.16.0新增engineId并在请求体中透传测试见 packages/sdk/src/index.spec.ts。所有公共方法调用前会记录LOCALIZE_START等追踪事件0.15.0引入。2.2 内容格式与配套方法0.4.0为 SDK 添加了格式特定方法0.5.0增加recognizeLocale与localizeHtml0.7.0增加batchLocalizeText0.11.0增加localizeStringArray。当前 SDK 提供的公共 API 如下全部支持 AbortSignal 取消localizeObject(obj, params, progressCallback?, signal?)翻译一个 JS 对象中的字符串值保持结构不变localizeText(text, params, progressCallback?, signal?)翻译单个文本batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)将同一文本并行翻译到多个目标 localelocalizeStringArray(strings, params)翻译字符串数组并保持原有顺序内部映射为item_0、item_1… 键翻译后按序还原见 packages/sdk/src/index.tslocalizeChat(chat, params, progressCallback?, signal?)翻译聊天序列仅发送text字段、保留说话人name内部映射为chat_0…localizeHtml(html, params, progressCallback?, signal?)翻译 HTML 文档保留结构与格式recognizeLocale(text, signal?)识别文本语言0.5.0走/process/recognize端点estimate(items, signal?)成本估算0.17.0新增详见下文whoami(signal?)查询当前密钥对应的账号信息。此外ReplexicaEngine与LingoEngine作为LingoDotDevEngine的废弃别名类保留以兼容旧代码构造时会打印一次弃用警告packages/sdk/src/index.ts。三、请求管线分块、批处理与会话关联所有本地化请求最终汇聚到内部的_localizeRaw方法packages/sdk/src/index.ts其管线如下参数校验payload 与 localization 参数均经 zod schema 校验非法输入在发请求前直接抛错分块extractPayloadChunks依据idealBatchItemSize词数与batchSize条目数把大 payload 切成多个 chunk词数统计由countWordsInRecord递归完成逐块翻译对每个 chunk 调用localizeChunk发出POST {apiUrl}/process/localize请求进度回调每处理完一个 chunk 就回调progressCallback(percentage, sourceChunk, processedChunk)进度为已处理 chunk 数占比的百分数合并结果用Object.assign把各 chunk 的翻译结果合并为最终对象。请求体见localizeChunkpackages/sdk/src/index.ts包含params.fast0.6.0引入的 fast mode更快但质量可能略低、sourceLocale、targetLocale、data、可选的reference多源参考翻译0.2.0引入 multisource 能力、可选的hints0.12.0引入的翻译提示、sessionId、triggerTypecli/ci、可选的metadata.filePath以及可选的engineId。其中sessionId由createId()cuid2在引擎实例构造时生成一次同一引擎实例的多次请求共享同一会话 ID测试验证了该一致性packages/sdk/src/index.spec.ts便于服务端按会话聚合分析。四、重试机制指数退避与全抖动0.16.5为 SDK 引入了重试能力localizeChunk在 5xx 响应与网络错误时自动重试由maxRetries默认 3与retryDelayMs默认 500控制。底层实现是fetchWithRetrypackages/sdk/src/index.ts关键行为只重试瞬时错误仅对 5xx 状态码和 fetch 抛出的网络/传输错误重试4xx 等确定性错误直接返回由调用方处理指数退避 全抖动backoffDelay返回[0, retryDelayMs * 2 ** attempt]区间内的随机延迟packages/sdk/src/index.ts。全抖动让众多客户端不会在服务恢复瞬间形成同步请求波中断可感知sleep会监听 AbortSignal重试等待期间被取消会立即以Operation was aborted拒绝已中止的请求永不重试连接回收重试前调用res.body?.cancel()释放底层连接重试耗尽maxRetries次重试后仍失败则抛出 Localization request failed after exhausting retries。上述行为在 packages/sdk/src/index.spec.ts 中有完整测试覆盖500→503→200 最终成功、2 次重试后仍 500 则抛出、400 不重试、网络错误重试、maxRetries: 0不重试、已中止请求不发起。错误信息方面0.16.1改进了错误解析extractErrorMessage会解析服务端 JSON 响应中的message字段并支持_tag NotFoundError的实体缺失格式而不是直接使用 HTTP 状态文本5xx 错误附带 This may be due to temporary service issues 提示400 错误以Invalid request: ...前缀抛出packages/sdk/src/index.ts。whoami也移除了 try/catch网络错误会真实向上传播而非被静默当作未认证。这一改进在0.9.0中已开始增强 5xx 错误处理CLI 端同步受益认证失败时能展示 Invalid API key 等具体信息而非笼统的 Authentication failed。五、Locale 规范化非 BCP 47 写法在途转换0.16.4解决了一个隐蔽问题Android 格式pt-rPT与下划线格式pt_PT的 locale 能通过配置校验但原样发给 API 会被 400 拒绝。SDK 的解决方案是校验放宽、在途收紧——用localeCodeSchema.transform(normalizeLocale)构造normalizedLocaleCodeSchemapackages/sdk/src/index.ts在请求发出前把sourceLocale、targetLocale以及reference键统一转换为规范 BCP 47 形式pt-rPT→pt-PTpt_PT→pt-PT。文件路径不受影响因此 CLI 仍可保留 Android 资源目录的原始写法如values-pt-rPT/。对应的规范化测试见 packages/sdk/src/index.spec.tsAndroid-r写法、下划线写法、reference 键都会在请求体中被规范化而已经是规范形式的 locale 保持不变。六、成本估算estimate() 与 /process/estimate0.17.0为 SDK 增加了estimate()方法并同步为 CLI 提供lingo.dev run --estimate命令只估算、不翻译、不计费。CLI 侧复用与常规 run 相同的变更差量计算把按 locale 统计的源字符数发给新增的/process/estimate端点然后打印逐 locale 的成本明细。SDK 侧实现packages/sdk/src/index.ts入参为{ targetLocale, sourceChars }[]由estimateItemsSchema校验数组至少 1 项sourceChars为非负整数空数组与负字符数会在客户端直接拒绝见 packages/sdk/src/index.spec.tslocale 在发送前同样经过规范化返回CostEstimateapproximate恒为true这是基于字符→token启发式的估算而非正式报价包含totals总源字符数、预计输出 token 数、LLM 成本、本地化成本、总成本单位 USD与byLocale逐语言明细packages/sdk/src/index.ts测试用例中的示例响应结构展示了完整的成本拆分字段packages/sdk/src/index.spec.ts。import { LingoDotDevEngine } from lingo.dev/_sdk; const engine new LingoDotDevEngine({ apiKey: process.env.LINGO_API_KEY }); const estimate await engine.estimate([ { targetLocale: de, sourceChars: 400 }, { targetLocale: fr, sourceChars: 199 }, ]); console.log(estimate.totals.estimatedTotalCostUsd);七、可观测性PostHog 使用追踪的演进0.15.0引入 SDK 方法调用的 PostHog 使用追踪0.16.2将追踪身份从 email 迁移为数据库用户 ID0.17.3又为 PostHog 事件附加organization分组使 SDK 活动能出现在组织级分析中对不返回组织 ID 的 API 密钥无行为变化。实现在 packages/sdk/src/utils/observability.ts事件名定义于 packages/sdk/src/utils/tracking-events.ts如sdk.localize.start、sdk.localize.success、sdk.localize.error、sdk.recognize.*并附带tracking_version与sdk_package属性身份解析三级策略getDistinctId先调用POST {apiUrl}/whoami——个人密钥以userId数据库 ID为 distinct_id 并携带 email 特征服务密钥以keyId为 distinct_id无 email测试明确断言自动化没有真人创建者的 email 不得搭车见 packages/sdk/src/utils/observability.spec.ts旧版 API 兼容id字段。whoami失败或不可用时回退为 API 密钥的 SHA-256 哈希前缀apikey-hex16且回退结果不缓存避免一次瞬时失败污染整个进程生命周期身份缓存同一apiKey的身份解析结果缓存在identityCache中/whoami每个密钥进程内只调用一次测试见 packages/sdk/src/utils/observability.spec.ts组织分组/whoami返回organizationId时事件以groups: { organization: organizationId }上报packages/sdk/src/utils/observability.ts对应 CHANGELOG0.17.3的变更隐私开关设置环境变量DO_NOT_TRACK1时完全跳过追踪DEBUGtrue时输出追踪日志。八、取消长任务AbortController 全方法支持0.10.0为 SDK 所有公共方法引入 AbortController 支持消费者可用标准 API 取消长时间运行的本地化任务。实现细节每个公共方法接受signal?: AbortSignal参数并透传给 fetchfetch(url, { signal })_localizeRaw在批与批之间检查signal.aborted实现分块间的尽早取消测试 packages/sdk/src/abort-controller.spec.ts 验证了大 payload 在第一块后中止的场景重试等待期间的sleep同样监听 abort可中断退避所有场景下中止都以Operation was aborted错误拒绝且中止的请求不会被重试。九、工程化与供应链安全演进CHANGELOG 也记录了一系列工程与安全改进值得集成方关注0.13.0精确版本锁定所有依赖去掉^/~范围固定到精确版本防止供应链攻击依赖升级需显式审查0.17.2漏洞修补通过 dependency overrides 修复picomatch、qs、unhead/vue、postcss、ajv、launch-editor、js-yaml3.x 与 4.x、joi等一批已知漏洞0.17.1zod 升级从4.1.12升到4.4.3以满足openrouter/ai-sdk-provider的zod^4.3.5peer 依赖解决开启strict-peer-deps时npm install的ERESOLVE失败0.14.0外部化将zod移入 external 依赖避免打包体积膨胀与版本冲突0.7.20typesVersions为旧moduleResolution模式补充类型版本映射提升 TypeScript 兼容性0.7.3动态导入 jsdom将jsdom移入localizeHtml内部的动态import()避免在不需要 HTML 翻译的场景承担其体积与解析开销packages/sdk/src/index.ts。十、能力时间线总览版本关键变更能力归属0.1.0从 CLI 抽取 API 调用为 SDK架构0.2.0multisource 多源参考翻译翻译能力0.4.0格式特定方法对象/文本/HTML/聊天API 面0.5.0recognizeLocalelocalizeHtmlAPI 面0.6.0fast mode翻译能力0.7.0batchLocalizeTextAPI 面0.7.11Replexica 更名为 Lingo.dev品牌0.7.23自动源 locale 检测翻译能力0.7.42并行处理性能0.8.0接入 compiler生态0.9.0增强 5xx 错误处理可靠性0.10.0AbortController 取消支持可靠性0.11.0localizeStringArrayAPI 面0.12.0hints 翻译提示翻译能力0.12.6xcode-xcstrings-v2 bucket 类型格式支持0.13.0依赖精确版本锁定安全0.15.0PostHog 使用追踪可观测性0.16.0统一 api.lingo.dev X-API-Key engineId架构0.16.1JSON 错误解析、whoami 网络错误传播可靠性0.16.2追踪身份迁移到数据库用户 ID可观测性0.16.4locale 在途规范化BCP 47兼容性0.16.5指数退避重试maxRetries/retryDelayMs可靠性0.17.0estimate()成本估算成本管理0.17.1zod 升级修复 ERESOLVE工程化0.17.2依赖漏洞修补安全0.17.3PostHog 组织分组可观测性十一、如何在项目中使用SDK 以独立包发布按 packages/sdk/README.md 安装即可npm i lingo.dev典型用法创建带 API 密钥的引擎实例调用localizeObject翻译结构化内容传入progressCallback感知进度、AbortSignal支持取消import { LingoDotDevEngine } from lingo.dev/sdk; const engine new LingoDotDevEngine({ apiKey: process.env.LINGO_API_KEY, engineId: eng_xxx, // 可选0.16.0 起支持 batchSize: 25, // 默认 25最大 250 idealBatchItemSize: 250, // 默认 250最大 2500 maxRetries: 3, // 默认 30 关闭重试 retryDelayMs: 500, // 默认 500ms }); const controller new AbortController(); const result await engine.localizeObject( { greeting: Hello, world! }, { sourceLocale: en, targetLocale: es, hints: { greeting: [keep it casual] } }, (progress) console.log(${progress}%), controller.signal, ); // { greeting: ¡Hola, mundo! }需要留意engineId在0.16.0中替代了此前的vNext配置maxRetries/retryDelayMs自0.16.5起可用estimate()自0.17.0起可用。若想深入底层实现可直接阅读 packages/sdk/src/index.ts 与对应测试 packages/sdk/src/index.spec.ts、packages/sdk/src/abort-controller.spec.ts、packages/sdk/src/utils/observability.spec.ts。【免费下载链接】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），仅供参考
从 @lingo.dev/_sdk 变更日志看 Lingo.dev 本地化 SDK 的核心能力与工程演进
从 lingo.dev/_sdk 变更日志看 Lingo.dev 本地化 SDK 的核心能力与工程演进【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica本篇技术指南以 Replexica 仓库现 Lingo.dev中 packages/sdk/CHANGELOG.md 的版本演进为脉络结合packages/sdk的真实源码实现系统讲解 LingoDotDevEngine 的配置参数、请求管线、重试与错误处理、locale 规范化、成本估算、可观测性及取消机制等核心能力。读完本文你将理解 SDK 每个关键特性的底层实现原理并能参照源码在真实项目中正确配置与使用它。一、SDK 是什么从replexica/sdk到lingo.dev/_sdkCHANGELOG 记录了这个包的完整生命周期。在0.1.0PR #142中项目将API 调用从 CLI 中抽取为独立的 SDK 包0.7.11PR #419时项目完成品牌更名Replexica is now Lingo.dev包名也从replexica/sdk统一为lingo.dev/_sdk同时依赖的replexica/spec也同步更名为lingo.dev/_spec。当前包配置见 packages/sdk/package.json包名lingo.dev/_sdk版本0.17.3协议 Apache-2.0产物同时提供build/index.mjsESM、build/index.cjsCJS与build/index.d.ts类型sideEffects: false便于 tree-shaking运行时依赖lingo.dev/_specworkspace 内部依赖负责 locale 校验与规范化、zod参数校验、posthog-node使用追踪、jsdomHTML 本地化、paralleldrive/cuid2会话 ID 生成。二、核心类 LingoDotDevEngine 与引擎参数SDK 的核心是LingoDotDevEngine类定义于 packages/sdk/src/index.ts。它的全部请求都通过统一的api.lingo.dev域名与X-API-Key请求头认证0.16.0将旧版分散端点统一迁移到该架构见 packages/sdk/src/index.ts。2.1 引擎参数engineParamsSchema引擎构造参数由engineParamsSchema校验packages/sdk/src/index.ts完整参数如下参数类型默认值约束说明apiKeystring—必填平台 API 密钥用于X-API-Key认证apiUrlstringhttps://api.lingo.dev合法 URLAPI 基础地址batchSizenumber25整数1 ≤ n ≤ 250单个请求批次最多容纳的翻译条目数idealBatchItemSizenumber250整数1 ≤ n ≤ 2500单个批次的理想词数上限engineIdstring可选—指定翻译引擎 ID0.16.0起由旧vNext自动迁移maxRetriesnumber3整数≥ 0瞬时失败5xx/网络错误后的最大重试次数0关闭重试retryDelayMsnumber500整数≥ 0指数退避的基础延迟毫秒CHANGELOG 中0.7.1曾将默认batchSize调低以避免触发平台限流0.16.0新增engineId并在请求体中透传测试见 packages/sdk/src/index.spec.ts。所有公共方法调用前会记录LOCALIZE_START等追踪事件0.15.0引入。2.2 内容格式与配套方法0.4.0为 SDK 添加了格式特定方法0.5.0增加recognizeLocale与localizeHtml0.7.0增加batchLocalizeText0.11.0增加localizeStringArray。当前 SDK 提供的公共 API 如下全部支持 AbortSignal 取消localizeObject(obj, params, progressCallback?, signal?)翻译一个 JS 对象中的字符串值保持结构不变localizeText(text, params, progressCallback?, signal?)翻译单个文本batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)将同一文本并行翻译到多个目标 localelocalizeStringArray(strings, params)翻译字符串数组并保持原有顺序内部映射为item_0、item_1… 键翻译后按序还原见 packages/sdk/src/index.tslocalizeChat(chat, params, progressCallback?, signal?)翻译聊天序列仅发送text字段、保留说话人name内部映射为chat_0…localizeHtml(html, params, progressCallback?, signal?)翻译 HTML 文档保留结构与格式recognizeLocale(text, signal?)识别文本语言0.5.0走/process/recognize端点estimate(items, signal?)成本估算0.17.0新增详见下文whoami(signal?)查询当前密钥对应的账号信息。此外ReplexicaEngine与LingoEngine作为LingoDotDevEngine的废弃别名类保留以兼容旧代码构造时会打印一次弃用警告packages/sdk/src/index.ts。三、请求管线分块、批处理与会话关联所有本地化请求最终汇聚到内部的_localizeRaw方法packages/sdk/src/index.ts其管线如下参数校验payload 与 localization 参数均经 zod schema 校验非法输入在发请求前直接抛错分块extractPayloadChunks依据idealBatchItemSize词数与batchSize条目数把大 payload 切成多个 chunk词数统计由countWordsInRecord递归完成逐块翻译对每个 chunk 调用localizeChunk发出POST {apiUrl}/process/localize请求进度回调每处理完一个 chunk 就回调progressCallback(percentage, sourceChunk, processedChunk)进度为已处理 chunk 数占比的百分数合并结果用Object.assign把各 chunk 的翻译结果合并为最终对象。请求体见localizeChunkpackages/sdk/src/index.ts包含params.fast0.6.0引入的 fast mode更快但质量可能略低、sourceLocale、targetLocale、data、可选的reference多源参考翻译0.2.0引入 multisource 能力、可选的hints0.12.0引入的翻译提示、sessionId、triggerTypecli/ci、可选的metadata.filePath以及可选的engineId。其中sessionId由createId()cuid2在引擎实例构造时生成一次同一引擎实例的多次请求共享同一会话 ID测试验证了该一致性packages/sdk/src/index.spec.ts便于服务端按会话聚合分析。四、重试机制指数退避与全抖动0.16.5为 SDK 引入了重试能力localizeChunk在 5xx 响应与网络错误时自动重试由maxRetries默认 3与retryDelayMs默认 500控制。底层实现是fetchWithRetrypackages/sdk/src/index.ts关键行为只重试瞬时错误仅对 5xx 状态码和 fetch 抛出的网络/传输错误重试4xx 等确定性错误直接返回由调用方处理指数退避 全抖动backoffDelay返回[0, retryDelayMs * 2 ** attempt]区间内的随机延迟packages/sdk/src/index.ts。全抖动让众多客户端不会在服务恢复瞬间形成同步请求波中断可感知sleep会监听 AbortSignal重试等待期间被取消会立即以Operation was aborted拒绝已中止的请求永不重试连接回收重试前调用res.body?.cancel()释放底层连接重试耗尽maxRetries次重试后仍失败则抛出 Localization request failed after exhausting retries。上述行为在 packages/sdk/src/index.spec.ts 中有完整测试覆盖500→503→200 最终成功、2 次重试后仍 500 则抛出、400 不重试、网络错误重试、maxRetries: 0不重试、已中止请求不发起。错误信息方面0.16.1改进了错误解析extractErrorMessage会解析服务端 JSON 响应中的message字段并支持_tag NotFoundError的实体缺失格式而不是直接使用 HTTP 状态文本5xx 错误附带 This may be due to temporary service issues 提示400 错误以Invalid request: ...前缀抛出packages/sdk/src/index.ts。whoami也移除了 try/catch网络错误会真实向上传播而非被静默当作未认证。这一改进在0.9.0中已开始增强 5xx 错误处理CLI 端同步受益认证失败时能展示 Invalid API key 等具体信息而非笼统的 Authentication failed。五、Locale 规范化非 BCP 47 写法在途转换0.16.4解决了一个隐蔽问题Android 格式pt-rPT与下划线格式pt_PT的 locale 能通过配置校验但原样发给 API 会被 400 拒绝。SDK 的解决方案是校验放宽、在途收紧——用localeCodeSchema.transform(normalizeLocale)构造normalizedLocaleCodeSchemapackages/sdk/src/index.ts在请求发出前把sourceLocale、targetLocale以及reference键统一转换为规范 BCP 47 形式pt-rPT→pt-PTpt_PT→pt-PT。文件路径不受影响因此 CLI 仍可保留 Android 资源目录的原始写法如values-pt-rPT/。对应的规范化测试见 packages/sdk/src/index.spec.tsAndroid-r写法、下划线写法、reference 键都会在请求体中被规范化而已经是规范形式的 locale 保持不变。六、成本估算estimate() 与 /process/estimate0.17.0为 SDK 增加了estimate()方法并同步为 CLI 提供lingo.dev run --estimate命令只估算、不翻译、不计费。CLI 侧复用与常规 run 相同的变更差量计算把按 locale 统计的源字符数发给新增的/process/estimate端点然后打印逐 locale 的成本明细。SDK 侧实现packages/sdk/src/index.ts入参为{ targetLocale, sourceChars }[]由estimateItemsSchema校验数组至少 1 项sourceChars为非负整数空数组与负字符数会在客户端直接拒绝见 packages/sdk/src/index.spec.tslocale 在发送前同样经过规范化返回CostEstimateapproximate恒为true这是基于字符→token启发式的估算而非正式报价包含totals总源字符数、预计输出 token 数、LLM 成本、本地化成本、总成本单位 USD与byLocale逐语言明细packages/sdk/src/index.ts测试用例中的示例响应结构展示了完整的成本拆分字段packages/sdk/src/index.spec.ts。import { LingoDotDevEngine } from lingo.dev/_sdk; const engine new LingoDotDevEngine({ apiKey: process.env.LINGO_API_KEY }); const estimate await engine.estimate([ { targetLocale: de, sourceChars: 400 }, { targetLocale: fr, sourceChars: 199 }, ]); console.log(estimate.totals.estimatedTotalCostUsd);七、可观测性PostHog 使用追踪的演进0.15.0引入 SDK 方法调用的 PostHog 使用追踪0.16.2将追踪身份从 email 迁移为数据库用户 ID0.17.3又为 PostHog 事件附加organization分组使 SDK 活动能出现在组织级分析中对不返回组织 ID 的 API 密钥无行为变化。实现在 packages/sdk/src/utils/observability.ts事件名定义于 packages/sdk/src/utils/tracking-events.ts如sdk.localize.start、sdk.localize.success、sdk.localize.error、sdk.recognize.*并附带tracking_version与sdk_package属性身份解析三级策略getDistinctId先调用POST {apiUrl}/whoami——个人密钥以userId数据库 ID为 distinct_id 并携带 email 特征服务密钥以keyId为 distinct_id无 email测试明确断言自动化没有真人创建者的 email 不得搭车见 packages/sdk/src/utils/observability.spec.ts旧版 API 兼容id字段。whoami失败或不可用时回退为 API 密钥的 SHA-256 哈希前缀apikey-hex16且回退结果不缓存避免一次瞬时失败污染整个进程生命周期身份缓存同一apiKey的身份解析结果缓存在identityCache中/whoami每个密钥进程内只调用一次测试见 packages/sdk/src/utils/observability.spec.ts组织分组/whoami返回organizationId时事件以groups: { organization: organizationId }上报packages/sdk/src/utils/observability.ts对应 CHANGELOG0.17.3的变更隐私开关设置环境变量DO_NOT_TRACK1时完全跳过追踪DEBUGtrue时输出追踪日志。八、取消长任务AbortController 全方法支持0.10.0为 SDK 所有公共方法引入 AbortController 支持消费者可用标准 API 取消长时间运行的本地化任务。实现细节每个公共方法接受signal?: AbortSignal参数并透传给 fetchfetch(url, { signal })_localizeRaw在批与批之间检查signal.aborted实现分块间的尽早取消测试 packages/sdk/src/abort-controller.spec.ts 验证了大 payload 在第一块后中止的场景重试等待期间的sleep同样监听 abort可中断退避所有场景下中止都以Operation was aborted错误拒绝且中止的请求不会被重试。九、工程化与供应链安全演进CHANGELOG 也记录了一系列工程与安全改进值得集成方关注0.13.0精确版本锁定所有依赖去掉^/~范围固定到精确版本防止供应链攻击依赖升级需显式审查0.17.2漏洞修补通过 dependency overrides 修复picomatch、qs、unhead/vue、postcss、ajv、launch-editor、js-yaml3.x 与 4.x、joi等一批已知漏洞0.17.1zod 升级从4.1.12升到4.4.3以满足openrouter/ai-sdk-provider的zod^4.3.5peer 依赖解决开启strict-peer-deps时npm install的ERESOLVE失败0.14.0外部化将zod移入 external 依赖避免打包体积膨胀与版本冲突0.7.20typesVersions为旧moduleResolution模式补充类型版本映射提升 TypeScript 兼容性0.7.3动态导入 jsdom将jsdom移入localizeHtml内部的动态import()避免在不需要 HTML 翻译的场景承担其体积与解析开销packages/sdk/src/index.ts。十、能力时间线总览版本关键变更能力归属0.1.0从 CLI 抽取 API 调用为 SDK架构0.2.0multisource 多源参考翻译翻译能力0.4.0格式特定方法对象/文本/HTML/聊天API 面0.5.0recognizeLocalelocalizeHtmlAPI 面0.6.0fast mode翻译能力0.7.0batchLocalizeTextAPI 面0.7.11Replexica 更名为 Lingo.dev品牌0.7.23自动源 locale 检测翻译能力0.7.42并行处理性能0.8.0接入 compiler生态0.9.0增强 5xx 错误处理可靠性0.10.0AbortController 取消支持可靠性0.11.0localizeStringArrayAPI 面0.12.0hints 翻译提示翻译能力0.12.6xcode-xcstrings-v2 bucket 类型格式支持0.13.0依赖精确版本锁定安全0.15.0PostHog 使用追踪可观测性0.16.0统一 api.lingo.dev X-API-Key engineId架构0.16.1JSON 错误解析、whoami 网络错误传播可靠性0.16.2追踪身份迁移到数据库用户 ID可观测性0.16.4locale 在途规范化BCP 47兼容性0.16.5指数退避重试maxRetries/retryDelayMs可靠性0.17.0estimate()成本估算成本管理0.17.1zod 升级修复 ERESOLVE工程化0.17.2依赖漏洞修补安全0.17.3PostHog 组织分组可观测性十一、如何在项目中使用SDK 以独立包发布按 packages/sdk/README.md 安装即可npm i lingo.dev典型用法创建带 API 密钥的引擎实例调用localizeObject翻译结构化内容传入progressCallback感知进度、AbortSignal支持取消import { LingoDotDevEngine } from lingo.dev/sdk; const engine new LingoDotDevEngine({ apiKey: process.env.LINGO_API_KEY, engineId: eng_xxx, // 可选0.16.0 起支持 batchSize: 25, // 默认 25最大 250 idealBatchItemSize: 250, // 默认 250最大 2500 maxRetries: 3, // 默认 30 关闭重试 retryDelayMs: 500, // 默认 500ms }); const controller new AbortController(); const result await engine.localizeObject( { greeting: Hello, world! }, { sourceLocale: en, targetLocale: es, hints: { greeting: [keep it casual] } }, (progress) console.log(${progress}%), controller.signal, ); // { greeting: ¡Hola, mundo! }需要留意engineId在0.16.0中替代了此前的vNext配置maxRetries/retryDelayMs自0.16.5起可用estimate()自0.17.0起可用。若想深入底层实现可直接阅读 packages/sdk/src/index.ts 与对应测试 packages/sdk/src/index.spec.ts、packages/sdk/src/abort-controller.spec.ts、packages/sdk/src/utils/observability.spec.ts。【免费下载链接】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），仅供参考
