AI 本地化
应用全量本地化解决方案,支持多格式资源文件 (JSON/XML/Strings/Plist/YAML/CSV) 翻译与平台配置自动化。
快速概览
Quick Overview
AI 本地化 API 为应用国际化提供一站式解决方案。上传源语言资源文件(JSON/XML/Strings/YAML/PO/CSV),自动翻译为多个目标语言,并生成对应格式的平台资源文件。支持保留占位符(%s, {0}, {{var}} 等)、关联术语库确保翻译一致性,以及命名空间/Key 路径映射,适用于 iOS/Android/Web 全平台本地化工作流。
认证方式
Authentication
所有 API 请求需在 HTTP Header 中携带 Access Token 进行身份认证:
Authorization: Bearer YOUR_ACCESS_TOKEN
请前往 控制台 获取您的 Access Token。
请求头
Request Headers
| Header | 值 | 必填 | 说明 |
|---|---|---|---|
| Authorization | Bearer {token} | required | Bearer 认证令牌 |
| Content-Type | multipart/form-data | required | 文件上传使用 multipart/form-data 格式 |
支持的文件格式
Supported File Formats
| 格式 | file_type | 主流平台 | 说明 |
|---|---|---|---|
| JSON | json | Web, React/i18next | 支持嵌套 Key 路径,如 nav.menu.home |
| XML | xml | Android | 支持 strings.xml 和 arrays.xml |
| YAML | yaml | Ruby on Rails, Flutter | 支持 .yml 和 .yaml 扩展名 |
| PO | po | GNU gettext, WordPress | 保留 msgid/msgstr 结构和注释 |
| Strings | strings | iOS, macOS | 支持 "key" = "value"; 格式和注释 |
| CSV | csv | 通用/Excel | 两列格式:key, value |
| Plist | plist | iOS, macOS | 支持 InfoPlist.strings 格式 |
占位符类型参考
Placeholder Types Reference
| 类型 | 示例 | 来源 |
|---|---|---|
%s / %d / %@ | Hello, %s! | C, Python, Objective-C, Android |
{0} / {1} | Page {0} of {1} | Java MessageFormat, .NET |
{{var}} | Welcome, {{username}}! | Handlebars, Angular, Vue i18n |
${var} | Hello, ${name}! | JavaScript template literals |
%@ | Hello, %@! | iOS/macOS (NSString format) |
:param | Hello, :name! | Ruby on Rails i18n |
资源文件翻译
Resource File Translation
POST/v1/localization/translate
请求参数
Request Parameters
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | file | required | 资源文件,支持 JSON/XML/YAML/PO/Strings/CSV/Plist,最大 10 MB |
| file_type | string | required | 文件类型:json/xml/yaml/po/strings/csv/plist |
| source_lang | string | required | 源语言代码,如 en/zh/ja |
| target_langs | string[] | required | 目标语言列表,最多 30 种语言 |
| tm_id | string | optional | 关联的术语库/翻译记忆库 ID,确保术语翻译一致性 |
| preserve_placeholders | boolean | optional | 保留占位符 (%s, {0}, {{var}}),默认 true |
| preserve_html | boolean | optional | 保留 HTML 标签,默认 true |
| output_format | string | optional | 输出文件格式,默认与输入一致,可指定为 json/xml/csv 等 |
| namespace | string | optional | 命名空间前缀(如 app.feature.),用于 Key 路径映射 |
| callback_url | string | optional | 翻译完成后的 Webhook 通知 URL |
请求示例
Request Examples
curl -X POST https://api.itranslator.cc/v1/localization/translate \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "file=@en.json" \ -F "file_type=json" \ -F "source_lang=en" \ -F "target_langs[]=zh" \ -F "target_langs[]=ja" \ -F "target_langs[]=ko" \ -F "target_langs[]=fr" \ -F "target_langs[]=de" \ -F "preserve_placeholders=true"
响应字段
Response Fields
| 字段 | 类型 | 说明 |
|---|---|---|
| project_id | string | 项目唯一标识,用于后续下载和查询进度 |
| status | string | 翻译状态:completed/processing/partial/failed |
| files | object | 已生成文件映射,key 为语言代码,value 为下载链接 |
| progress | object | 翻译进度信息:completed, total, percentage |
| stats | object | 翻译统计:total_keys, languages_generated, placeholders_preserved |
| errors | object[] | 翻译中的错误/警告列表(如某语言翻译失败或某 key 跳过) |
输入示例 (en.json)
Input (en.json)
{
"welcome": "Welcome, {username}!",
"settings": "Settings",
"messages.unread": "You have {count} unread messages.",
"nav.home": "Home",
"nav.profile": "My Profile",
"action.submit": "Submit"
}响应示例(同步完成)
Response Example (Sync Complete)
{
"project_id": "loc_7a3b2c1d",
"status": "completed",
"files": {
"zh": "https://cdn.itranslator.cc/localization/loc_7a3b2c1d/zh.json",
"ja": "https://cdn.itranslator.cc/localization/loc_7a3b2c1d/ja.json",
"ko": "https://cdn.itranslator.cc/localization/loc_7a3b2c1d/ko.json",
"fr": "https://cdn.itranslator.cc/localization/loc_7a3b2c1d/fr.json",
"de": "https://cdn.itranslator.cc/localization/loc_7a3b2c1d/de.json"
},
"progress": { "completed": 5, "total": 5, "percentage": 100 },
"stats": {
"total_keys": 6,
"languages_generated": 5,
"placeholders_preserved": 4
},
"errors": []
}响应示例(大文件异步)
Response Example (Async for Large Files)
{
"project_id": "loc_9f4e8d2c",
"status": "processing",
"files": {},
"progress": { "completed": 2, "total": 5, "percentage": 40 },
"stats": null,
"errors": []
}
异步处理说明
- 文件小于 500 条时通常同步返回全部结果;超过后进入异步处理,通过进度接口轮询状态。
- 若提供了
callback_url,翻译完成后会 POST 通知该地址,携带project_id和status字段。
获取翻译进度
Translation Progress
GET/v1/localization/progress
查询参数
Query Parameters
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_id | string | required | 翻译项目 ID |
进度查询响应
Progress Response
{
"project_id": "loc_9f4e8d2c",
"status": "completed",
"progress": { "completed": 5, "total": 5, "percentage": 100 },
"files": {
"zh": "https://cdn.itranslator.cc/localization/loc_9f4e8d2c/zh.json",
"ja": "https://cdn.itranslator.cc/localization/loc_9f4e8d2c/ja.json",
"ko": "https://cdn.itranslator.cc/localization/loc_9f4e8d2c/ko.json",
"fr": "https://cdn.itranslator.cc/localization/loc_9f4e8d2c/fr.json",
"de": "https://cdn.itranslator.cc/localization/loc_9f4e8d2c/de.json"
},
"stats": {
"total_keys": 2500,
"languages_generated": 5,
"placeholders_preserved": 1200
}
}下载已翻译文件
Download Translated Files
GET/v1/localization/download
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_id | string | required | 翻译项目 ID |
| lang | string | optional | 指定下载单语言文件;不填则打包为 ZIP 下载所有语言 |
| format | string | optional | 输出格式,默认与上传时一致 |
错误码
Error Codes
| HTTP Code | 错误码 | 说明 |
|---|---|---|
| 200 | 0 | 成功 |
| 400 | 1001 | 参数错误,请检查必填参数和参数格式 |
| 400 | 1002 | 不支持的语言代码 |
| 400 | 1003 | 不支持的文件类型,请参考支持的文件格式 |
| 400 | 1007 | target_langs 数量超过限制(最多 30 种) |
| 401 | 2001 | 认证失败,Token 无效或已过期 |
| 403 | 2003 | 无权限访问该资源 |
| 404 | 3003 | project_id 不存在或已过期 |
| 413 | 3004 | 文件大小超过限制(最大 10 MB) |
| 422 | 3005 | 文件解析失败,请检查文件格式是否正确 |
| 429 | 4001 | 请求频率超限,请稍后重试 |
| 500 | 5001 | 服务器内部错误,请重试或联系技术支持 |
最佳实践
Best Practices
- 使用术语库统一翻译:通过
tm_id关联术语库,确保产品名、品牌名等核心术语在所有语言中一致。 - 分模块上传大文件:对于超过 2000 条的资源文件,建议按模块拆分上传(如 common.json / checkout.json),避免单次处理时间过长。
- 规范化占位符格式:确保所有源语言条目使用统一的占位符风格(如全部使用
{var}而非混合 %s),提高保留准确率。 - 设置回调避免轮询:大文件使用
callback_url接收完成通知,无需反复轮询进度接口。 - 先翻译后审校:完成机器翻译后,建议人工抽查 10%~20% 的关键页面条目,确保语境翻译质量。
- 保留原文注释:在源文件中使用注释标记翻译说明(如
// 按钮文案,最长 10 字符),部分格式的注释会被保留。
使用场景
Use Cases
| 场景 | 推荐参数 | 说明 |
|---|---|---|
| 移动 App 国际化 | file_type=json|xml|strings, target_langs=10+ | 上传 iOS/Android 资源文件,一次生成所有目标语言版本 |
| Web 应用多语言 | file_type=json, namespace=app. | 连接 CI/CD 流水线,发布时自动生成多语言 JSON 资源 |
| WordPress 主题翻译 | file_type=po, preserve_placeholders=true | 上传 .po 文件,生成各语言的 .po/.mo 文件 |
| 产品说明多语言 | file_type=json|csv, tm_id=glossary | 上传产品说明键值对,关联术语库确保品牌术语一致性 |
| 游戏本地化 | file_type=json|yaml, tm_id=game_terms | 处理大量对话和 UI 文本,保留 {player_name} 等占位符 |
| 格式转换 | output_format=xml, source_lang=en | 将 JSON 资源文件转换为 Android XML 格式用于跨平台移植 |
使用说明
- 所有 API 请求均使用 HTTPS,建议开启 HTTP Keep-Alive 以提高性能。
- 请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
- 推荐设置合理的超时时间(60 秒),大文件翻译可能耗时较长;并实现指数退避重试策略。
- 文件下载链接有效期为 72 小时,请及时下载或使用
/v1/localization/download接口重新获取。
iTranslator