Subtitle Translator

Translate SRT subtitle files using LLM APIs with OpenAI-compatible format. Supports both single-language and bilingual output. Use when you need to translate subtitle files (.srt) from one language to another while preserving timestamps. Processes in batches of 50 sentences with progress logging.

Overview

Translate SRT subtitle files using LLM APIs. Supports OpenAI-compatible API format with customizable URL, API key, and model selection. Outputs single-language or bilingual subtitles with original timestamps preserved.

Features

• Format Support: SRT subtitles
• API Compatibility: OpenAI-compatible endpoints
• Output Modes: Single-language or bilingual (translation above original)
• Batch Processing: 50 sentences per batch (configurable) with 1-second intervals
• Progress Tracking: Detailed logging of task progress and execution
• Validation: Ensures sentence count consistency and timestamp preservation

Quick Start

Basic Translation

python3 scripts/translate_srt.py \
  --input video.srt \
  --output video_zh.srt \
  --source-lang en \
  --target-lang zh \
  --api-url https://api.openai.com/v1 \
  --api-key sk-... \
  --model gpt-4

Bilingual Output

python3 scripts/translate_srt.py \
  --input video.srt \
  --output video_bilingual.srt \
  --source-lang en \
  --target-lang zh \
  --bilingual \
  --api-url https://api.openai.com/v1 \
  --api-key sk-...

Validate SRT File

python3 scripts/validate_srt.py input.srt

List Available Models

python3 scripts/list_models.py \
  --api-url https://api.openai.com/v1 \
  --api-key sk-...

Configuration

Option 1: Environment Variables (Recommended)

export SUBTITLE_API_URL="https://api.openai.com/v1"
export SUBTITLE_API_KEY="sk-your-api-key"
export SUBTITLE_MODEL="gpt-4"

python3 scripts/translate_srt.py -i input.srt -o output.srt

Option 2: Command Line Arguments

python3 scripts/translate_srt.py \
  -i input.srt \
  -o output.srt \
  -u https://api.openai.com/v1 \
  -k sk-your-api-key \
  -m gpt-4

Option 3: Config File (Less Secure)

Create ~/.openclaw/skills/subtitle-translator/config.json:

{
  "api_url": "https://api.openai.com/v1",
  "api_key": "sk-your-api-key",
  "model": "gpt-4",
  "batch_size": 50,
  "batch_interval_ms": 1000,
  "output_mode": "single",
  "log_level": "info"
}

⚠️ Security Warning: Storing API keys in plaintext config files increases risk. Prefer environment variables or command line arguments.

Security Considerations

1. API Key Storage: Use environment variables or secure secret managers instead of plaintext config files
2. API Endpoint: Ensure you trust the API URL you provide
3. Proxy Environment: The scripts honor http_proxy/https_proxy environment variables. If your environment uses untrusted proxies, API keys could be captured
4. Network Traffic: All subtitle content is sent to the API endpoint. Do not use with sensitive/confidential content unless you control the API

Workflow

1. Parse SRT: Extract index, timecodes, and text
2. Validate: Optional validation of input format
3. Batch Translation: Send 50 sentences per request (configurable)
4. Validate: Ensure output count matches input
5. Reconstruct: Combine original timecodes with translations
6. Output: Generate SRT file

Resources

scripts/

• translate_srt.py - Main translation script
• list_models.py - List available models from API
• validate_srt.py - Validate SRT file format

references/

• srt_format.md - SRT file format specification