llm-translator

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).

SKILL.md

---
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:

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

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

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

3. Run translation:

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

### Option 2: Using Command-line Arguments

```bash
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

```bash
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:

```bash
# 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:

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

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

```bash
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:

```bash
# 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](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](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

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

### Pattern 2: Translate File Preserving Format

```python
# 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

```python
# 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

```python
# 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