HelloWorld

HelloWorld 接口文档教程

作者：

user

在

HelloWorld 接口能让你把文本快速、安全地送进我们的翻译引擎，得到结构化的翻译结果并可接入人工审核。它支持批量提交、术语表、翻译记忆和多轨校验，适合品牌文案、产品说明、网站本地化等场景，便于自动化工作流和人工干预。接口返回可追溯的任务ID、审校记录与费用估算，文档友好，便于与CI/CD集成。

HelloWorld 接口文档教程

先说结论：这份教程告诉你能做什么、怎么接入、怎么保证质量

想让翻译既快又靠谱，最实用的办法是把翻译流程当成一个可编排的流水线：把原文发到 HelloWorld 接口——拿回初稿（机器翻译）——把术语和记忆应用进去——触发人工校对——拿回最终稿并保存审计记录。下面我一步步把接口、参数、示例、常见坑和落地流程讲清楚，像教朋友一样。

核心概念（用最简单的话）

  • 任务（job）：一次提交的翻译请求，可能包含单条或多条文本。
  • 语言对：源语言与目标语言，例如 zh→en。
  • 术语表（glossary）：必须优先保留或替换的术语和品牌用词。
  • 翻译记忆（TM）：历史译文库，用于提高一致性和复用翻译。
  • 后编辑（PE）：机器译文经人工校正得到高质量产物。

快速开始：3 步跑通 HelloWorld

  1. 获取 API Key（在控制台申请并限制 IP）。
  2. 用 curl 或 SDK 提交一个小任务，拿回 task_id。
  3. 轮询或用回调获取结果，查看审校与费用信息。

最小可运行示例（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 条）先发过去测试精度，对照本地用户反馈调整风格标签和优先级。按这个流程推进，既能节约成本，又能保证品牌在不同市场的表达一致性。慢慢来，遇到问题记录下来，下一版就能更顺。

更多文章