AI 本地化AI Localization

应用全量本地化解决方案,支持多格式资源文件 (JSON/XML/Strings/Plist/YAML/CSV) 翻译与平台配置自动化。Full-scale app localization solution. Translates i18n resource files (JSON/XML/Strings/Plist/YAML/CSV) with automated platform configuration.

快速概览

Quick Overview

AI 本地化 API 为应用国际化提供一站式解决方案。上传源语言资源文件(JSON/XML/Strings/YAML/PO/CSV),自动翻译为多个目标语言,并生成对应格式的平台资源文件。支持保留占位符(%s, {0}, {{var}} 等)、关联术语库确保翻译一致性,以及命名空间/Key 路径映射,适用于 iOS/Android/Web 全平台本地化工作流。The AI Localization API provides a one-stop solution for app internationalization. Upload source-language resource files (JSON/XML/Strings/YAML/PO/CSV), automatically translate to multiple target languages, and generate platform-compatible resource files. Supports placeholder preservation, glossary integration for consistency, and namespace/key path mapping — ideal for iOS/Android/Web localization workflows.

认证方式

Authentication

所有 API 请求需在 HTTP Header 中携带 Access Token 进行身份认证:All API requests must include an Access Token in the HTTP Header for authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN

请前往 控制台 获取您的 Access Token。Get your Access Token from the Dashboard.

请求头

Request Headers

HeaderHeaderValue必填Required说明Description
AuthorizationBearer {token}requiredBearer 认证令牌Bearer authentication token
Content-Typemultipart/form-datarequired文件上传使用 multipart/form-data 格式File upload uses multipart/form-data

支持的文件格式

Supported File Formats

格式Formatfile_type主流平台Platforms说明Notes
JSONJSONjsonWeb, React/i18next支持嵌套 Key 路径,如 nav.menu.homeSupports nested key paths like nav.menu.home
XMLXMLxmlAndroid支持 strings.xmlarrays.xmlSupports strings.xml and arrays.xml
YAMLYAMLyamlRuby on Rails, Flutter支持 .yml 和 .yaml 扩展名Supports .yml and .yaml extensions
POPOpoGNU gettext, WordPress保留 msgid/msgstr 结构和注释Preserves msgid/msgstr structure and comments
StringsStringsstringsiOS, macOS支持 "key" = "value"; 格式和注释Supports "key" = "value"; format and comments
CSVCSVcsv通用/ExcelGeneric/Excel两列格式:key, valueTwo-column format: key, value
PlistPlistplistiOS, macOS支持 InfoPlist.strings 格式Supports InfoPlist.strings format

占位符类型参考

Placeholder Types Reference

类型示例来源Origin
%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)
:paramHello, :name!Ruby on Rails i18n

资源文件翻译

Resource File Translation

POST/v1/localization/translate

请求参数

Request Parameters

参数Parameter类型Type必填Required说明Description
filefilerequired资源文件,支持 JSON/XML/YAML/PO/Strings/CSV/Plist,最大 10 MBResource file (JSON/XML/YAML/PO/Strings/CSV/Plist), max 10 MB
file_typestringrequired文件类型:json/xml/yaml/po/strings/csv/plistFile type: json/xml/yaml/po/strings/csv/plist
source_langstringrequired源语言代码,如 en/zh/jaSource language code, e.g. en/zh/ja
target_langsstring[]required目标语言列表,最多 30 种语言Target language list, up to 30 languages
tm_idstringoptional关联的术语库/翻译记忆库 ID,确保术语翻译一致性Associated glossary/TM ID for terminology consistency
preserve_placeholdersbooleanoptional保留占位符 (%s, {0}, {{var}}),默认 truePreserve placeholders; default true
preserve_htmlbooleanoptional保留 HTML 标签,默认 truePreserve HTML tags; default true
output_formatstringoptional输出文件格式,默认与输入一致,可指定为 json/xml/csvOutput format; defaults to input type, can specify json/xml/csv
namespacestringoptional命名空间前缀(如 app.feature.),用于 Key 路径映射Namespace prefix (e.g. app.feature.) for key path mapping
callback_urlstringoptional翻译完成后的 Webhook 通知 URLWebhook URL for completion notification

请求示例

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

字段Field类型Type说明Description
project_idstring项目唯一标识,用于后续下载和查询进度Unique project ID for download and progress queries
statusstring翻译状态:completed/processing/partial/failedStatus: completed/processing/partial/failed
filesobject已生成文件映射,key 为语言代码,value 为下载链接Generated file map, key=lang code, value=download URL
progressobject翻译进度信息:completed, total, percentageProgress info: completed, total, percentage
statsobject翻译统计:total_keys, languages_generated, placeholders_preservedStats: total_keys, languages_generated, placeholders_preserved
errorsobject[]翻译中的错误/警告列表(如某语言翻译失败或某 key 跳过)List of errors/warnings (e.g. failed language or skipped 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 条时通常同步返回全部结果;超过后进入异步处理,通过进度接口轮询状态。
  • Files with <500 entries typically return results synchronously; larger files process asynchronously.
  • 若提供了 callback_url,翻译完成后会 POST 通知该地址,携带 project_idstatus 字段。
  • If callback_url is provided, a POST notification with project_id and status is sent upon completion.

获取翻译进度

Translation Progress

GET/v1/localization/progress

查询参数

Query Parameters

参数Parameter类型Type必填Required说明Description
project_idstringrequired翻译项目 IDTranslation project 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
参数Parameter类型Type必填Required说明Description
project_idstringrequired翻译项目 IDTranslation project ID
langstringoptional指定下载单语言文件;不填则打包为 ZIP 下载所有语言Download single language; omit for ZIP bundle of all languages
formatstringoptional输出格式,默认与上传时一致Output format; defaults to upload format

错误码

Error Codes

HTTP Code错误码Error Code说明Description
2000成功Success
4001001参数错误,请检查必填参数和参数格式Invalid parameter; check required fields and format
4001002不支持的语言代码Unsupported language code
4001003不支持的文件类型,请参考支持的文件格式Unsupported file type; see supported formats
4001007target_langs 数量超过限制(最多 30 种)target_langs exceeds limit (max 30 languages)
4012001认证失败,Token 无效或已过期Authentication failed; invalid or expired token
4032003无权限访问该资源Access denied; insufficient permissions
4043003project_id 不存在或已过期project_id not found or expired
4133004文件大小超过限制(最大 10 MB)File size exceeds limit (max 10 MB)
4223005文件解析失败,请检查文件格式是否正确File parsing failed; check file format validity
4294001请求频率超限,请稍后重试Rate limit exceeded; please retry later
5005001服务器内部错误,请重试或联系技术支持Internal server error; retry or contact support

最佳实践

Best Practices

  1. 使用术语库统一翻译:通过 tm_id 关联术语库,确保产品名、品牌名等核心术语在所有语言中一致。
  2. Unify translations with glossary: Use tm_id to link a glossary for consistent core terminology across all languages.
  3. 分模块上传大文件:对于超过 2000 条的资源文件,建议按模块拆分上传(如 common.json / checkout.json),避免单次处理时间过长。
  4. Upload large files by module: For files with 2000+ entries, split by module (e.g. common.json / checkout.json) to avoid long processing times.
  5. 规范化占位符格式:确保所有源语言条目使用统一的占位符风格(如全部使用 {var} 而非混合 %s),提高保留准确率。
  6. Standardize placeholder format: Use consistent placeholder style (e.g. all {var} instead of mixed %s) to improve preservation accuracy.
  7. 设置回调避免轮询:大文件使用 callback_url 接收完成通知,无需反复轮询进度接口。
  8. Use callbacks to avoid polling: For large files, use callback_url to receive completion notifications instead of polling.
  9. 先翻译后审校:完成机器翻译后,建议人工抽查 10%~20% 的关键页面条目,确保语境翻译质量。
  10. Translate first, review later: After machine translation, manually spot-check 10%~20% of key UI entries for contextual accuracy.
  11. 保留原文注释:在源文件中使用注释标记翻译说明(如 // 按钮文案,最长 10 字符),部分格式的注释会被保留。
  12. Preserve source comments: Use comments in source files for translation notes (e.g. // button text, max 10 chars); some formats preserve comments.

使用场景

Use Cases

场景Scenario推荐参数Recommended Params说明Notes
移动 App 国际化Mobile App i18nfile_type=json|xml|strings, target_langs=10+上传 iOS/Android 资源文件,一次生成所有目标语言版本Upload iOS/Android resource files, generate all target languages at once
Web 应用多语言Web App i18nfile_type=json, namespace=app.连接 CI/CD 流水线,发布时自动生成多语言 JSON 资源Connect to CI/CD pipeline, auto-generate multilingual JSON on deployment
WordPress 主题翻译WordPress Theme Translationfile_type=po, preserve_placeholders=true上传 .po 文件,生成各语言的 .po/.mo 文件Upload .po files, generate per-language .po/.mo files
产品说明多语言Product Docs Localizationfile_type=json|csv, tm_id=glossary上传产品说明键值对,关联术语库确保品牌术语一致性Upload product description key-values, link glossary for brand term consistency
游戏本地化Game Localizationfile_type=json|yaml, tm_id=game_terms处理大量对话和 UI 文本,保留 {player_name} 等占位符Process dialogue and UI texts, preserve {player_name} placeholders
格式转换Format Conversionoutput_format=xml, source_lang=en将 JSON 资源文件转换为 Android XML 格式用于跨平台移植Convert JSON resource files to Android XML for cross-platform porting
使用说明
  • 所有 API 请求均使用 HTTPS,建议开启 HTTP Keep-Alive 以提高性能。
  • All API requests use HTTPS; enable HTTP Keep-Alive for better performance.
  • 请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
  • Do not expose your Access Token in client-side code; use a backend proxy.
  • 推荐设置合理的超时时间(60 秒),大文件翻译可能耗时较长;并实现指数退避重试策略。
  • Set a reasonable timeout (60s); large file translation may take longer. Implement exponential backoff for retries.
  • 文件下载链接有效期为 72 小时,请及时下载或使用 /v1/localization/download 接口重新获取。
  • File download links expire after 72 hours; download promptly or re-acquire via /v1/localization/download.