@4399ywkf/i18n
v1.0.0
Published
AI 自动翻译 i18n locale JSON 与 Markdown 文档(fork 自 lobe-i18n)
Downloads
331
Readme
@4399ywkf/i18n
用 AI 自动翻译 i18n locale JSON 和 Markdown 文档。
源自 lobe-i18n(@lobehub/[email protected],MIT),现已独立维护,不再跟随上游同步。主要变化:
- 去掉
ink/react/@lobehub/cli-ui,依赖树里不再有@lobehub/*;终端提示全部改为中文。 - 默认使用流式输出,进度按「已翻译条目 / 总条目」实时计算(见下文「进度」)。
- 修复上游 1.27.0 未开启
saveImmediately时 locale 译文被丢弃、mdast 模式 Markdown 输出仍为原文等问题。 - 命令名
lobe-i18n→ywkf-i18n,用户目录配置保存在ywkf-i18n下(与 lobe-i18n 互不影响)。 modelName允许填写非 OpenAI 模型(如内部模型网关),未知模型的上下文长度按默认模型计算,可用splitToken覆盖。
安装
pnpm add -D @4399ywkf/i18nNode.js >= 18
使用
在项目根目录创建 .i18nrc.js(支持 cosmiconfig 的所有格式,如 .i18nrc.json、package.json 中的 i18n 字段):
const { defineConfig } = require("@4399ywkf/i18n");
module.exports = defineConfig({
entry: "locales/zh-CN",
entryLocale: "zh-CN",
output: "locales",
outputLocales: ["en-US"],
});配置 API Key(二选一):
- 环境变量(支持项目根目录
.env):OPENAI_API_KEY,可选OPENAI_PROXY_URL指定 OpenAI 兼容网关地址 - 交互式保存到用户目录:
ywkf-i18n -o
环境变量优先于 -o 保存的配置。
ywkf-i18n # 翻译 locale 文件(同 ywkf-i18n locale)
ywkf-i18n md # 翻译 Markdown 文件
ywkf-i18n lint # 检查翻译文件的语言是否正确
ywkf-i18n --with-md # 同时翻译 locale 和 Markdown
ywkf-i18n -c ./i18n.config.js # 指定配置文件
ywkf-i18n -o # 交互式设置 API Key / 代理地址在 ywkf 项目里也可以通过 ywkf-cli i18n [...args] 调用,参数原样透传。
进度
终端中每个文件显示一块原地刷新的进度,完成后收起为一行结果:
[2/3] locales/en-US/common.json zh-CN → en-US
⠇ 45% ███████████░░░░░░░░░░░░░ 19/42 条 · 2.8s
✔ locales/en-US/common.json 42 条 · 5.4s · 约 974 tokens
✔ 翻译完成:3 个文件 · 约 1,329 tokens · 7.0s- locale JSON / Markdown mdast 模式:发请求前就知道要翻译多少条,流式返回时实时统计已完成的条目,百分比是精确的。
- Markdown string 模式:输出是整段文本,按已生成的 token 数相对原文估算,显示为「约 xx%」,完成前最多 99%。
- 非流式(
stream: false):只在分块完成时前进,等待期间显示已用时间。 - CI 等非终端环境不输出进度,每个文件完成后输出一行结果。
token 数由本地按 tokenizer 估算,仅供参考。
文件结构
- 单文件:
entry指向 JSON 文件,如locales/zh-CN.json,输出为locales/en-US.json。 - 文件夹:
entry指向目录,如locales/zh-CN,按相同的相对路径输出到locales/en-US/。
已有的翻译只会补齐缺失的 key,不会重复翻译。
Locale 配置
| 属性 | 必填 | 类型 | 默认值 | 说明 |
| --------------- | ---- | ---------- | ------------ | ------------------------------------------------------ |
| entry | ✓ | string | - | 入口文件或文件夹 |
| entryLocale | ✓ | string | - | 作为翻译源的语言 |
| output | ✓ | string | - | 翻译结果的存放目录 |
| outputLocales | ✓ | string[] | - | 需要翻译到的语言 |
| modelName | | string | gpt-5-mini | 使用的模型 |
| keyStyle | | string | nested | 点分隔 key 的处理方式:nested、flat、auto |
| reference | | string | - | 补充上下文,提升翻译准确度 |
| saveImmediately | | boolean | false | 每个分块完成后立即写盘 |
| splitToken | | number | 自动计算 | 按 token 数切分 JSON |
| stream | | boolean | true | 流式输出以计算精确进度;模型网关不支持流式时设为 false |
| temperature | | number | 0 | 采样温度 |
| topP | | number | - | 核采样阈值 |
| concurrency | | number | 5 | 并发请求数 |
| experimental | | object | {} | jsonMode: true 开启模型强制 JSON 输出(需模型支持) |
| markdown | | object | - | 见下文 |
Markdown 配置
| 属性 | 必填 | 类型 | 默认值 | 说明 |
| ---------------- | ---- | ------------------------------- | ---------------------------- | ------------------------------------- |
| entry | ✓ | string[] | [] | 入口文件或目录,支持 glob |
| entryLocale | | string | 继承外层 | 作为翻译源的语言 |
| entryExtension | | string | .md | 入口文件扩展名 |
| exclude | | string[] | [] | 排除的文件,支持 glob |
| outputLocales | | string[] | 继承外层 | 需要翻译到的语言 |
| outputExtensions | | function | (locale) => '.{locale}.md' | 生成输出文件扩展名 |
| mode | | 'string'/'mdast'/function | string | string 整段翻译;mdast 按语法树翻译文本节点 |
| translateCode | | boolean | false | mdast 模式下是否翻译代码块 |
| includeMatter | | boolean | false | 是否翻译 front matter |
已存在的目标 Markdown 文件会被跳过。
License
MIT。保留 lobe-i18n 原始版权声明,见 LICENSE。
