> translating the developer experience

你不是在"用"翻译API——你在跟它对话。调试、测试、分析、优化,一个终端全搞定。

API Playground — POST /v2/translate
// Request
curl -X POST https://api.traneasy.com/v2/translate \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"source":"zh","target":"en","text":"人工智能正在改变世界","formality":"auto"}'
// Response 200 OK — 287ms
{
  "translated": "Artificial intelligence is changing the world",
  "confidence": 0.974,
  "tokens_used": 42,
  "latency_ms": 287
}

api_playground

把你脑子里想的请求直接敲进去,即时看到请求/响应/耗时/错误。不用写脚本,不用配环境——浏览器就是你的开发终端。

request_builder

请求构造器

可视化填写参数,自动生成cURL、Python、JavaScript、Go四种语言的请求代码片段。支持环境变量绑定,base URL和API Key不用每次都粘贴。请求历史自动保存,点击就能重放。

response_inspector

响应检查器

返回的JSON自动格式化并高亮语法。Headers、状态码、耗时、token消耗四个维度的信息分Tab展示。如果你开了术语表,响应里会额外显示哪些术语被匹配到了、覆盖了哪些句子。

batch_runner

批量执行器

上传一个JSONL文件(每行一个请求参数),Playground按你的并发设置逐批执行。跑完后输出汇总报告:总请求数、成功/失败数、P50/P95/P99延迟、token总消耗。适合在做正式集成前先用真实数据压一遍。

mock_server

Mock 服务器

不想每次都消耗API额度?开启Mock模式,所有请求返回符合规范的假数据。响应结构、字段类型、延迟范围都可以自定义。你在本地调试业务逻辑的时候,Mock模式能省不少钱。

test_suite

翻译不是黑盒。把测试写清楚,每次模型更新或配置变更后跑一遍,确保质量不退化。

regression_test

回归测试集

定义一组"标准答案"句子对——原文 + 期望译文。每次引擎升级后自动跑一遍,对比实际输出和期望输出的BLEU/COMET分数。低于阈值自动标红告警,不让质量偷偷滑下去。

fuzz_test

模糊测试

随机生成边界输入:空字符串、纯emoji、10000字长文、混合语言段落、特殊Unicode字符。验证API不会崩溃、不会返回非JSON、不会超时。这种测试人力根本覆盖不全,自动化才是正解。

term_consistency

术语一致性检测

给定一份术语表(如"用户体验 → user experience"),用包含这些术语的测试句子去调API,检查返回译文里术语翻译是否始终一致。输出每个术语的匹配率,哪些句子掉了术语一目了然。

$ traneasy test run --suite regression_v3.2 --env staging
[2026-07-11 14:32:01] Loading test suite: regression_v3.2 (247 cases)...
[14:32:03] Running against: api-staging.traneasy.com/v2

PASS [001/247] zh→en basic_noun   BLEU:0.82 COMET:0.91
PASS [002/247] zh→en tech_term   BLEU:0.78 COMET:0.88
SKIP [003/247] zh→ar low_resource   (model not loaded in staging)
PASS [004/247] en→zh idiom   BLEU:0.76 COMET:0.85
FAIL [005/247] zh→ja keigo   BLEU:0.61 (< threshold 0.65)
...
[14:33:18] 243 passed, 2 failed, 2 skipped — 98.4% pass rate

performance_profiler

延迟多少、吞吐多少、瓶颈在哪里——数据说话。

latency_breakdown

延迟拆解

一个翻译请求的总延迟拆成三段:网络往返时间、服务端排队时间、模型推理时间。哪段拖后腿一目了然。如果在东京部署一套边缘节点能把网络延迟从200ms压到40ms,报告里会直接给你这个建议。

throughput_test

吞吐量压测

设置并发数梯度(1/5/10/20/50),每个梯度持续60秒,记录QPS、平均延迟和错误率。自动标出"性能拐点"——也就是再往上加并发延迟就开始指数级上升的那个点。

$ traneasy perf latency-breakdown --api v2 --region ap-southeast-1

网络往返
42ms
服务端排队
23ms
模型推理
198ms

总延迟: 263ms | 模型推理占比 75.3% — 建议:开启量化推理可将推理时间降低约40%

error_diagnostics

API返回的错误码有时候像谜语。我们把它翻译成人话,顺便告诉你怎么修。

ERR_401

认证失败

API Key过期、被撤销,或者你传错了Header字段名。检查Authorization header是不是"Bearer sk-xxx"格式。管理后台可以看到Key的最后使用时间和IP。

ERR_429

速率限制

短时间内的请求数超出了你套餐的上限。标准版是1000次/天、专业版10000次/天。响应Header里有X-RateLimit-Remaining和X-RateLimit-Reset,程序里读这两个字段做退避重试。

ERR_413

请求体过大

单次请求的文本超过了上限(标准版5000字符,专业版50000字符)。对长文档先做分段再逐段请求,或者切到企业版解除限制。

ERR_500

服务端内部错误

这是我们的问题,不是你的。500错误会自动触发PagerDuty告警,值班工程师5分钟内介入。你在Playground里可以一键生成错误报告(含request_id),发给技术支持团队排查。

ERR_422

参数校验失败

source或target传了不支持的语言代码、text字段为空、formality参数的值不在[auto, formal, informal, neutral]范围内。响应Body的errors数组会精确指出哪个字段有问题。

ERR_504

上游超时

模型推理时间过长,超过了网关的60秒超时限制。长文本翻译建议改用异步接口(POST /v2/translate/async),提交后拿task_id轮询结果,不阻塞你的HTTP连接。

sdk_reference

你熟悉的语言,我们都有对应的SDK。GitHub上开源,欢迎提PR。

ci_cd_integration

把翻译质量检测嵌入你的CI/CD流水线。每次提交代码,自动验证i18n翻译的完整性。

🔧

GitHub Actions

配置 .github/workflows/translate-check.yml,push时自动跑回归测试
🔵

GitLab CI

.gitlab-ci.yml 中加入 traneasy/test 镜像,MR时在Pipeline中显示测试报告
🔋

Jenkins

Jenkinsfile中调用 traneasy CLI,生成JUnit格式的测试结果直接渲染到构建页面
🚀

CircleCI

使用 traneasy/test Orb,三步完成安装→测试→结果上传

faq

Playground消耗API额度吗?跟生产环境的API调用有什么不同?

Playground里的每次请求都计入你的API调用额度,跟生产环境一样走实际计费。区别在于Playground额外提供了调试信息——完整的请求/响应日志、token拆解、延迟分项——这些在生产环境的响应Body里不会返回,只在Playground可见。Mock模式下的请求不消耗额度。

测试套件的回归测试用例怎么定义?需要自己写BLEU阈值吗?

最简单的用例格式就是一个JSON数组,每条包含source、target、text、expected四个字段。BLEU阈值默认0.65,你可以在suite配置里调整。对于精确度要求高的场景(比如法律条款翻译),建议把阈值设到0.80以上,并增加人工标注的"必须包含关键词"校验规则。

Mock服务器返回的数据跟真实API格式完全一致吗?

JSON结构、字段名、数据类型和HTTP状态码全部保持一致。差异在于Mock返回的translated字段是随机生成的假译文(比如把文本中的每个词随机换成同长度字符串),confidence值固定0.9。你不能用Mock数据测翻译质量,但可以用它测你的错误处理逻辑和UI渲染。

性能分析工具会对我正在使用的API造成影响吗?

压测工具通过独立的测试通道发送请求,不会跟你生产环境的流量共用连接池。但如果你用的套餐有并发限制(标准版最多5并发、专业版20并发),压测期间的请求会占用这些 slot。建议在低流量时段跑压测,或者提前申请临时提高并发上限。

CI/CD集成里的测试会影响构建速度吗?

看你的测试集大小。一个50条用例的回归套件跑完大约需要90-120秒。我们建议把翻译测试放在CI流水线的非阻塞阶段(比如GitHub Actions中设为continue-on-error: true),这样即使某项翻译质量暂时不达标也不会直接打断部署。测试结果可以在构建摘要中查看,不影响合并按钮。

SDK支持流式(streaming)翻译吗?

Python、JavaScript、Go三个SDK从v3.1开始完整支持SSE流式传输。调用时设置stream=True,SDK返回一个迭代器/AsyncIterator,你可以逐token地处理翻译结果、更新进度条或渲染打字机效果。Java和.NET的流式支持在v3.2中已经加入。其他语言暂不支持,可以通过原生HTTP库调用SSE端点。

错误诊断的ERR_500发生时,我的请求数据安全吗?

500错误期间,你的请求在服务端触发异常后原始数据被隔离在错误日志系统里,只有经审批的值班工程师在排查时才能访问。错误日志保留7天,到期自动清除。你需要确认你的请求是否包含敏感数据——如果有,建议在发送前做脱敏处理。诊断报告里只会包含request_id和错误堆栈,不会附带你的原始文本。