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