Translate TXT

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翻译.

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

text

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