ai-locale 翻译 CLI

一个使用 OpenAI API 验证和翻译本地化文件的命令行工具。支持多种文件格式，使用 #locale 占位符进行智能路径匹配。

🌍 多语言文档

• 🇺🇸 English (原始)
• 🇫🇷 Français
• 🇪🇸 Español
• 🇨🇳 中文 (当前)

🎯 支持的文件格式

CLI 支持广泛的本地化文件格式：

📱 iOS .strings 文件

/* Localizable.strings */
"SAVE_BUTTON" = "保存";
"CANCEL_BUTTON" = "取消";
"ERROR_MESSAGE" = "发生错误：{error}";

📄 Android XML 字符串

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="save_button">保存</string>
    <string name="cancel_button">取消</string>
    <string name="error_message">发生错误：%1$s</string>
</resources>

📦 JSON 文件

{
  "save_button": "保存",
  "cancel_button": "取消",
  "error_message": "发生错误：{error}"
}

🔧 TypeScript/JavaScript 导出对象

export default {
  save_button: "保存",
  cancel_button: "取消",
  error_message: "发生错误：{error}",
} as const;

🗂️ 使用 #locale 进行路径匹配

CLI 使用 #locale 占位符进行智能文件发现和语言检测：

#locale 工作原理

#locale 占位符会自动替换为从文件结构中检测到的语言代码：

# 模式：locales/#locale/messages.json
# 匹配：locales/en/messages.json, locales/fr/messages.json, locales/es/messages.json
# 检测到的语言：en, fr, es

ai-locale translate 'locales/#locale/messages.json'

常用 #locale 模式

# iOS/Android 结构
'locales/#locale/Localizable.strings'
'locales/#locale/strings.xml'

# JSON 结构
'locales/#locale/messages.json'
'i18n/#locale/translations.json'

# TypeScript 结构
'src/locales/#locale/index.ts'
'locales/#locale/translation.ts'

# 混合格式
'locales/#locale/strings.xml'
'locales/#locale/messages.json'

语言检测

CLI 自动从以下位置检测语言：

• 目录名称：locales/en/, locales/fr/
• 文件名称：en.json, fr.json, en.ts
• 文件路径：locales/en/messages.json

功能特性

• ✅ 多格式支持：处理 iOS .strings、Android XML、JSON 和 TypeScript/JavaScript 文件
• ✅ 智能路径匹配：使用 #locale 占位符进行智能文件发现
• ✅ 缺失键检测：自动识别语言文件中缺失的翻译
• ✅ AI 驱动翻译：使用 OpenAI 的 GPT-4o-mini 进行高质量翻译
• ✅ 成本优化：并行批处理翻译，提供成本估算
• ✅ 上下文感知：使用所有现有翻译作为上下文，确保最大准确性
• ✅ 交互式 CLI：美观的终端界面，带有进度指示器
• ✅ 备份支持：翻译前自动创建备份文件
• ✅ 试运行模式：预览翻译而不进行实际更改
• ✅ 批处理控制：可配置的批处理大小和延迟，用于速率限制管理

安装

全局安装

npm install -g ai-locale-cli

本地安装

git clone <repository-url>
cd iara-worldwide
npm install

快速开始

1. 设置 API 密钥

在项目根目录创建 .env 文件：

OPENAI_API_KEY=sk-your-openai-api-key-here

或使用 --api-key 选项：

ai-locale translate "locales/#locale/messages.json" --api-key sk-your-key

2. 翻译文件

# 使用 #locale 模式（推荐）
ai-locale translate "locales/#locale/messages.json" --source en

# 明确指定目标语言
ai-locale translate "locales/#locale/strings.xml" --source en --target fr,es,de

# 使用传统 glob 模式
ai-locale translate "translations/**/*.strings" --source en --target fr,es

# 试运行查看将要翻译的内容
ai-locale translate "locales/#locale/messages.json" --dry-run

3. 验证文件

# 使用 #locale 模式检查缺失的翻译
ai-locale validate "locales/#locale/messages.json" --source en

# 传统 glob 模式
ai-locale validate "translations/**/*.strings" --source en

4. 查看统计信息

# 显示翻译完整性统计信息
ai-locale stats "locales/#locale/messages.json"

# 传统 glob 模式
ai-locale stats "translations/**/*.strings"

CLI 命令

translate - 翻译缺失的键

翻译本地化文件中缺失的键。

ai-locale translate <pattern> [options]

参数：

• pattern - 文件模式（例如 locales/#locale/messages.json, translations/**/*.strings）

选项：

• -k, --api-key <key> - OpenAI API 密钥（或设置 OPENAI_API_KEY 环境变量）
• -s, --source <lang> - 源语言代码（默认："en"）
• -t, --target <langs> - 逗号分隔的目标语言（如果未提供则自动检测）
• -o, --output <dir> - 输出目录（默认：覆盖原始文件）
• --dry-run - 显示将要翻译的内容而不进行更改
• --verbose - 显示详细输出
• --no-backup - 不创建备份文件
• --yes - 跳过确认提示
• --batch-size <size> - 并行处理的翻译数量（默认：5）
• --batch-delay <ms> - 批次间延迟（毫秒）（默认：1000）

示例：

# 使用 #locale 模式的基本翻译
ai-locale translate "locales/#locale/messages.json"

# 指定源语言和目标语言
ai-locale translate "locales/#locale/strings.xml" --source en --target fr,es,de,it

# 试运行预览
ai-locale translate "locales/#locale/messages.json" --dry-run --verbose

# 保存到不同目录
ai-locale translate "locales/#locale/messages.json" --output ./translated/

# 使用特定 API 密钥
ai-locale translate "locales/#locale/messages.json" --api-key sk-your-key

# 控制批处理
ai-locale translate "locales/#locale/messages.json" --batch-size 3 --batch-delay 2000

validate - 验证翻译文件

检查翻译文件中缺失的键和一致性问题。

ai-locale validate <pattern> [options]

参数：

• pattern - 要验证的文件模式

选项：

• -s, --source <lang> - 源语言代码（默认："en"）

示例：

# 使用 #locale 模式验证所有翻译文件
ai-locale validate "locales/#locale/messages.json"

# 使用特定源语言验证
ai-locale validate "locales/#locale/strings.xml" --source en

# 传统 glob 模式
ai-locale validate "translations/**/*.strings" --source en

stats - 显示翻译统计信息

显示翻译文件的完整统计信息。

ai-locale stats <pattern>

参数：

• pattern - 要分析的文件模式

示例：

# 使用 #locale 模式显示所有文件的统计信息
ai-locale stats "locales/#locale/messages.json"

# 显示特定模式的统计信息
ai-locale stats "locales/#locale/strings.xml"

# 传统 glob 模式
ai-locale stats "translations/**/*.strings"

purge - 删除过时的键

删除源语言文件中不存在的键。

ai-locale purge <pattern> [options]

参数：

• pattern - 要清理的文件模式

选项：

• -s, --source <lang> - 源语言代码（默认："en"）
• --dry-run - 显示将要清理的内容而不进行更改
• --verbose - 显示详细输出
• --no-backup - 不创建备份文件

示例：

# 使用 #locale 模式删除英语中不存在的键
ai-locale purge "locales/#locale/messages.json" --source en

# 试运行预览将要清理的内容
ai-locale purge "locales/#locale/strings.xml" --dry-run --verbose

# 使用法语作为源语言清理
ai-locale purge "locales/#locale/messages.json" --source fr

# 传统 glob 模式
ai-locale purge "translations/**/*.strings" --source en

Glob 模式示例

CLI 支持强大的 glob 模式进行文件发现：

# locales 目录中的所有翻译文件
"locales/#locale/messages.json"

# 递归的所有 .strings 文件
"translations/**/*.strings"

# 特定语言文件
"src/locales/en.ts"
"src/locales/fr.ts"

# 多个模式
"locales/#locale/messages.json" "src/i18n/#locale/translations.json"

# 特定命名约定的文件
"**/i18n/#locale/*.ts"
"**/locales/#locale/*.strings"

# 混合格式与 #locale
"locales/#locale/strings.xml"
"locales/#locale/messages.json"

支持的语言

该工具支持 20+ 种语言，包括：

• 英语 (en)
• 法语 (fr)
• 西班牙语 (es)
• 德语 (de)
• 意大利语 (it)
• 葡萄牙语 (pt)
• 荷兰语 (nl)
• 瑞典语 (sv)
• 丹麦语 (da)
• 挪威语 (no)
• 芬兰语 (fi)
• 波兰语 (pl)
• 俄语 (ru)
• 日语 (ja)
• 韩语 (ko)
• 中文 (zh)
• 阿拉伯语 (ar)
• 印地语 (hi)
• 土耳其语 (tr)
• 泰语 (th)

翻译上下文和准确性

CLI 为 OpenAI 提供最大上下文以获得最准确的翻译：

智能上下文检测

• 所有现有翻译：如果键在英语和法语中存在，两者都包含在提示中
• 源语言优先级：使用指定的源语言作为主要参考
• 完整上下文：为每个键提供所有可用的翻译以确保一致性

翻译上下文示例

键："common.save"
现有翻译：
- en: "Save"
- fr: "Enregistrer"
- es: "Guardar"

缺失于：de, it

AI 接收："将 'Save' 翻译成德语和意大利语，考虑法语和西班牙语中的现有翻译作为上下文"

成本优化

CLI 针对成本和速度进行了优化：

• 并行处理：使用 Promise.all 同时翻译多个键
• 可配置批处理：使用 --batch-size 和 --batch-delay 选项控制批处理大小和延迟
• 成本估算：处理前显示估算成本
• 高效模型：使用 GPT-4o-mini 获得最佳成本/质量比
• 上下文优化：使用所有现有翻译作为上下文以获得最大准确性
• 速率限制管理：内置延迟和批处理以遵守 API 限制

批处理控制示例

# 保守方法（较小的批次，较长的延迟）
ai-locale translate "locales/#locale/messages.json" --batch-size 2 --batch-delay 2000

# 激进方法（较大的批次，较短的延迟）
ai-locale translate "locales/#locale/messages.json" --batch-size 10 --batch-delay 500

# 默认设置（平衡）
ai-locale translate "locales/#locale/messages.json" --batch-size 5 --batch-delay 1000

成本估算示例

对于 3 种语言的 100 个缺失键：

• 估算成本：约 $0.15 USD
• 处理时间：约 2-3 分钟
• 使用的令牌：约 25,000 输入 + 5,000 输出

开发

本地开发

# 安装依赖
npm install

# 本地运行 CLI
node src/cli.js translate "examples/*.ts"

# 带自动重载的开发
npm run dev translate "examples/*.ts"

# 运行测试
npm test

构建可执行文件

# 构建独立可执行文件
npm run build

# 可执行文件将在 dist/ 目录中
./dist/ai-locale-cli translate "locales/#locale/messages.json"

环境变量

| 变量 | 描述 | 默认值 | | ---------------- | --------------- | ----------- | | OPENAI_API_KEY | OpenAI API 密钥 | 必需 | | NODE_ENV | 环境 | development |

项目结构

src/
├── cli.js                    # 主 CLI 入口点
├── services/
│   ├── openaiService.js      # OpenAI 集成
│   └── translationService.js # 翻译逻辑
└── utils/
    ├── fileParser.js         # 文件解析工具
    └── validation.js         # 请求验证

使用示例

示例 1：基本翻译

# 项目结构：
# locales/
#   ├── en/
#   │   └── messages.json
#   ├── fr/
#   │   └── messages.json (缺少一些键)
#   └── es/
#       └── messages.json (缺少一些键)

ai-locale translate "locales/#locale/messages.json" --source en

示例 2：iOS Strings 文件

# 项目结构：
# translations/
#   ├── en/
#   │   └── Localizable.strings
#   ├── fr/
#   │   └── Localizable.strings
#   └── es/
#       └── Localizable.strings

ai-locale translate "translations/#locale/Localizable.strings" --source en

示例 3：Android XML 文件

# 项目结构：
# locales/
#   ├── en/
#   │   └── strings.xml
#   ├── fr/
#   │   └── strings.xml
#   └── es/
#       └── strings.xml

ai-locale translate "locales/#locale/strings.xml" --source en

示例 4：GNU gettext .po 文件

# 项目结构：
# locale/
#   ├── en/
#   │   └── LC_MESSAGES/
#   │       └── messages.po
#   ├── fr/
#   │   └── LC_MESSAGES/
#   │       └── messages.po
#   └── es/
#       └── LC_MESSAGES/
#           └── messages.po

ai-locale translate "locale/#locale/LC_MESSAGES/messages.po" --source en

示例 5：验证和统计信息

# 检查缺失的内容
ai-locale validate "locales/#locale/messages.json" --source en

# 显示统计信息
ai-locale stats "locales/#locale/messages.json"

# 预览翻译（试运行）
ai-locale translate "locales/#locale/messages.json" --dry-run --verbose

示例 6：清理过时的键

# 删除英语中不存在的键
ai-locale purge "locales/#locale/messages.json" --source en

# 预览将要清理的内容
ai-locale purge "translations/#locale/Localizable.strings" --dry-run --verbose

# 使用法语作为源语言清理
ai-locale purge "locales/#locale/messages.json" --source fr

错误处理

CLI 提供全面的错误处理：

• 文件未找到：为无效模式提供清晰的错误消息
• API 错误：优雅处理 OpenAI API 失败
• 解析错误：为文件问题提供详细的错误信息
• 验证错误：为无效请求提供清晰的消息

故障排除

常见问题

1. OpenAI API 密钥无效

   错误：需要 OpenAI API 密钥

   解决方案：设置 OPENAI_API_KEY 环境变量或使用 --api-key 选项

2. 未找到文件

   错误：未找到匹配模式的翻译文件

   解决方案：检查 glob 模式和文件结构

3. 文件解析错误

   错误：解析文件 en.ts 失败

   解决方案：检查文件格式和语法

4. 权限错误

   错误：EACCES：权限被拒绝

   解决方案：检查文件权限或使用适当的权限运行

调试模式

启用详细输出进行调试：

ai-locale translate "locales/#locale/messages.json" --verbose

贡献

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

MIT 许可证 - 查看 LICENSE 文件了解详情。

支持

对于问题和疑问：

1. 查看故障排除部分
2. 检查日志
3. 创建包含详细信息的 issue
4. 包含文件示例和错误消息