Transept
浏览帮助中心

通过 API 本地化字符串目录

由 Vitalii Vlasiuk 维护Co-founder

UI 文本、游戏字符串和邮件模板通常以带键值的目录形式存在，而“键”正是实现本地化自动化的核心：Transept 根据键值对比目录差异，仅翻译实际变动的内容，并按原有的键值结构返回各语种译文。通过这种闭环流程，即使只改动了一个字符串，也只需支付一个字符串的费用。

本页内容

什么是字符串目录？

Transept 的带键值格式为 .tstrings.json：它包含一系列单元（units），每个单元都有一个固定的 id、一个 source，以及可选的 context（说明字符串内容及出现位置）、max_length 和 placeholders。id 是核心契约：它是翻译在多次重新导入时保持身份一致、保留审核状态以及在导出时为各语种匹配键值的依据。这两项额外参数都有实际作用：上下文会作为翻译指南提供给模型，而字符限制则通过“自动缩短并重试”机制强制执行。

CSV、gettext PO 和 XLIFF 文件通过应用或上传接口导入后，也会被转换为同样的带键值单元；关于各格式的具体映射方式，请参阅字符串文件。本文主要介绍如何通过代码驱动这一闭环流程，在此场景下，.tstrings.json 是其原生格式。

如何通过 API 导入目录？

以 JSON 格式通过 POST /documents/import-strings 发送目录。目标语言将按固定顺序解析：请求中明确指定的 target_language / target_languages 优先级最高，否则采用目录头部的 target_locales；若均未提供，调用将立即失败并返回 no_target_languages，而不会导入没有目标语言的文档。该调用会返回一个 processing_job_id；请轮询 GET /document-jobs/{id}，直到导入完成并获取文档 ID。

文件中已有的译文（如 targets: {de: "…"}）将直接作为每个字符串的当前译文，此操作免费且无需运行翻译任务，并会立即同步至您的翻译记忆库。这与通过应用导入现有翻译的效果一致。

# BASE="https://app.transept.ai/api/public/v1"; KEY from Settings → Developer
curl -s -X POST $BASE/documents/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document": {
        "format": "transept-strings", "version": 1, "source_locale": "en",
        "target_locales": ["de", "fr", "uk"],
        "metadata": {"name": "App UI"},
        "units": [
          {"id": "app.save", "source": "Save", "context": "Toolbar button"},
          {"id": "app.greeting", "source": "Welcome, {name}", "context": "Dashboard header"}
        ]}}'
# → { processing_job_id }; poll GET /document-jobs/{id}

如何仅重译变动内容？

重新提交完整的当前目录至 POST /documents/{id}/import-strings，而非精简后的文件。服务器会根据单元 ID 自动比对差异，并返回检测结果（added、changed、unchanged、removed）以及 delta_block_ids：即各语种版本中需要处理的具体区块。将该返回对象原样作为 组合运行 的 block_ids 参数传入，即可仅翻译这些区块；此外，你也可以在重新导入时直接传入 run 参数，在同一次调用中完成增量处理。

未变动的单元将保留其译文以及已有的审核状态；这就是 仅运行变动内容 功能在 API 端的实现。在包含数百个字符串的目录中，即使只修复了一个字符串，也只需支付一个字符串的费用。

# 1. Re-submit the whole current catalog; the server diffs it by unit id
curl -s -X POST $BASE/documents/<master>/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @app-ui.tstrings.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {<doc_id>: [block ids]} }

# 2. Feed delta_block_ids VERBATIM into a group run; only those blocks translate
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end",
       "target_languages": "all", "block_ids": { "<doc_id>": ["<block id>", "…"] }}'

如何获取带键值的翻译结果？

对主文档调用 GET /documents/{id}/content?format=strings 会返回一个包含所有语言翻译且以单元 ID 为键的 .tstrings.json 文件：只需一次调用，即可直接提交或集成到您的构建流程中。当流水线需要特定的传输格式时，该端点也提供按语种生成的版本（markdown、html、csv、xliff、tmx）；完整表格请参阅通过 API 实现 Transept 自动化。

对于以 CSV、PO 或 XLIFF 格式导入的目录，原始文件导出则会填充您文件中的单元格和条目（除了添加了翻译外，内容与您上传的文件逐字节一致），使文件可以直接加载回原系统。

curl -s "$BASE/documents/<master>/content?format=strings" \
  -H "Authorization: Bearer $KEY"
# → one .tstrings.json with every language keyed by unit id
常见问题✦

未变动的字符串会重复计费吗？

不会。每次重新导入时，Transept 都会根据单元 ID 对比提交的目录与已存储的目录，只有新增或变动的单元才会进入运行。未变动的字符串将保留其译文及已有的审核状态；重新提交完整文件本身不会产生任何费用。

如何处理像 {name} 这样的占位符？

它们受到保护，不会被翻译。在文本发送给模型之前，占位符会被遮蔽；在模型回复后，系统会将其与原文进行核对。如果译文丢失或弄乱了占位符，系统会进行修复或重试，绝不会让错误静默通过。占位符文本本身会原样还原。

重新导入前，我需要自己比对差异吗？

不需要，这正是该循环流程的意义所在。请始终发送完整的当前目录；服务器会负责处理差异比对，并准确返回哪些区块发生了变动。手动精简文件其实是错误的做法：提交内容中缺失的单元会被视为已删除。

继续阅读✦
探索功能✦

仍有疑问？在应用内询问 Literess，或发送邮件至 [email protected]。