Subtitle Translator

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