API
通过服务器翻译 JSON 和文件、跟踪翻译进度,并下载已完成的译文。
使用 Lingo.dev API 翻译由应用管理的内容。一个本地化任务包含一个引擎、一种源语言、多种目标语言,以及一个或多个文档。每个文档都会跟踪所请求的各语言对应的翻译目标。大多数格式会生成独立的目标文件;Apple 字符串目录则将多种语言整合到同一个文件中。
API 基础 URL 为 https://api.lingo.dev/v2。请将 API 凭据保存在服务器上。从首次翻译请求开始,翻译两条消息并保存结果。
选择输入内容 #
| 你的内容 | 从这里开始 |
|---|---|
| 应用中已有的 JSON 对象 | 翻译 JSON。在创建请求中直接发送该对象。 |
| JSON、Markdown、HTML 或移动端资源等文件 | 翻译文档。上传原始字节数据,再下载相同格式的文件。 |
| 多个文档或多种目标语言 | 创建翻译任务。同一个任务可以同时包含内联 JSON 和上传的文件。 |
这三种方式都遵循相同的生命周期:
- 创建任务,并将任务 ID 与源内容版本一同保存。
- 上传响应中
uploads数组列出的每个文件。内联 JSON 源内容会在创建任务时保存。 - 启动任务。
- 读取任务的进度,直到所需的文档翻译目标全部完成。
- 通过各自的
status.downloadUrl下载每个已完成的翻译目标。
创建任务只是保存待执行的工作;启动任务后,工作才会被接纳并开始处理。创建请求成功返回,并不代表译文已经生成。
如果需要查看内容复用情况和预估费用,请在创建任务前估算工作量。
配置翻译 #
通过 engineId 明确指定引擎。引擎提供模型、术语表、规则和品牌语调,以及翻译流水线。API 密钥必须具有该引擎的翻译访问权限。
对于 JSON,可通过 format.options 添加文档专属的上下文、提示和受保护路径。处理后续版本时,可提供上一版源内容和译文,以复用未更改的内容。
人工审核让获授权的审核者可以在流水线继续执行前,批准或编辑符合条件的译文。审核工作流指南介绍了如何衔接提交、审核和交付。
将应用状态与任务关联 #
继续操作前,请持久化保存任务 ID、源内容版本、文档键和请求的语言区域。创建任务时使用 Idempotency-Key 标头,以便在无法确定响应结果时重试,而不创建重复任务。提交替代任务前,请先获取已有任务。
即使其他翻译目标失败,也应下载已完成的翻译目标。只有当结果仍对应应用所预期的源内容版本时,才发布该结果。构建翻译工作流介绍了如何协调这些操作。
准备并改进引擎 #
初始化配置会根据网站内容或文本填充术语表、规则和品牌语调。引擎建议将反馈转化为可供查看和应用的提案。在依据生成的指导内容进行翻译之前,请先审核这些内容。