CLI tool for validating and translating localization files using OpenAI
npm install ai-locale-cli一个使用 OpenAI API 验证和翻译本地化文件的命令行工具。支持多种文件格式，使用 #locale 占位符进行智能路径匹配。
- 🇺🇸 English (原始)
- 🇫🇷 Français
- 🇪🇸 Español
- 🇨🇳 中文 (当前)
CLI 支持广泛的本地化文件格式：
``strings`
/ Localizable.strings /
"SAVE_BUTTON" = "保存";
"CANCEL_BUTTON" = "取消";
"ERROR_MESSAGE" = "发生错误：{error}";
`xml`
`json`
{
"save_button": "保存",
"cancel_button": "取消",
"error_message": "发生错误：{error}"
}
`typescript`
export default {
save_button: "保存",
cancel_button: "取消",
error_message: "发生错误：{error}",
} as const;
进行路径匹配CLI 使用 #locale 占位符进行智能文件发现和语言检测：
#locale 占位符会自动替换为从文件结构中检测到的语言代码：
`bash模式：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'
`
`bashiOS/Android 结构
'locales/#locale/Localizable.strings'
'locales/#locale/strings.xml'
$3
CLI 自动从以下位置检测语言：
- 目录名称：
, locales/fr/
- 文件名称：, fr.json, en.ts
- 文件路径：功能特性
- ✅ 多格式支持：处理 iOS
、Android XML、JSON 和 TypeScript/JavaScript 文件
- ✅ 智能路径匹配：使用 #locale 占位符进行智能文件发现
- ✅ 缺失键检测：自动识别语言文件中缺失的翻译
- ✅ AI 驱动翻译：使用 OpenAI 的 GPT-4o-mini 进行高质量翻译
- ✅ 成本优化：并行批处理翻译，提供成本估算
- ✅ 上下文感知：使用所有现有翻译作为上下文，确保最大准确性
- ✅ 交互式 CLI：美观的终端界面，带有进度指示器
- ✅ 备份支持：翻译前自动创建备份文件
- ✅ 试运行模式：预览翻译而不进行实际更改
- ✅ 批处理控制：可配置的批处理大小和延迟，用于速率限制管理安装
$3
`bash
npm install -g ai-locale-cli
`$3
bash
git clone
cd iara-worldwide
npm install
`快速开始
$3
在项目根目录创建
文件：`bash
OPENAI_API_KEY=sk-your-openai-api-key-here
`或使用
选项：`bash
ai-locale translate "locales/#locale/messages.json" --api-key sk-your-key
`$3
bash
使用 #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
bash
使用 #locale 模式检查缺失的翻译
ai-locale validate "locales/#locale/messages.json" --source en传统 glob 模式
ai-locale validate "translations/*/.strings" --source en
`$3
bash
显示翻译完整性统计信息
ai-locale stats "locales/#locale/messages.json"传统 glob 模式
ai-locale stats "translations/*/.strings"
`CLI 命令
$3
翻译本地化文件中缺失的键。
bash
ai-locale translate [options]
`参数：
-
- 文件模式（例如 locales/#locale/messages.json, translations/*/.strings）选项：
-
-k, --api-key - OpenAI API 密钥（或设置 OPENAI_API_KEY 环境变量）
- -s, --source - 源语言代码（默认："en"）
- -t, --target - 逗号分隔的目标语言（如果未提供则自动检测）
- -o, --output - 输出目录（默认：覆盖原始文件）
- --dry-run - 显示将要翻译的内容而不进行更改
- --verbose - 显示详细输出
- --no-backup - 不创建备份文件
- --yes - 跳过确认提示
- --batch-size - 并行处理的翻译数量（默认：5）
- --batch-delay - 批次间延迟（毫秒）（默认：1000）示例：
`bash
使用 #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
`$3
检查翻译文件中缺失的键和一致性问题。
bash
ai-locale validate [options]
`参数：
-
- 要验证的文件模式选项：
-
-s, --source - 源语言代码（默认："en"）示例：
`bash
使用 #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
`$3
显示翻译文件的完整统计信息。
bash
ai-locale stats
`参数：
-
- 要分析的文件模式示例：
`bash
使用 #locale 模式显示所有文件的统计信息
ai-locale stats "locales/#locale/messages.json"显示特定模式的统计信息
ai-locale stats "locales/#locale/strings.xml"传统 glob 模式
ai-locale stats "translations/*/.strings"
`$3
删除源语言文件中不存在的键。
bash
ai-locale purge [options]
`参数：
-
- 要清理的文件模式选项：
-
-s, --source - 源语言代码（默认："en"）
- --dry-run - 显示将要清理的内容而不进行更改
- --verbose - 显示详细输出
- --no-backup - 不创建备份文件示例：
`bash
使用 #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 模式进行文件发现：
bash
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 提供最大上下文以获得最准确的翻译：
$3
- 所有现有翻译：如果键在英语和法语中存在，两者都包含在提示中
- 源语言优先级：使用指定的源语言作为主要参考
- 完整上下文：为每个键提供所有可用的翻译以确保一致性
$3
键："common.save"
现有翻译：
- en: "Save"
- fr: "Enregistrer"
- es: "Guardar"缺失于：de, it
AI 接收："将 'Save' 翻译成德语和意大利语，考虑法语和西班牙语中的现有翻译作为上下文"
成本优化
CLI 针对成本和速度进行了优化：
- 并行处理：使用
同时翻译多个键
- 可配置批处理：使用 --batch-size 和 --batch-delay 选项控制批处理大小和延迟
- 成本估算：处理前显示估算成本
- 高效模型：使用 GPT-4o-mini 获得最佳成本/质量比
- 上下文优化：使用所有现有翻译作为上下文以获得最大准确性
- 速率限制管理：内置延迟和批处理以遵守 API 限制$3
`bash
保守方法（较小的批次，较长的延迟）
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
对于 3 种语言的 100 个缺失键：
- 估算成本：约 $0.15 USD
- 处理时间：约 2-3 分钟
- 使用的令牌：约 25,000 输入 + 5,000 输出
开发
$3
bash
安装依赖
npm install本地运行 CLI
node src/cli.js translate "examples/*.ts"带自动重载的开发
npm run dev translate "examples/*.ts"运行测试
npm test
`$3
bash
构建独立可执行文件
npm run build可执行文件将在 dist/ 目录中
./dist/ai-locale-cli translate "locales/#locale/messages.json"
`$3
| 变量 | 描述 | 默认值 |
| ---------------- | --------------- | ----------- |
|
| OpenAI API 密钥 | 必需 |
| NODE_ENV | 环境 | development |$3
`
src/
├── cli.js # 主 CLI 入口点
├── services/
│ ├── openaiService.js # OpenAI 集成
│ └── translationService.js # 翻译逻辑
└── utils/
├── fileParser.js # 文件解析工具
└── validation.js # 请求验证
使用示例
$3
bash
项目结构：
locales/
├── en/
│ └── messages.json
├── fr/
│ └── messages.json (缺少一些键)
└── es/
└── messages.json (缺少一些键)
ai-locale translate "locales/#locale/messages.json" --source en
`$3
bash
项目结构：
translations/
├── en/
│ └── Localizable.strings
├── fr/
│ └── Localizable.strings
└── es/
└── Localizable.strings
ai-locale translate "translations/#locale/Localizable.strings" --source en
`$3
bash
项目结构：
locales/
├── en/
│ └── strings.xml
├── fr/
│ └── strings.xml
└── es/
└── strings.xml
ai-locale translate "locales/#locale/strings.xml" --source en
`$3
bash
项目结构：
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
`$3
bash
检查缺失的内容
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
`$3
bash
删除英语中不存在的键
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 失败
- 解析错误：为文件问题提供详细的错误信息
- 验证错误：为无效请求提供清晰的消息
故障排除
$3
1. OpenAI API 密钥无效
错误：需要 OpenAI API 密钥
解决方案：设置
环境变量或使用 --api-key 选项2. 未找到文件
`
错误：未找到匹配模式的翻译文件
解决方案：检查 glob 模式和文件结构
3. 文件解析错误
错误：解析文件 en.ts 失败
解决方案：检查文件格式和语法
4. 权限错误
错误：EACCES：权限被拒绝
解决方案：检查文件权限或使用适当的权限运行
$3
启用详细输出进行调试：
bash
ai-locale translate "locales/#locale/messages.json" --verbose
``1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求
MIT 许可证 - 查看 LICENSE 文件了解详情。
对于问题和疑问：
1. 查看故障排除部分
2. 检查日志
3. 创建包含详细信息的 issue
4. 包含文件示例和错误消息