Baidu Text Translate

Translate text using Baidu AI Translation API via trans-cli with Baidu-specific language codes, API key management, error handling, and environment diagnostics.

Security Scan

The skill's instructions match its translation purpose, but the manifest and SKILL.md disagree about required binaries, install steps, and config paths—these inconsistencies warrant caution before installing or running it.

Purpose & Capability

The SKILL.md describes a translation helper that uses trans-cli to call Baidu's Translation API — that purpose is coherent with the described actions (trans text, trans doctor, trans config). However the top-level registry metadata/manifest claims no required binaries or config paths, while the SKILL.md metadata clearly declares the trans binary and an npm install for @bdtrans/trans-cli. This mismatch is unexpected and should be resolved by the author.

Instruction Scope

Runtime instructions are narrowly scoped to running trans-cli commands, parsing its JSON output, diagnosing via `trans doctor`, and reading/writing the trans-cli config (~/.trans-cli/config.json) or TRANS_API_KEY. The skill does not instruct collecting unrelated files or secrets beyond the API key and config file. It explicitly states the agent cannot obtain the key for the user.

Install Mechanism

SKILL.md contains metadata that suggests an npm install of @bdtrans/trans-cli (a public npm package) which is a reasonable install mechanism. But the registry-level install spec is reported as absent — another inconsistency. Installing from a public npm package is moderate-risk (verify package provenance and source); there are no high-risk direct-download URLs in the instructions.

Credentials

The skill requires an API key (TRANS_API_KEY or config file field api_key) to function per SKILL.md. The top-level manifest, however, lists no required env vars or config paths. The requested credential (Baidu API key) is proportionate to the stated purpose, but the manifest/metadata disagreement is a red flag: the skill may assume access to ~/.trans-cli/config.json and TRANS_API_KEY even though the registry doesn't declare them.

Persistence & Privilege

The skill does not request always:true or any special persistent privileges. It documents how to write the API key to the trans-cli config, but explicitly says the agent cannot perform the developer portal steps — no unexpected autonomous escalation is indicated.

What to consider before installing

This skill appears to do what it says (wrap trans-cli for Baidu translation), but there are inconsistencies between the SKILL.md and the registry manifest you should resolve before installing: 1) Confirm the trans binary requirement and whether the skill intends to install @bdtrans/trans-cli via npm. 2) Verify the npm package name (@bdtrans/trans-cli) and inspect its source repository and npm page for trustworthiness (owner, downloads, recent releases). 3) Be aware you must supply a Baidu TRANS_API_KEY or write it to ~/.trans-cli/config.json; check that file's permissions and contents before saving secrets there. 4) Prefer installing trans-cli yourself or reviewing the package code rather than blindly running the skill's install step. 5) If you need certainty, ask the skill author to fix the manifest so required env vars, bins, and install steps are declared consistently.

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.

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:

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

JSON contract (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
}

Exit	all_ok	Meaning
0	true	All checks passed — ready to translate
2	false	At 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):

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

Field	Note
from	API-detected language — may differ from --from auto
to	Target language
source	Original input
translated	Result

Error (stderr, exit ≠ 0):

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

help_url and raw_code are omitted when not applicable.

---

Error Decision Tree

Exit	code	Cause	Action
0	—	OK	Use translated
1	INVALID_INPUT	Empty text	Fix input, don't retry
1	INVALID_LANGUAGE	Wrong lang code (e.g. ja → should be jp)	Fix --to/--from, see Language Codes below
2	CONFIG_MISSING	TRANS_API_KEY not set	Stop — run trans doctor --json then guide user to set up API key
2	AUTH_FAILED	Key invalid/expired (raw_code 52001–52003)	Stop — run trans doctor --json then guide user to API key page
3	QUOTA_EXCEEDED	Balance = 0	Stop — guide user to recharge (see below)
3	RATE_LIMITED	QPS exceeded	Wait 1 s, retry once
3	API_ERROR	Unexpected API error	Retry once; if persists, report raw_code + message
4	NETWORK_ERROR	No connectivity	Retry 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:

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)	Language
jp	ja	Japanese
kor	ko	Korean
fra	fr	French
spa	es	Spanish
ara	ar	Arabic
vie	vi	Vietnamese

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.

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