baidu-text-translate

intent

use this skill to translate text via the baidu ai translation api when you need to convert content between languages. the trans command wraps baidu's api and outputs structured json for parsing. trigger this skill whenever translating text, setting up api keys for the first time, debugging translation failures, checking environment health, or looking up baidu-specific language codes (which do not follow iso 639 standards).

inputs

external connection: baidu ai translation api

• setup: create free account at https://fanyi-api.baidu.com/, register for general translation, obtain api key from https://fanyi-api.baidu.com/manage/apiKey
• auth method: api key (bearer token)
• env var: TRANS_API_KEY (or stored in ~/.trans-cli/config.json under api_key field)
• rate limit: check usage at https://fanyi-api.baidu.com/api/trans/user/usage
• quota: free tier includes limited monthly characters; recharge at https://fanyi-api.baidu.com/manage/account if quota_exceeded error occurs

binary requirement

• trans command (installed via npm: npm install -g @bdtrans/trans-cli)

parameters for translation

• text: the string to translate (can be positional arg or stdin pipe)
• --from: source language code (use auto for auto-detect; baidu codes differ from iso 639, see language codes table below)
• --to: target language code (required; same baidu-specific codes)
• --reference: optional instruction string to influence translation tone/style (sent to api)
• --json: mandatory flag for structured output parsing (separates stdout success from stderr errors)
• --api-key: optional flag override (takes priority over env var and config file)

environment context

• shell access with trans-cli installed and in $PATH
• network connectivity to baidu api (https://fanyi-api.baidu.com)
• ability to read/write ~/.trans-cli/config.json (or set env var)

procedure

step 1: verify environment health

input: none (diagnostic step) action: run trans doctor --json to check api key, connectivity, and account status before any translation attempt output: json object with checks array and all_ok boolean; exit code 0 if all checks pass, 2 if any fails

parse the result:

• if all_ok: true, proceed to step 2
• if all_ok: false, inspect checks[].ok and checks[].message; identify which check failed (api_key, connectivity, or account)
• if api_key check failed, move to step 3a (configure api key)
• if account check failed, move to step 3b (recharge or fix key)
• if connectivity check failed, retry once after 2 second wait; if persists, report network error

step 2: run translation

input: text string, source language code (or auto), target language code, optional reference instruction action: execute trans text --json --from <SOURCE> --to <TARGET> [--reference "<INSTRUCTION>"] "<TEXT>" or pipe via echo/stdin output: json object on stdout with fields from, to, source, translated; or json error object on stderr with code, message, help_url, raw_code exit code: 0 on success, non-zero on failure (see decision points)

examples:

trans text --json --to en "你好世界"
trans text --json --from zh --to jp --reference "使用正式语气" "你好"
echo "早上好" | trans text --json --to en
trans text --json --to fra "bonjour"

step 3a: first-time api key setup (if missing)

input: user has baidu account but no api key configured action: guide user through these manual steps (agent cannot perform on behalf):

1. open https://fanyi-api.baidu.com/ and sign in with baidu account
2. navigate to https://fanyi-api.baidu.com/manage/developer
3. click "use now", select "general translation", complete identity verification if prompted
4. retrieve api key from https://fanyi-api.baidu.com/manage/apiKey (copy the key string)
5. store key via one of these methods:
   • trans config set api_key <KEY> (creates ~/.trans-cli/config.json if absent)
   • or set environment variable: export TRANS_API_KEY=<KEY>
6. verify setup: run trans doctor --json and confirm all_ok: true output: api key configured; doctor command exits 0

step 3b: recharge quota (if quota_exceeded error)

input: quota_exceeded error (exit code 3) from translation attempt action: guide user to https://fanyi-api.baidu.com/manage/account to recharge balance (takes effect immediately, no restart required); user can enable auto-renewal on same page output: account recharged; retry translation from step 2

step 4: look up language code (if invalid_language error)

input: error code invalid_language or uncertainty about baidu language codes action: query supported languages locally via trans languages --json [--filter <KEYWORD>] output: json array of language objects with code, name, and aliases; or run without --json for human-readable table

examples:

trans languages --json                        # all 200+ languages
trans languages --filter jp                   # search by code
trans languages --filter 日语                 # search by name

reference the common iso traps in the table below if code is wrong.

step 5: parse and handle errors

input: non-zero exit code from trans command action: parse json stderr to extract code field; dispatch to appropriate handler (see decision points section) output: error code and message identified; action taken (retry, fix input, configure auth, etc.)

decision points

if exit code is 0

• success. extract and use translated field from stdout json.

if exit code is 1 (invalid input or invalid language)

• if code: INVALID_INPUT: input text is empty or malformed. fix the text and retry; do not retry the same call.
• if code: INVALID_LANGUAGE: source or target language code is wrong (often iso 639 mistake like ja instead of jp for japanese). check language codes section and run trans languages --filter <CODE> to verify; fix --from or --to flag and retry.

if exit code is 2 (config or auth failure)

• if code: CONFIG_MISSING: environment variable TRANS_API_KEY is not set and no config file exists. stop. run trans doctor --json to diagnose; guide user through step 3a (first-time setup).
• if code: AUTH_FAILED with raw_code in range 52001-52003: api key is invalid, expired, or revoked. stop. run trans doctor --json to confirm account check failure; guide user to https://fanyi-api.baidu.com/manage/apiKey to refresh key, then re-run trans config set api_key <NEW_KEY> and step 2.

if exit code is 3 (quota or rate limit)

• if code: QUOTA_EXCEEDED: user balance is zero. stop. guide user through step 3b (recharge at https://fanyi-api.baidu.com/manage/account).
• if code: RATE_LIMITED: qps (queries per second) limit exceeded. wait 1 second and retry once; if second attempt also rate-limits, report to user that api is under heavy load.
• if code: API_ERROR with raw_code: unexpected baidu api error. retry once immediately; if error persists on second attempt, report raw_code and message to user for investigation or escalation.

if exit code is 4 (network error)

• if code: NETWORK_ERROR: no connectivity to baidu api. retry twice with 2 second gap between retries; if both retries fail, report network connectivity issue and suggest checking firewall/proxy/internet connection.

if doc/list/config commands are used instead of translation

• trans doctor --json: environment diagnostic (step 1; exit 0 if all_ok, 2 if any check fails)
• trans languages --json: language code lookup (step 4; exit 0 always)
• trans config set api_key <KEY>: api key configuration (step 3a; exit 0 on success)

output contract

success case (exit 0)

• stdout: valid json object with four fields: from (detected source language code), to (target language code), source (original input string), translated (translated output string)
• stderr: empty
• file location: none (output is stdout, not persisted)
• format example: {"from":"zh","to":"en","source":"你好","translated":"Hello"}

error case (exit 1, 2, 3, or 4)

• stdout: empty
• stderr: valid json object with at least two fields: code (error code string), message (human-readable error description); may include optional fields help_url (link to fix) and raw_code (baidu api raw error code)
• format example: {"code":"AUTH_FAILED","message":"invalid api key","help_url":"https://fanyi-api.baidu.com/manage/apiKey","raw_code":"52001"}

doctor diagnostic (exit 0 or 2)

• stdout: json object with top-level checks array (each check has name, ok boolean, message, and optional latency_ms or help_url) and all_ok boolean
• format example:

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

language list (exit 0)

• stdout (with --json flag): array of objects, each with fields code, name, and optional aliases
• stdout (without --json flag): human-readable table with columns code, name, aliases

outcome signal

translation succeeded

• exit code 0, stdout contains valid json with non-empty translated field matching expected target language
• user can inspect from field to see which source language baidu detected
• no errors on stderr

environment is healthy

• trans doctor --json returns all_ok: true and exit 0
• all three checks (api_key, connectivity, account) report ok: true

api key is configured

• trans config set api_key <KEY> exits 0
• subsequent trans doctor --json call has api_key.ok: true

quota needs recharge

• translation attempt returns exit 3 with code: QUOTA_EXCEEDED
• user visits https://fanyi-api.baidu.com/manage/account, adds credit, and can immediately retry translation

language code was corrected

• trans languages --filter <KEYWORD> returns matching language code
• translation retry with corrected --from or --to flag exits 0 with translated result

network or auth issue identified

• trans doctor --json pinpoints which check failed (connectivity, api_key, or account) with ok: false and descriptive message
• user takes corresponding action (configure key, fix network, recharge quota, etc.)