baidu-file-translate — Agent Reference
File translation is async. Always use the submit → poll loop below.
Never rely on --wait without a timeout — it may block indefinitely in an
Agent framework.
Step 1: trans file submit <file> --from auto --to <lang> --json
→ exit ≠ 0 → ⚠ STOP if exit 2 (auth/config); handle others (see Error Handling)
→ exit 0 → record request_id from stdout
Step 2: every 5 s: trans file query <request_id> --json
→ exit ≠ 0 → handle error; DOC_FAILED = don't retry
→ exit 0, status=processing → keep polling (set Agent timeout ≤ 10 min)
→ exit 0, status=done → ⚠ confirm with user before downloading
then: trans file query <request_id> --download --output ./
→ WAIT_TIMEOUT → ⚠ STOP — save request_id, report to user
Set an Agent-level timeout (e.g. 10 min). On WAIT_TIMEOUT, save the request_id and report to user — the job is still running and can be resumed later.
trans file submit <file>
trans file submit report.pdf --from zh --to en --json
trans file submit report.pdf --to en --reference "Use academic tone"
| Flag | Default | Description |
|---|---|---|
--from |
auto | Source language (auto-detect) |
--to |
zh | Target language — auto is not accepted |
--reference |
— | Custom translation instruction, ≤ 1000 Unicode code points |
--trans-image |
false | Also translate text inside images |
--wait |
false | Block until done (always pair with --wait-timeout) |
--wait-timeout |
0 (no limit) | Max wait time for --wait mode |
trans file query <requestId>
trans file query REQ123 --json
trans file query REQ123 --download --output ./output/
| Flag | Default | Description |
|---|---|---|
--download |
false | Download the translated file when done |
--output |
./ | Download directory (used with --download) |
--wait |
false | Block until done |
--wait-timeout |
0 (no limit) | Max wait time for --wait mode |
JSON Contract
submit success (stdout):
{"request_id": "REQ123", "status": "submitted"}
query — in progress (stdout):
{"request_id": "REQ123", "status": "processing", "name": "report.pdf", "from": "zh", "to": "en"}
query — done (stdout):
{"request_id": "REQ123", "status": "done", "file_url": "https://...", "char_count": 1000, "amount": 70}
With --download, the done response gains:
{"local_path": "/absolute/path/to/report_en.pdf"}
error (stderr, exit ≠ 0):
{"code": "AUTH_FAILED", "message": "...", "help_url": "https://fanyi-api.baidu.com/manage/apiKey"}
help_url is omitted when not applicable.
Error Handling
exit ≠ 0
├── CONFIG_MISSING (exit 2) → guide user to set TRANS_API_KEY
├── AUTH_FAILED (exit 2) → key invalid/expired; check fanyi-api.baidu.com/manage/apiKey
├── QUOTA_EXCEEDED (exit 3) → balance exhausted; recharge, then retry
├── RATE_LIMITED (exit 3) → back off 30 s, then retry
├── NETWORK_ERROR (exit 4) → check connectivity, retry
├── DOC_FAILED (exit 3) → server-side failure; do NOT retry
├── INVALID_INPUT (exit 1) → fix file path / format / --to value
└── WAIT_TIMEOUT (exit 1) → job still running; save request_id and resume later
stderr carries errors only — there are no progress events on stderr.
Supported Formats
docx / doc / pdf / xlsx / xls / pptx / ppt / html / htm / txt / xml / md
file_url expires after 30 days.