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:
# 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:
# 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 ~/.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
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:
# 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 emptyAPI_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
