baidu_text_translate — Agent 参考文档

trans text 封装了百度 AI 翻译 API。请务必使用 --json 参数——它将成功响应（stdout）与错误信息（stderr）分离，并提供结构化的字段供程序逻辑处理。

trans text --json "你好世界"                             # 自动检测源语言 → 英语
trans text --json --from zh --to jp "你好"               # 显式指定源/目标语言
trans text --json --to fra --reference "使用正式语气" "你好"  # 自定义指令
echo "早上好" | trans text --json                        # 通过 stdin 管道输入

环境诊断

执行翻译前，请先用 trans doctor 验证运行环境：

trans doctor           # 人类可读格式输出
trans doctor --json    # JSON 格式输出，便于 Agent 解析

JSON 协议规范（stdout）：

{
  "checks": [
    {"name":"api_key",     "ok":true,  "source":"env/config", "message":"configured"},
    {"name":"connectivity","ok":true,  "latency_ms":243,       "message":"reachable"},
    {"name":"account",     "ok":true,                          "message":"valid"}
  ],
  "all_ok": true
}

当某项检查失败时，该检查项中的 help_url 字段会指向对应问题的修复指引：

• api_key.ok:false → 设置环境变量 TRANS_API_KEY（参见下方“配置”章节）
• account.ok:false → API 密钥无效/已过期，或配额已耗尽

在排查任意 trans-cli 故障时，第一步应始终运行 trans doctor --json。

JSON 协议规范

成功响应（stdout，退出码为 0）：

{"from":"zh","to":"en","source":"你好","translated":"Hello"}

错误响应（stderr，退出码非 0）：

{"code":"AUTH_FAILED","message":"…","help_url":"https://…","raw_code":"52001"}

若不适用，help_url 和 raw_code 字段将被省略。

错误决策树

退出码为 2 表示需人工介入 — Agent 无法自动修复认证或配置问题。
退出码为 1 表示 Agent 调用时传入了非法参数 — 应修正调用方式，而非修改环境。

语言代码

百度平台不遵循 ISO 639 标准。若不确定某语言的正确代码，可通过本地命令查询：

trans languages                    # 完整语言列表（支持 200+ 种语言）
trans languages --filter jp        # 按代码搜索
trans languages --filter 日语      # 按名称搜索
trans languages --json             # JSON 格式输出，便于 Agent 解析

最常被误用的六种 ISO 语言代码（陷阱示例）：

其余常见语言代码与 ISO 一致：zh cht en ru de pt it nl hi th
源语言可使用 auto 启用自动检测。

配置

配置优先级： --api-key 命令行参数 > TRANS_API_KEY 环境变量 > ~/.trans-cli/config.json 配置文件

配置文件中对应字段名为：api_key。

trans config init               # 创建空配置骨架（~/.trans-cli/config.json）
trans config init --force       # 覆盖已有配置文件
trans config set api_key   # 写入 api_key（如文件不存在则自动创建）

获取 API 密钥（首次配置）

请引导用户按以下步骤操作 — Agent 无法代为完成：

1. 访问百度翻译开放平台并登录：https://fanyi-api.baidu.com/
2. 进入开发者中心：https://fanyi-api.baidu.com/manage/developer
3. 点击“立即使用” → 选择“通用翻译” → 完成实名认证
4. 获取您的 API 密钥：https://fanyi-api.baidu.com/manage/apiKey
5. 写入配置：trans config set api_key ，或设置环境变量 TRANS_API_KEY
6. 验证配置：trans doctor --json — 若返回 all_ok:true 则表示成功

充值（QUOTA_EXCEEDED）

充值入口：https://fanyi-api.baidu.com/manage/account
充值即时生效，无需重启服务。同一页面可开启自动续费。
用量详情：https://fanyi-api.baidu.com/api/trans/user/usage

非显而易见的行为

• 多个位置参数将被空格拼接：trans text hello world → 实际发送 "hello world"
• 同时提供 stdin 输入和位置参数时，位置参数将静默覆盖 stdin 内容
• JSON 响应中的 from 字段为 API 实际检测到的语言代码，并非 --from 参数值
• trans doctor 的各项检查采用短路机制：若 api_key 检查失败，则跳过后续的 connectivity/account 检查
• --reference 为可选参数；若未指定，则不会向 API 发送额外字段