Translate text files using OpenAI-compatible APIs (e.g. SiliconFlow, DeepSeek, OpenAI). Use when the user wants to: translate a txt file, translate text to C...
---
name: translate-txt
description: |
Translate text files using OpenAI-compatible APIs (e.g. SiliconFlow, DeepSeek, OpenAI).
Use when the user wants to: translate a txt file, translate text to Chinese or other languages,
batch translate documents, or convert foreign language txt files to Chinese.
Triggers: 翻译txt文件, 翻译文本, translate txt, translate file, 文件翻译, txt翻译.
metadata:
config:
- key: TRANSLATE_API_KEY
description: API key for the translation service
required: true
- key: TRANSLATE_BASE_URL
description: Base URL for OpenAI-compatible API
default: https://api.siliconflow.cn/v1
- key: TRANSLATE_MODEL
description: Model name to use
default: Qwen/Qwen2.5-7B-Instruct
---
# translate-txt Skill
Translate `.txt` files using any OpenAI-compatible API. Defaults to SiliconFlow with Qwen model, translating foreign languages to Chinese.
## Features
- Supports any OpenAI-compatible API (SiliconFlow, DeepSeek, OpenAI, etc.)
- Auto-detects source language, defaults to translating into Chinese
- Handles large files by chunking at paragraph/sentence boundaries
- **Concurrent translation** — multiple chunks translated in parallel
- **Sliding-window context** — each chunk gets glossary + background from nearby chunks; new terms auto-propagate, stale context naturally fades as the window slides
- Automatic retry with exponential backoff on timeout and transient errors
- Preserves original formatting and structure
## File Structure
```
translate-txt/
├── SKILL.md # Skill definition
├── .env # User configuration (created by setup)
├── setup.sh # Setup script (interactive & non-interactive)
└── scripts/
└── translate.py # Translation script
```
## Configuration
The script reads config from the `.env` file in the skill root directory, falling back to environment variables.
| Variable | Default | Description |
|---|---|---|
| `TRANSLATE_API_KEY` | (none, required) | API key for the translation service |
| `TRANSLATE_BASE_URL` | `https://api.siliconflow.cn/v1` | Base URL for OpenAI-compatible API |
| `TRANSLATE_MODEL` | `Qwen/Qwen2.5-7B-Instruct` | Model name to use |
| `TRANSLATE_THINKING` | `auto` | Thinking mode: `auto`/`disabled` (recommended) or `enabled` |
| `TRANSLATE_MAX_TOKENS` | `4096` | Max output tokens per chunk |
| `TRANSLATE_TEMPERATURE` | `1` | Model temperature |
| `TRANSLATE_TIMEOUT` | `300` | API request timeout in seconds |
Priority: environment variables > `.env` file > defaults.
## How to Use
### Step 1: Check & Setup Configuration
Before first use, check if the API key is configured. The script loads config from the `.env` file in the skill directory, falling back to environment variables.
**If `.env` does not exist or `TRANSLATE_API_KEY` is empty**, ask the user for their API key and preferred provider, then run:
```bash
# Non-interactive setup (for AI agent):
bash ~/.comate/skills/translate-txt/setup.sh --api-key <KEY> --provider <PROVIDER>
# Providers: siliconflow (default), deepseek, openai
# Or specify full config:
bash ~/.comate/skills/translate-txt/setup.sh --api-key <KEY> --base-url <URL> --model <MODEL>
```
**Examples:**
```bash
# SiliconFlow (default)
bash ~/.comate/skills/translate-txt/setup.sh --api-key sk-xxx --provider siliconflow
# DeepSeek
bash ~/.comate/skills/translate-txt/setup.sh --api-key sk-xxx --provider deepseek
# OpenAI
bash ~/.comate/skills/translate-txt/setup.sh --api-key sk-xxx --provider openai
# Custom endpoint
bash ~/.comate/skills/translate-txt/setup.sh --api-key sk-xxx --base-url https://my-api.example.com/v1 --model my-model
```
The user can also run the interactive setup manually:
```bash
bash ~/.comate/skills/translate-txt/setup.sh
```
On success, the script outputs `CONFIG_SAVED:<path>`. If the API key is already configured, skip to Step 2.
### Step 2: Run Translation
```bash
python3 ~/.comate/skills/translate-txt/scripts/translate.py <input_file> [options]
```
**Options:**
- `--output <path>` - Output file path (default: `<input>_translated.txt`)
- `--target-lang <lang>` - Target language (default: `Chinese`)
- `--source-lang <lang>` - Source language hint (default: `auto` for auto-detect)
- `--chunk-size <int>` - Max characters per chunk (default: `3000`)
- `--concurrency <int>` - Max concurrent API calls (default: `3`)
- `--context-window <int>` - Number of preceding chunks for sliding context (default: `3`)
**Examples:**
```bash
# Translate a file to Chinese (default)
python3 ~/.comate/skills/translate-txt/scripts/translate.py document.txt
# Translate to Japanese
python3 ~/.comate/skills/translate-txt/scripts/translate.py document.txt --target-lang Japanese
# Specify output path
python3 ~/.comate/skills/translate-txt/scripts/translate.py document.txt --output result.txt
```
### Step 3: Report Result
After the script completes successfully, it outputs the translated file path in the format `OUTPUT:<path>`. Report this to the user.
If the script fails, check the error output:
- `CONFIG_ERROR` - API key not configured. Ask user for their API key, then run `setup.sh --api-key <KEY> --provider <PROVIDER>`
- `FILE_ERROR` - Input file not found or empty
- `API_ERROR` - API call failed (check key, URL, model, and network)
## How It Works
The script uses a three-step approach for multi-chunk files:
**Step 1: Keyword extraction** — Each chunk is processed concurrently with a lightweight prompt to extract proper nouns and domain terms with their translations.
**Step 2: Build per-chunk context** — For each chunk, the script merges keywords from a sliding window of N preceding chunks (default `--context-window 3`). This means:
- New terms introduced in later chapters automatically appear in context for subsequent chunks
- Context naturally shifts as the window slides forward (e.g., chunk 10's context reflects chunks 7-10, not chunks 1-3)
- A background description is inferred from initial chunks and prepended to all contexts
**Step 3: Translation** — All chunks are translated concurrently, each with its own window-scoped context.
Use `--context-window` to control the window size. Larger windows provide more context but may include irrelevant terms from distant sections.
Progress is reported on stderr:
- `KEYWORDS:chunk N/M` / `KEYWORDS_DONE:chunk N/M` (Step 1)
- `TRANSLATING:chunk N/M` / `DONE:chunk N/M` (Step 3)
Results are reassembled in original order.
## Model Selection & Performance
Model choice has a dramatic impact on translation speed. The main factor is whether the model uses **thinking/reasoning mode** — thinking models spend significant time on internal reasoning, which is unnecessary for translation and makes them **5-10x slower**.
**Recommended models (fast, good quality):**
| Model | Provider/Endpoint | Speed | Quality | Notes |
|---|---|---|---|---|
| `deepseek-v3` / `deepseek-v3.2` | DeepSeek or compatible | Fast (~1.5min/28K chars) | Good | Best choice for translation |
| `gpt-4o-mini` | OpenAI | Fast | Good | Cost-effective |
| `Qwen/Qwen2.5-7B-Instruct` | SiliconFlow | Moderate | Decent | Default, good balance |
**Models to avoid for translation:**
| Model | Why |
|---|---|
| `kimi-k2.5` | Thinking model — ~13min/28K chars, 8x slower |
| `kimi-k2-thinking` | Same issue, even more reasoning overhead |
| `deepseek-r1` | Reasoning model, slow for straightforward translation |
**Tips:**
- The script passes `enable_thinking: false` by default (`TRANSLATE_THINKING=auto`). If your API doesn't support this, switch to a non-thinking model.
- For batch translations or large files, prefer `deepseek-v3` or `deepseek-v3.2`.
## Notes
- The script uses only Python standard library (no pip install needed)
- Translation quality depends on the model; larger models generally produce better translations
- Keyword extraction adds one API call per chunk but ensures every term is captured
- Set `--concurrency 1` to disable parallel translation if the API has strict rate limits
- The script preserves original text formatting (paragraphs, line breaks) in the translation
- **Avoid thinking/reasoning models** for translation — much slower with no quality benefit
- **Sliding-window context scales to any text length** — 10 chunks or 1000 chunks work the same way
don't have the plugin yet? install it then click "run inline in claude" again.