llm-translator

name

llm-translator

description

Translate text and files between any languages using LLM APIs (OpenAI, Anthropic, Chinese LLMs, etc.). Use when users request translation tasks like "translate this to English", "翻译成中文", "batch translate these files", or "translate this Markdown file while preserving formatting". Supports direct API calls, config files, environment variables, and multiple translation scenarios (plain text, batch files, format-preserving translation).

LLM Translator

Translate text and files between any languages using customizable LLM APIs.

Quick Start

Option 1: Using Config File (Recommended)

1. Copy the config template:

cp assets/config.template.json translator-config.json

2. Edit translator-config.json with your API credentials:

{
  "api_base": "https://api.openai.com/v1",
  "api_key": "your-api-key-here",
  "model": "gpt-3.5-turbo"
}

3. Run translation:

python scripts/translate.py "Hello world" -t "中文" --config translator-config.json

Option 2: Using Command-line Arguments

python scripts/translate.py "Hello world" \
  -t "Japanese" \
  --api-base "https://api.openai.com/v1" \
  --api-key "your-key" \
  --model "gpt-3.5-turbo"

Option 3: Using Environment Variables

export LLM_API_BASE="https://api.openai.com/v1"
export LLM_API_KEY="your-api-key"
export LLM_MODEL="gpt-3.5-turbo"

python scripts/translate.py "Hello world" -t "Spanish"

Core Workflows

1. Simple Text Translation

Translate a string or stdin content:

# Translate a string
python scripts/translate.py "This is a test" -t "French"

# Translate from stdin
echo "Hello" | python scripts/translate.py -t "German"

# Specify source language (optional)
python scripts/translate.py "你好" -s "Chinese" -t "English"

2. Single File Translation

Translate a file and save the output:

python scripts/translate.py -f input.txt -t "Japanese" -o output.txt --config config.json

With format preservation (for Markdown, HTML, etc.):

python scripts/translate.py -f document.md -t "Spanish" -o document_es.md --preserve-format --config config.json

3. Batch File Translation

Translate multiple files while preserving directory structure:

# Translate all files in a directory
python scripts/batch_translate.py ./docs ./docs_translated -t "Chinese" --config config.json

# Translate only specific file types
python scripts/batch_translate.py ./docs ./docs_zh -t "简体中文" -e .md .txt --config config.json

# Translate without preserving formatting
python scripts/batch_translate.py ./files ./files_en -t "English" --no-preserve-format --config config.json

When to Use Each Script

translate.py - Single Translation

Use for:

• Translating short text snippets
• Single file translation
• Testing API configuration
• Quick one-off translations

batch_translate.py - Batch Processing

Use for:

• Translating entire documentation folders
• Processing multiple subtitle files
• Migrating content to another language
• Bulk translation tasks

API Configuration

Supported Providers

This skill works with any OpenAI-compatible API. For specific provider configurations, see references/api_providers.md for examples including:

• OpenAI
• Azure OpenAI
• Anthropic Claude (via proxy)
• Chinese LLMs (DeepSeek, Zhipu, Moonshot, Qwen, Wenxin)
• Local models (Ollama, LM Studio, vLLM)

Configuration Priority

Settings are applied in this order (later overrides earlier):

1. Config file (--config)
2. Environment variables (LLM_API_BASE, LLM_API_KEY, LLM_MODEL)
3. Command-line arguments (--api-base, --api-key, --model)

Language Specification

You can specify languages naturally:

• Full name: "English", "Japanese", "Spanish"
• Native name: "日本語", "简体中文", "Français"
• Short form: "Chinese" (defaults to Simplified)

Use "auto" as source language for automatic detection (recommended).

For comprehensive language reference, see references/language_codes.md.

Format Preservation

Use --preserve-format flag to maintain formatting in:

• Markdown: Headings, lists, code blocks, links
• HTML: Tags, attributes, structure
• Code files: Comments, docstrings
• Subtitles: Timestamps, formatting codes

The LLM will translate only text content while keeping all markup intact.

Common Patterns

Pattern 1: Translate User-Provided Text

# User says: "Translate 'hello world' to Chinese"
python scripts/translate.py "hello world" -t "Chinese" --config config.json

Pattern 2: Translate File Preserving Format

# User says: "Translate this README.md to Spanish"
python scripts/translate.py -f README.md -t "Spanish" -o README_es.md --preserve-format --config config.json

Pattern 3: Batch Translate Documentation

# User says: "Translate all markdown files in ./docs to Japanese"
python scripts/batch_translate.py ./docs ./docs_ja -t "日本語" -e .md --config config.json

Pattern 4: Manual API Configuration

# User provides API credentials directly
python scripts/translate.py "test" -t "French" \
  --api-base "https://api.example.com/v1" \
  --api-key "sk-xxx" \
  --model "gpt-4"

Implementation Guidelines

When User Requests Translation

1. Determine translation type:

   • Short text → Use translate.py with direct text
   • Single file → Use translate.py with -f flag
   • Multiple files/folder → Use batch_translate.py

2. Check for API configuration:

   • Ask if they have a config file, OR
   • Check for environment variables, OR
   • Request API credentials (base URL, key, model)

3. Identify source and target languages:

   • Target language is usually explicit in request
   • Source language: use "auto" unless specified
   • Accept natural language specifications

4. Determine format preservation:

   • If file has markup (.md, .html, etc.) → Use --preserve-format
   • If plain text or user wants clean translation → Omit flag

5. Execute translation:

   • Run appropriate script with collected parameters
   • Show output or save to file as requested

Error Handling

Common issues and solutions:

• "API base URL and API key are required" → Need configuration
• Connection errors → Check API endpoint URL and network
• 401/403 errors → Invalid API key
• Rate limit errors → Slow down or use different model
• Encoding errors → Ensure files are UTF-8 encoded

Tips

• Model selection: Use faster/cheaper models (e.g., gpt-3.5-turbo) for bulk translations; use better models (e.g., gpt-4) for quality-critical content
• Cost management: Preview first file in batch to verify quality before processing all
• Source language: Unless you have specific reason, use "auto" for source language detection
• Large files: For very large files (>10K words), consider splitting into chunks