项目介绍
translator-ai
快速高效的JSON国际化翻译工具，支持多个AI提供商（Google Gemini、OpenAI及Ollama/DeepSeek），具有智能缓存、多文件去重以及MCP集成功能。
特性
- 多个AI提供商：选择Google Gemini、OpenAI（云端）或Ollama/DeepSeek（本地）进行翻译
- 多文件支持：处理多个文件时自动去重以节省API调用次数
- 增量缓存：仅翻译新内容或修改过的字符串，大幅减少API调用次数
- 批量处理：智能分批翻译以优化性能
- 路径保存：保持精确的JSON结构，包括嵌套对象和数组
- 跨平台：在Windows、macOS和Linux上运行，并自动检测缓存目录
- 开发者友好：内置性能统计和进度指示器
- 成本效益：通过智能缓存和去重最小化API使用
- 语言检测：自动检测源语言而不是假设为英语
- 多种目标语言：一次命令翻译成多种语言
- 翻译元数据：可选地在输出文件中包含翻译详情以便追踪
- 干跑模式：预览要翻译的内容而不进行API调用
- 格式保存：保持URL、电子邮件、日期、数字和模板变量不变
安装
全局安装（推荐）
npm install -g translator-ai
本地安装
npm install translator-ai
配置
方案1：Google Gemini API（云端）
在项目根目录创建.env文件或设置环境变量：
GEMINI_API_KEY=your_gemini_api_key_here
从Google AI Studio获取您的API密钥。
方案2：OpenAI API（云端）
在项目根目录创建.env文件或设置环境变量：
OPENAI_API_KEY=your_openai_api_key_here
从OpenAI 平台获取您的API密钥。
方案3：Ollama与DeepSeek-R1（本地）
无需API费用的完全本地翻译：
- 安装 Ollama
- 拉取DeepSeek-R1模型：
ollama pull deepseek-r1:latest - 使用
--provider ollama标志：translator-ai source.json -l es -o spanish.json --provider ollama
使用方法
基本用法
# 翻译单个文件
translator-ai source.json -l es -o spanish.json
# 多文件翻译并去重
translator-ai src/locales/en/*.json -l es -o "{dir}/{name}.{lang}.json"
# 使用通配符模式
translator-ai "src/**/*.en.json" -l fr -o "{dir}/{name}.fr.json"
命令行选项
translator-ai <inputFiles...> [options]
参数：
inputFiles 源JSON文件路径或通配符模式
选项：
-l, --lang <langCodes> 目标语言代码，多个用逗号分隔
-o, --output <pattern> 输出文件路径或模式
--stdout 输出到标准输出而非文件
--stats 显示详细的性能统计数据
--no-cache 禁用增量翻译缓存
--cache-file <path> 自定义缓存文件路径
--provider <type> 翻译提供商：gemini、openai 或 ollama（默认：gemini）
--ollama-url <url> Ollama API URL（默认：http://localhost:11434）
--ollama-model <model> Ollama 模型名称（默认：deepseek-r1:latest）
--gemini-model <model> Gemini 模型名称（默认：gemini-2.0-flash-lite）
--openai-model <model> OpenAI 模型名称（默认：gpt-4o-mini）
--list-providers 列出可用的翻译提供商
--verbose 启用调试输出
--detect-source 自动检测源语言而不是假设为英语
--dry-run 预览要翻译的内容而不进行API调用
--preserve-formats 保持URL、电子邮件、数字、日期和其他格式
--metadata 在输出文件中添加翻译元数据（可能会破坏某些i18n解析器）
--sort-keys 按字母顺序排序输出JSON键
--check-keys 验证所有源键是否存在于输出中（如果缺少键则退出错误）
-h, --help 显示帮助信息
-V, --version 显示版本信息
输出模式变量（用于多个文件）：
{dir} - 原始目录路径
{name} - 去除扩展名的原始文件名
{lang} - 目标语言代码
示例
翻译单个文件
translator-ai en.json -l es -o es.json
使用模式翻译多个文件
# 目录中的所有JSON文件
translator-ai locales/en/*.json -l es -o "locales/es/{name}.json"
# 递归通配符模式
translator-ai "src/**/en.json" -l fr -o "{dir}/fr.json"
# 多个特定文件
translator-ai file1.json file2.json file3.json -l de -o "{name}.de.json"
带去重节省的翻译
# 显示统计信息，包括节省了多少API调用
translator-ai src/i18n/*.json -l ja -o "{dir}/{name}.{lang}.json" --stats
输出到标准输出（适用于管道）
translator-ai en.json -l de --stdout > de.json
使用jq解析输出
translator-ai en.json -l de --stdout | jq
禁用缓存进行全新翻译
translator-ai en.json -l ja -o ja.json --no-cache
使用自定义缓存位置
translator-ai en.json -l ko -o ko.json --cache-file /path/to/cache.json
使用Ollama进行本地翻译
# 使用Ollama的基本用法
translator-ai en.json -l es -o es.json --provider ollama
# 使用不同的Ollama模型
translator-ai en.json -l fr -o fr.json --provider ollama --ollama-model llama2:latest
# 连接到远程Ollama实例
translator-ai en.json -l de -o de.json --provider ollama --ollama-url http://192.168.1.100:11434
# 查看可用提供商
translator-ai --list-providers
高级功能
# 自动检测源语言
translator-ai content.json -l es -o spanish.json --detect-source
# 一次性翻译成多种语言
translator-ai en.json -l es,fr,de,ja -o translations/{lang}.json
# 干跑模式 - 预览要翻译的内容而不进行API调用
translator-ai en.json -l es -o es.json --dry-run
# 保持格式（URL、电子邮件、日期、数字、模板变量）
translator-ai app.json -l fr -o app-fr.json --preserve-formats
# 包含翻译元数据（默认禁用以确保兼容性）
translator-ai en.json -l fr -o fr.json --metadata
# 按字母顺序排序键以保持一致的输出
translator-ai en.json -l fr -o fr.json --sort-keys
# 验证所有键是否存在于翻译中
translator-ai en.json -l fr -o fr.json --check-keys
# 使用不同的Gemini模型
translator-ai en.json -l es -o es.json --gemini-model gemini-2.5-flash
# 组合功能
translator-ai src/**/*.json -l es,fr,de -o "{dir}/{name}.{lang}.json" \
--detect-source --preserve-formats --stats --check-keys
可用的Gemini模型
--gemini-model选项允许您选择各种Gemini模型。流行的选项包括：
gemini-2.0-flash-lite（默认） - 快速高效，适合大多数翻译gemini-2.5-flash- 性能增强，具有新的能力gemini-pro- 更复杂的理解，适合复杂翻译gemini-1.5-pro- 上一代专业模型gemini-1.5-flash- 上一代快速模型
示例用法：
# 使用最新的闪存模型
translator-ai en.json -l es -o es.json --gemini-model gemini-2.5-flash
# 使用默认轻量级模型
translator-ai en.json -l fr -o fr.json --gemini-model gemini-2.0-flash-lite
可用的OpenAI模型
--openai-model选项允许您选择各种OpenAI模型。流行的选项包括：
gpt-4o-mini（默认） - 成本效益高且快速，适合大多数翻译gpt-4o- 最强大的模型，具有高级理解能力gpt-4-turbo- 上一代旗舰模型gpt-3.5-turbo- 快速高效，适合简单的翻译
示例用法：
# 使用OpenAI和默认模型
translator-ai en.json -l es -o es.json --provider openai
# 使用GPT-4o进行复杂翻译
translator-ai en.json -l ja -o ja.json --provider openai --openai-model gpt-4o
# 使用GPT-3.5-turbo进行更快、更简单的翻译
translator-ai en.json -l fr -o fr.json --provider openai --openai-model gpt-3.5-turbo
翻译元数据
启用--metadata标志后，translator-ai会在输出文件中添加元数据以帮助跟踪翻译：
{
"_translator_metadata": {
"tool": "translator-ai v1.1.0",
"repository": "https://github.com/DatanoiseTV/translator-ai",
"provider": "Google Gemini",
"source_language": "English",
"target_language": "fr",
"timestamp": "2025-06-20T12:34:56.789Z",
"total_strings": 42,
"source_file": "en.json"
},
"greeting": "Bonjour",
"farewell": "Au revoir"
}
元数据默认禁用以确保与i18n解析器兼容。使用--metadata来启用它。
键排序
使用--sort-keys标志按字母顺序排序所有JSON键：
translator-ai en.json -l es -o es.json --sort-keys
这确保了翻译之间的一致排序，并使差异更清晰。键按以下方式排序：
- 不区分大小写（a, B, c，而不是B, a, c）
- 递归遍历所有嵌套对象
- 数组保持元素顺序
键验证
使用--check-keys标志确保翻译完整性：
translator-ai en.json -l es -o es.json --check-keys
此功能：
- 验证所有源键是否存在于翻译输出中
- 报告任何缺失键及其完整路径
- 如果缺少任何键，则退出错误码1
- 帮助捕获翻译API失败或格式问题
- 检查时忽略元数据键
支持的语言代码
应支持任何标准化的语言代码。
工作原理
- 解析：读取并展平您的JSON结构为路径
- 去重：处理多个文件时识别共享字符串
- 缓存：检查缓存中已翻译的字符串
- 差异：识别需要翻译的新或修改过的字符串
- 批量：将唯一字符串分组为最优批次大小以提高API效率
- 翻译：将批次发送到选定提供商（Gemini API或本地Ollama）
- 重建：使用翻译重建精确的JSON结构
- 缓存更新：更新缓存以供未来使用
多文件去重
当翻译多个文件时，translator-ai会自动：
- 跨文件识别重复字符串
- 每个唯一字符串只翻译一次
- 在所有文件中一致应用相同的翻译
- 节省大量API调用并确保一致性
例如：如果10个文件共享50%的字符串，您可以节省约50%的API调用！
缓存管理
默认缓存位置
- Windows：
%APPDATA%\translator-ai\translation-cache.json - macOS：
~/Library/Caches/translator-ai/translation-cache.json - Linux：
~/.cache/translator-ai/translation-cache.json
缓存文件存储按以下索引的翻译：
- 源文件路径
- 目标语言
- 源字符串的SHA-256哈希值
这确保了：
- 修改的字符串会被重新翻译
- 删除的字符串会被从缓存中删除
- 多个项目可以共享同一缓存而不会冲突
提供商比较
Google Gemini
- 优点：快速准确，高效处理大批量
- 缺点：需要API密钥，有使用成本
- 可用模型：
gemini-2.0-flash-lite（默认） - 最快，最具成本效益gemini-pro- 性能均衡gemini-1.5-pro- 先进的能力gemini-1.5-flash- 快速且质量好
- 最佳用途：生产使用，大型项目，准确性至关重要
Ollama（本地）
- 优点：免费，本地运行，无API限制，隐私友好
- 缺点：较慢，需要本地资源，需要下载模型
- 最佳用途：开发，隐私敏感数据，成本意识强的项目
性能提示
- 使用缓存（默认启用）以最小化API调用
- 批量多个文件在同一会话中以利用暖缓存
- 使用
--stats标志监控性能和优化机会 - 保持源文件一致性以最大化缓存命中率
- 对于Ollama：使用强大的机器以获得更好的性能
API限制和成本
Gemini API
- 使用Gemini 2.0 Flash Lite模型以实现最佳速度和成本
- 根据输入键数动态选择最佳批次大小
- 每次API调用最多100个字符串
- 查看Google定价以获取当前费率
Ollama
- 无API成本 - 完全在您的硬件上运行
- 性能取决于您的机器能力
- 支持不同模型，具有不同的速度/质量权衡
使用Model Context Protocol (MCP)
translator-ai可以用作MCP服务器，允许像Claude Desktop这样的AI助手直接翻译文件。
MCP配置
添加到您的Claude Desktop配置：
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"translator-ai": {
"command": "npx",
"args": [
"-y",
"translator-ai-mcp"
],
"env": {
"GEMINI_API_KEY": "your-gemini-api-key-here"
// 或者对于Ollama：
// "TRANSLATOR_PROVIDER": "ollama"
}
}
}
}
MCP使用示例
配置完成后，您可以请求Claude翻译文件：
Human: 你能把我的英文区域文件翻译成西班牙语吗？
Claude: 我将使用translator-ai将您的英文区域文件翻译成西班牙语。
<use_tool name="translate_json">
{
"inputFile": "locales/en.json",
"targetLanguage": "es",
"outputFile": "locales/es.json"
}
</use_tool>
成功翻译！文件已保存到locales/es.json。
对于带去重的多个文件：
Human: 把我locales文件夹中的所有英文JSON文件翻译成德语。
Claude: 我将把您的所有英文JSON文件翻译成德语，并进行去重。
<use_tool name="translate_multiple">
{
"pattern": "locales/en/*.json",
"targetLanguage": "de",
"outputPattern": "locales/de/{name}.json",
"showStats": true
}
</use_tool>
翻译完成！处理了5个文件，节省了23%的去重。
MCP可用工具
-
translate_json：翻译单个JSON文件
inputFile：源文件路径targetLanguage：目标语言代码outputFile：输出文件路径