baidu_text_translate — Agent Reference#

trans text wraps the Baidu AI Translation API. Use --json — it separates success (stdout) from errors (stderr) and gives you structured fields to act on.

bash

trans text --json "你好世界"                             # auto-detect → English
trans text --json --from zh --to jp "你好"               # explicit languages
trans text --json --to fra --reference "使用正式语气" "你好"  # custom instruction
echo "早上好" | trans text --json                        # stdin pipe

---

Environment Diagnosis#

Before translating, verify the environment with trans doctor:

bash

trans doctor           # human-readable output
trans doctor --json    # JSON output for Agent parsing

JSON contract (stdout):

json

{
  "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
}

Exitall_okMeaning0trueAll checks passed — ready to translate2falseAt least one check failed — inspect checks[].ok

When a check fails, help_url in the failing check points to the fix:

• api_key.ok:false → set TRANS_API_KEY (see Configuration below)
• account.ok:false → key invalid/expired or quota exhausted

Run trans doctor --json as the first step when diagnosing any trans-cli failure.

---

JSON Contract#

Success (stdout, exit 0):

json

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

FieldNotefromAPI-detected language — may differ from --from auto``toTarget languagesourceOriginal inputtranslatedResult

Error (stderr, exit ≠ 0):

json

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

help_url and raw_code are omitted when not applicable.

---

Error Decision Tree#

ExitcodeCauseAction0—OKUse translated1INVALID_INPUTEmpty textFix input, don't retry1INVALID_LANGUAGEWrong lang code (e.g. ja → should be jp)Fix --to/ --from, see Language Codes below2CONFIG_MISSING``TRANS_API_KEY not setStop — run trans doctor --json then guide user to set up API key2AUTH_FAILEDKey invalid/expired ( raw_code 52001–52003)Stop — run trans doctor --json then guide user to API key page3QUOTA_EXCEEDEDBalance = 0Stop — guide user to recharge (see below)3RATE_LIMITEDQPS exceededWait 1 s, retry once3API_ERRORUnexpected API errorRetry once; if persists, report raw_code + message4NETWORK_ERRORNo connectivityRetry twice with 2 s gap; if persists, report

Exit 2 requires human intervention — the agent cannot fix auth or config. Exit 1 means the agent passed bad arguments — fix the call, not the environment.

---

Language Codes#

Baidu does not follow ISO 639. When unsure of a code, query locally:

bash

trans languages                    # full list (200+ languages)
trans languages --filter jp        # search by code
trans languages --filter 日语      # search by name
trans languages --json             # JSON output for Agent parsing

The six most common ISO traps:

Baidu (correct)ISO (wrong for Baidu)Languagejp``jaJapanesekor``koKoreanfra``frFrenchspa``esSpanishara``arArabicvie``viVietnamese

Other common codes that match ISO: zh cht en ru de pt it nl hi th Use auto for source-language auto-detection.

---

Configuration#

Priority: --api-key flag > TRANS_API_KEY env > ~/.trans-cli/config.json

Config file field: api_key.

bash

trans config init               # create empty config skeleton (~/.trans-cli/config.json)
trans config init --force       # overwrite existing config
trans config set api_key <KEY>  # write api_key (creates file if absent)

---

Getting an API Key (First-Time Setup)#

Guide the user through these steps — the agent cannot do this on their behalf:

1. Open the Baidu Translation Open Platform and sign in: https://fanyi-api.baidu.com/
2. Go to Developer Center: https://fanyi-api.baidu.com/manage/developer
3. Click "Use Now" → select "General Translation" → complete identity verification
4. Get your API Key: https://fanyi-api.baidu.com/manage/apiKey
5. Write to config: trans config set api_key <KEY> or set the environment variable TRANS_API_KEY
6. Verify: trans doctor --json — all_ok:true means success

---

Recharging (QUOTA_EXCEEDED)#

Recharge portal: https://fanyi-api.baidu.com/manage/account Takes effect immediately — no restart needed. Auto-renewal can be enabled on the same page. Usage details: https://fanyi-api.baidu.com/api/trans/user/usage

---

Non-Obvious Behaviours#

• Multiple positional args join with a space: trans text hello world → "hello world"
• When both stdin and positional args are given, positional args win silently
• The from field in JSON is the API's detected language, not the --from flag value
• trans doctor checks are short-circuit: if api_key fails, connectivity/account are skipped
• --reference is optional; omitting it sends no extra field to the API