# LiteTranslate Skill Install Guide (for AI Agents)

> This page is the **self-install / self-update guide** for the LiteTranslate skill (a free Chinese↔English translation API by Lite Lake / 轻湖, powered by LiteRouter). You (the AI agent) can complete installation or update by following the steps below — no human intervention needed.
>
> **Current version: 1.0.0**

## What this is

Once installed, you can translate text or Markdown between Chinese and English with one command. In `markdown` format the server conserves structure: fenced code blocks, `[text](url)` links and `![alt](url)` images are counted on both sides, retried on drift, and rejected (`50023`) rather than returning broken Markdown. The skill has two files, both served by this deployment:

| File | URL |
|---|---|
| `SKILL.md` (skill description / trigger rules) | `https://translate.litelake.com/skill/SKILL.md` |
| `litetranslate.py` (stdlib-only CLI, zero dependencies) | `https://translate.litelake.com/skill/litetranslate.py` |

This site is the public entry of the current deployment — the URLs above work as-is, and the skill connects back to this entry by default.

**Communication**: the skill and CLI speak English, but you should always converse with the user in the user's own language (e.g. reply in Chinese if the user writes Chinese).

## Install steps

### Step 1: pick a skills directory

Pick the skills directory for your platform (reuse it if it exists, otherwise create it):

| Platform | Skills directory |
|---|---|
| ZCode / DSH | `~/.agents/skills/litetranslate` |
| Claude Code | `~/.claude/skills/litetranslate` |
| Codex | `~/.codex/skills/litetranslate` |
| Pi Coding Agent | `~/.pi/agent/skills/litetranslate` |
| OpenClaw | `~/.openclaw/skills/litetranslate` |
| Other / generic | `~/.agents/skills/litetranslate` |

### Step 2: download the skill files (install or update; idempotent overwrite)

```bash
mkdir -p "$SKILLS_DIR/litetranslate" && cd "$SKILLS_DIR/litetranslate" \
  && curl -fsSL https://translate.litelake.com/skill/SKILL.md -o SKILL.md \
  && curl -fsSL https://translate.litelake.com/skill/litetranslate.py -o litetranslate.py
```

### Step 3: verify

```bash
python3 litetranslate.py --version
# expected output: litetranslate-skill 1.0.0
python3 litetranslate.py doctor --offline
```

Once verified, read `SKILL.md` for the trigger rules and command usage (`translate` / `languages` / `usage` / `doctor`), then follow it when the user asks to translate Chinese/English text or Markdown.

## Configure

- Get an API key from the LiteTranslate product site (Account page → create key; keys look like `ltr_<env>_<32hex>`, free tier 100 translations/hour per user).
- Config directory: `~/.lite-lake/lite-translate/` (Windows: `C:\Users\<user>\.lite-lake\lite-translate`), file `config.json`:

```bash
mkdir -p ~/.lite-lake/lite-translate && chmod 700 ~/.lite-lake/lite-translate
cat > ~/.lite-lake/lite-translate/config.json <<'EOF'
{
  "base_url": "https://translate.litelake.com",
  "api_key": "PASTE_KEY_HERE"
}
EOF
chmod 600 ~/.lite-lake/lite-translate/config.json
```

- Key input preference: `--api-key-stdin` (recommended) or `LITETRANSLATE_API_KEY` env var. `--api-key` inline is supported but discouraged — it lands in shell history and the process list. The CLI never prints the key.
- Secrets stay out of the skill directory, so updates never touch credentials.

## Quick start

```bash
# Translate plain text (auto-detect direction)
python3 litetranslate.py translate --text "你好，世界" --target en --json

# Translate Markdown keeping code blocks / links / images intact
python3 litetranslate.py translate --text "$MD_DOC" --source auto --target en --format markdown --json

# Supported languages and quota usage
python3 litetranslate.py languages --json
python3 litetranslate.py usage --json
```

## Error codes quick reference

| code | meaning | what to do |
|---|---|---|
| 40001 | invalid params | fix arguments; do not retry blindly |
| 40021 | text > 5000 chars | split or shorten, then retry |
| 40022 | direction unsupported (not zh↔en / source == target) | fix `--source`/`--target` |
| 40101 | API key invalid/revoked | ask the user for a new key; do not retry |
| 40301 | key owner banned | tell the user; do not retry |
| 42901 | quota exceeded (429) | wait for `Retry-After` / `usage.reset_at`, then retry once |
| 50021 / 50022 | upstream error / timeout | retry once; split long texts |
| 50023 | Markdown structure check failed after retry | retry once or fall back to `--format text` |
| 50024 | quota storage unavailable (fail-closed) | retry after a pause |

## Update check

If already installed, compare the version at the top of this page with the installed one:

```bash
python3 litetranslate.py --version
```

For a machine-readable check (requires the configured key), query
`https://translate.litelake.com/api/open/version` (`server_version` / `min_skill_version` /
`recommended_skill_version` / `protocol_version`).

If the printed version is older than `1.0.0`, re-run Step 2 to overwrite (the files are stateless; configuration at `~/.lite-lake/lite-translate/` survives updates).