HelloWorld 接口能让你把文本快速、安全地送进我们的翻译引擎，得到结构化的翻译结果并可接入人工审核。它支持批量提交、术语表、翻译记忆和多轨校验，适合品牌文案、产品说明、网站本地化等场景，便于自动化工作流和人工干预。接口返回可追溯的任务ID、审校记录与费用估算，文档友好，便于与CI/CD集成。
先说结论：这份教程告诉你能做什么、怎么接入、怎么保证质量
想让翻译既快又靠谱，最实用的办法是把翻译流程当成一个可编排的流水线：把原文发到 HelloWorld 接口——拿回初稿（机器翻译）——把术语和记忆应用进去——触发人工校对——拿回最终稿并保存审计记录。下面我一步步把接口、参数、示例、常见坑和落地流程讲清楚，像教朋友一样。
核心概念（用最简单的话）
- 任务（job）：一次提交的翻译请求，可能包含单条或多条文本。
- 语言对：源语言与目标语言，例如 zh→en。
- 术语表（glossary）：必须优先保留或替换的术语和品牌用词。
- 翻译记忆（TM）：历史译文库，用于提高一致性和复用翻译。
- 后编辑（PE）：机器译文经人工校正得到高质量产物。
快速开始：3 步跑通 HelloWorld
- 获取 API Key（在控制台申请并限制 IP）。
- 用 curl 或 SDK 提交一个小任务，拿回 task_id。
- 轮询或用回调获取结果，查看审校与费用信息。
最小可运行示例（curl）
curl -X POST https://api.example.com/v1/translate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source":"zh","target":"en","contents":["你好，世界！"],"glossary_id":"g123"}'
接口一览（常用）
| 接口 | 方法 | 说明 |
| /v1/translate | POST | 提交翻译任务（支持批量） |
| /v1/status/{task_id} | GET | 查询任务状态与结果 |
| /v1/glossaries | POST/GET | 创建与查询术语表 |
| /v1/tms | POST/GET | 上传/查询翻译记忆条目 |
| /v1/invoice | GET | 查询费用明细与计费记录 |
请求参数详解：把每个字段看成开关
- source / target：语言代码（ISO 639-1/3）。必须填写。
- contents：字符串数组。支持原始文本、HTML（可选择清洗）或带占位符的模板。
- format：plain/html/markdown，决定是否保留标签。
- glossary_id：引用已存在的术语表，优先级高于模型建议。
- tm_id：引用翻译记忆库，用于自动匹配与建议译文。
- post_edit：auto/manual，自动后编辑或人工后编辑。
- callback_url：任务完成后通知的回调地址（建议使用 HTTPS 并验证签名）。
- priority：normal/high/urgent，影响排队与计费。
返回字段要注意的三项
- task_id：所有后续操作都以它为主键。
- estimated_cost：提交时的费用估算，避免意外账单。
- audit_trail：每次人工编辑、谁改了、改了什么，都能查到。
示例：品牌 Slogan 创意化翻译流程
品牌口号不能照搬，要保留情感、节奏、文化内涵。一个实操流程：
- 先在术语表里定义品牌专有词与禁用词。
- 提交原文、指定 target 和 format=plain，并要求 post_edit=manual。
- 机器给出三套候选译文（A/B/C），并返回每套的风格标签（formal/casual/edgy）。
- 人工译者基于品牌语调和本地文化做创意改写，填写审校理由并保存版本。
请求样例：
{
"source":"zh",
"target":"en",
"contents":["取针出海，让品牌出圈。"],
"format":"plain",
"glossary_id":"brand_glossary_01",
"post_edit":"manual",
"options":{"candidates":3,"style":"creative"}
}
错误码与排查要点（真实场景）
- 400 Bad Request：常见原因是字段缺失或格式错误，检查 JSON schema。
- 401 Unauthorized：API Key 未传或被禁用，检查控制台与 IP 白名单。
- 402 Payment Required：余额不足或账号未开通相应额度，查看费用估算与计费策略。
- 429 Too Many Requests：超过速率限制，采用指数退避或队列机制。
- 5xx Server Error：记录 request_id，联系技术支持并重试。
质量保证（AI + 人工）的落地细节
把“机翻+人工”变成可靠的流程，需要做三件事：
- 前处理：清洗 HTML、替换代码占位、拆分长句。
- 中间处理：应用术语表和 TM，把高匹配的段落自动接受或标记为建议。
- 后处理与审计：人工审校、记录差异、保存最终版本与审校备注。
举个比喻：翻译流水线像做寿司——机器切配（基础翻译），人工调味（文化与创意），最后打包并标注成分表（审计记录）。
本地化工作流建议（网站、产品说明、电商详情）
- 网站：导出 i18n 文件（JSON/XLIFF），批量提交，启用格式保留，回传后自动部署到 staging。
- 产品说明书：保留技术术语、图表注释为占位符，术语表必须先同步。
- 电商详情页：短句优先机器候选并人工优化 SEO 关键词、口语化表达与尺码单位转换。
性能、计费与 SLA（实务建议）
| 项 | 示例 |
| 并发限制 | 50 rps（可按需提升） |
| 批量大小 | 单次不超过 5,000 字符或 500 条记录 |
| 计费方式 | 按字符/按任务/包月混合计费（提交时返回 estimated_cost） |
| SLA | 普通任务 24h 内完成，urgent 2h 内响应（视语对与工作量） |
安全与合规（必须有）
- 数据传输须走 HTTPS，并对回调进行 HMAC 签名校验。
- 敏感数据先脱敏或用占位符，随后可选择回填。
- 保留期与删除策略可在合同中约定，遵守 GDPR / 中国网络安全法 等相关法规。
常见落坑与规避策略（实用）
- 不要直接把整个网站 HTML 传给接口，先抽出可翻译文本并保留结构标记。
- 术语表要先在控制台导入并测试，避免事后大量替换。
- 长句应拆小段，机器翻译更准确且便于人工校对。
接口版本与变更管理
任何对接口的向后不兼容变更，都应发布新版本（例如 v1 → v2），并保留至少 90 天的兼容层。在头部里明确版本：Accept-Version: v1。
最佳实践清单（可打印）
- 始终在提交前做文本预处理（占位符、HTML 清洗）。
- 维护并同步术语表与翻译记忆。
- 对关键文案走“多候选+人工创译”流程。
- 使用回调 + 审计日志确保可追溯性。
- 把费用估算纳入提交响应，避免超出预算。
示例：完整请求到回调的典型交互（思路图）
客户端提交 → 返回 task_id 与 estimated_cost → 处理队列（机器翻译 + 术语/TM 应用）→ 若需要人工，则分配给译员 → 译员提交审校并写审校说明 → 系统生成最终包并触发 callback → 客户拉取并存档。
FAQ（两个很常见的问题）
- 问：如何保证品牌调性在不同语言也能成立？ 答：通过术语表、风格指南、候选译文与人工创译三项联动来把控。
- 问：机器翻译结果是否能直接用于上线？ 答：仅在非营销性、低风险内容可考虑自动发布；品牌/营销/法律类务必人工审校。
如果你已经准备好开始，把术语表和一个小样本（如 10 条）先发过去测试精度，对照本地用户反馈调整风格标签和优先级。按这个流程推进，既能节约成本，又能保证品牌在不同市场的表达一致性。慢慢来，遇到问题记录下来，下一版就能更顺。
