@thor123141245r/ai-translate

v1.0.5

Published

3 months ago

本仓库是 npm 包 `@thor123141245r/ai-translate` 的源码。

0High
0Medium
0Low

thor123141245r

ai-translate：可复用的 AI 翻译 CLI 与 i18n JSON 批量翻译

本仓库是 npm 包 @thor123141245r/ai-translate 的源码。

它提供两类能力：

通用文件翻译：把任意文本文件分块后交给大模型翻译（适合 Markdown、技术文档、代码注释等）
i18n JSON 翻译：以 en.json 为标准，批量生成/补齐其他语言 JSON（严格保留 key 与结构，只翻译字符串 value）

核心设计原则是：结构在本地处理，模型只做翻译。避免把大体量结构化文件整段塞进模型上下文导致不稳定。

功能概览

CLI：
- ai-translate 通用文件翻译
- ai-translate i18n i18n JSON 批量翻译
可复用模块：AiTranslateTransform、TextSplitterStream、translateI18nDir
配置：.ai-translate.json（支持环境变量覆盖）
兼容多模型提供方：ollama / openai / openai-compatible / anthropic / mistral / deepseek（通过 Vercel AI SDK）
i18n 专用能力：
- 只翻译 value，不改 key 与结构
- 批处理调用，避免上下文混乱
- 占位符保护（例如 {{name}}、{name}、%s）
- 本地缓存，减少重复翻译

Codex Skill

本仓库内置了一个面向 Next.js + JSON i18n 的 Codex Skill，适用于“以 en.json 为标准批量补齐或生成其他语言 JSON”的场景：

Skill 目录：skills/nextjs-json-i18n-ai-translate/
Skill 名称：nextjs-json-i18n-ai-translate
核心能力：只翻译字符串 value，不改 key 与结构，支持 fill/overwrite/prune 模式

安装到 Codex CLI

目标：把 Skill 目录放到 ~/.codex/skills/ 下。

方式 A：从 npm 包解压安装（推荐，确保和发布版本一致）

npm pack @thor123141245r/ai-translate
tar -xzf thor123141245r-ai-translate-*.tgz
mkdir -p ~/.codex/skills
cp -R package/skills/nextjs-json-i18n-ai-translate ~/.codex/skills/

方式 B：从源码仓库复制安装（适合本地开发）

mkdir -p ~/.codex/skills
cp -R skills/nextjs-json-i18n-ai-translate ~/.codex/skills/

安装完成后，重启 Codex CLI（或重新打开会话）使其加载新 Skill。

安装到 Cursor

Cursor 不直接识别 Codex 的 Skill 目录结构，但可以把它当作“项目规则”使用：

在 Cursor 的 Rules 或 Project Rules 中新增一条规则，命名为 nextjs-json-i18n-ai-translate
将 skills/nextjs-json-i18n-ai-translate/SKILL.md 的内容粘贴进去并保存
在对话中明确说明你的目标与目录范围（见下方用法示例）

其他主流编辑器

思路基本一致：把 skills/nextjs-json-i18n-ai-translate/SKILL.md 作为“项目级 AI 规则或提示词模板”保存，然后在需要时点名调用。

用法（建议直接这样对 AI 说）

如果没有自动触发，直接在对话里点名 nextjs-json-i18n-ai-translate。

示例 1：补齐缺失翻译（推荐默认）

“使用 nextjs-json-i18n-ai-translate：把 ./src/messages 下的 en.json 翻译到 fr,de，先 --dry 预览统计，再用 mode=fill 写入文件。”

示例 2：全量重翻（谨慎）

“使用 nextjs-json-i18n-ai-translate：对 ./public/locales 做全量重翻到 ja，先 dry，再 mode=overwrite 执行。”

注意：

翻译仍需要配置可用的模型提供方与密钥（见下方“选择模型提供方”）
默认建议先 --dry，确认统计后再执行真实写入

CLI

通用翻译参数

| 参数 | 作用 | 备注 | | --- | --- | --- | | -h, --help | 输出帮助信息 | | | -v, --version | 输出版本号 | | | -c, --config DIR | 指定配置目录或配置文件路径 | 读取 .ai-translate.json | | -f, --from LANG | 源语言 | 可用英文名或 BCP47 代码 | | -t, --to LANG | 目标语言 | 可用英文名或 BCP47 代码 | | -i, --input FILE | 输入文件路径 | | | -o, --output FILE | 输出文件路径 | | | --format FORMAT | 指定输入格式 | cpp/go/java/js/php/proto/python/rst/ruby/rust/scala/swift/markdown/latex/html | | set KEY VALUE | 写入配置项 | 见配置说明 | | i18n | i18n JSON 批量翻译 | 只翻译 value |

配置项

| 参数 | 作用 | 默认值 | | --- | --- | --- | | provider | 模型提供方 | openai-compatible | | model | 模型名称 | 取决于 provider（见下表） | | apiKey | 模型 API Key | 空 | | baseUrl | 模型 Base URL | 空 | | temperature | 模型温度 | 0.1 | | maxRetries | 最大重试次数 | 10 | | chunkSize | 文本分块大小 | 1000 |

各 provider 默认模型

| provider | 默认 model | | --- | --- | | openai-compatible | gpt-4o | | openai | gpt-4o-mini | | anthropic | claude-3-5-haiku-20241022 | | mistral | ministral-8b | | deepseek | deepseek-reasoner | | ollama | qwen2.5:7b |

快速开始

npx / pnpx 运行

npx @thor123141245r/ai-translate --help
pnpx @thor123141245r/ai-translate --help

选择模型提供方（要真正翻译必须配置）

本工具需要能访问某个大模型提供方；默认使用 openai-compatible + gpt-4o。如果未提供可用的 baseUrl/apiKey（例如未设置 AI_TRANSLATE_BASE_URL 与 AI_TRANSLATE_API_KEY），翻译调用会失败。

下面任选一种方式：

方式 A：OpenAI（云）

先配置环境变量：

export OPENAI_API_KEY="你的key"

再设置 provider（会写入 .ai-translate.json）：

npx @thor123141245r/ai-translate set provider openai

方式 B：Anthropic（云）

export ANTHROPIC_API_KEY="你的key"
npx @thor123141245r/ai-translate set provider anthropic

方式 C：Mistral（云）

export MISTRAL_API_KEY="你的key"
npx @thor123141245r/ai-translate set provider mistral

方式 D：DeepSeek（云）

export DEEPSEEK_API_KEY="你的key"
npx @thor123141245r/ai-translate set provider deepseek

方式 E：Ollama（本地）

启动 Ollama，并确保 OLLAMA_BASE_URL 可访问（默认 http://127.0.0.1:11434，内部会自动补齐 /v1）。

export OLLAMA_BASE_URL="http://127.0.0.1:11434"
npx @thor123141245r/ai-translate set provider ollama

方式 F：OpenAI Compatible（市面大多数模型）

只要模型提供方支持 OpenAI Compatible API，就可以直接接入：

export AI_TRANSLATE_API_KEY="你的key"
export AI_TRANSLATE_BASE_URL="https://your-compatible-endpoint"
npx @thor123141245r/ai-translate set provider openai-compatible
npx @thor123141245r/ai-translate set model your-model-name

说明：

AI_TRANSLATE_BASE_URL 若未包含 /v1，会自动补齐
也可改用 OPENAI_API_KEY / OPENAI_BASE_URL（同样会被识别）
openai-compatible 必须提供 baseUrl

补充说明：

AI_TRANSLATE_API_KEY 会覆盖各 provider 的 *_API_KEY
AI_TRANSLATE_BASE_URL 会覆盖各 provider 的 *_BASE_URL 或 OLLAMA_BASE_URL
baseUrl 若未包含 /v1，会自动补齐

本地开发

npm install
npm run build

用法

通用文件翻译

# 翻译文件
node dist/bin/ai-translate.js -f Spanish -t English -i input.md -o output.md

# 从 stdin 读取，并使用当前目录的配置文件
echo "translate" | node dist/bin/ai-translate.js -f en -t en -c .

工作方式：

通过 --format 或文件扩展名推断格式
将输入按 chunkSize 分块（默认 1000）
对每个分块使用统一 Prompt 调用模型翻译
尽量保留原始空白与结构

i18n JSON 翻译（以 en.json 为标准）

不要把 en.json 当纯文本翻译，这很容易破坏 JSON 语法或把 key 翻译掉。请使用 i18n 子命令：只翻译叶子字符串 value。

# 用 npx 直接运行
npx @thor123141245r/ai-translate i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru

# 默认 mode=fill：保留已有翻译，只补齐缺失项
node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en

# 指定目标语言（即使目标文件不存在也会生成）
node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru,de

# 覆盖重翻（慎用）
node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru --mode overwrite

# 仅预览统计（不写文件）
node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --dry

工作方式：

从 --base 目录读取源文件（默认 {source}.json，例如 en.json）
目标文件默认 {lang}.json（例如 ru.json）
本地解析 JSON，提取所有“叶子字符串 value”作为待翻译单元
通过批处理调用模型（模型不会拿到整份 JSON）
按原 key 路径写回翻译结果，严格不改 key
默认在目录下写入缓存 .ai-translate.cache.json，减少重复翻译

i18n 常用参数：

--mode fill：只补齐缺失项（推荐默认）
--mode overwrite：重翻全部字符串 value
--mode prune：对齐结构并清理多余 key
--checkpoint off|batch：写入策略；batch 表示每个 batch 翻译完成后就写回目标 JSON（更适合长任务与可中断场景）；当 mode=overwrite 且未显式传 --checkpoint 时默认启用 batch
--quiet：关闭执行过程中的进度日志（仍会输出最终汇总）
--batchMaxItems / --batchMaxChars：控制批处理大小
--cache：自定义缓存文件名（相对于 --base）

进度日志说明：

非 --dry 模式下会输出按 target 与 batch 的进度日志（默认走 stderr），避免长时间无反馈
最终汇总统计仍会输出到 stdout，便于脚本解析

配置说明

配置文件名为 .ai-translate.json，可通过命令行写入：

node dist/bin/ai-translate.js set provider ollama
node dist/bin/ai-translate.js set apiKey YOUR_API_KEY
node dist/bin/ai-translate.js set model qwen2.5:7b
node dist/bin/ai-translate.js set chunkSize 1000

环境变量优先级

优先级：环境变量 > 配置文件 > 默认值。

通用环境变量：

AI_TRANSLATE_API_KEY
AI_TRANSLATE_BASE_URL

提供方环境变量：

OPENAI_API_KEY / OPENAI_BASE_URL
ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL
MISTRAL_API_KEY / MISTRAL_BASE_URL
DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL
OLLAMA_BASE_URL
OPENAI_API_KEY / OPENAI_BASE_URL 也可用于 openai-compatible