Skip to content
julien-media-subtitle-translation logo

Subtitle Translation Skill

julien-media-subtitle-translation

Translates SRT subtitle files using LLM APIs (OpenRouter/Llama). Use when user wants to translate subtitles, SRT files, or needs batch subtitle translation for movies/series. Handles HTML tags, batch processing, retries, and cost estimation.

SKILL.md

Full skill instructions

Subtitle Translation Skill

Translate SRT subtitle files efficiently using LLM APIs with proper cost management.

When to Use

  • User wants to translate .srt subtitle files
  • Batch translation of multiple episodes/​movies
  • Translation between any language pair (default: EN→FR)

Step 0: Ask User for API Provider

Always ask the user which provider to use:

Which API provider do you want to use?

1. **OpenRouter** (Recommended) - Best price/​quality, many models
2. **OpenAI** - GPT-4o-mini, reliable but needs credit card
3. **Ollama Local** - Free, runs on your machine (needs GPU)
4. **Ollama Hostinger** - Free, runs on your VPS

For large batches (100+ episodes): OpenRouter or Ollama Hostinger
For small batches (<20 episodes): Any option works

Provider Configuration

ProviderAPI URLAuth
OpenRouterhttps://openrouter.ai/​api/​v1/​chat/​completionsBearer token
OpenAIhttps://api.openai.com/​v1/​chat/​completionsBearer token
Ollama Localhttp://localhost:11434/​api/​chatNone
Ollama Hostingerhttp://YOUR_VPS_IP:11434/​api/​chatNone

Step 1: Choose Model Based on Complexity

Ask user about subtitle complexity:

What type of content are you translating?

A) Simple dialogue (sitcoms, slice-of-life) → Fast/​cheap model
B) Standard content (action, drama) → Balanced model
C) Complex content (technical, poetry, wordplay) → Quality model

Model Recommendations (December 2024)

ComplexityOpenRouterOpenAIOllama
Simplemistral-7b-instruct ($0.03/​M)-mistral:7b
Standardllama-3.3-70b-instruct ($0.11/​M in, $0.34/​M out)gpt-4o-mini ($0.15/​M in, $0.60/​M out)llama3.1:70b
Complexclaude-3.5-sonnet ($3/​M in, $15/​M out)gpt-4o ($2.50/​M in, $10/​M out)llama3.1:70b

Low-Resource Servers (VPS < 16GB RAM)

For servers with limited RAM, use lightweight multilingual models:

ModelRAM RequiredQualitySpeedBest For
aya:8b~6GBGoodFastMultilingual - 100+ languages native
mistral:7b~5GBOKFastEuropean languages
gemma2:9b~7GBGoodMediumGeneral purpose

Aya 8B is recommended for subtitle translation on VPS because:

  • Trained specifically for multilingual tasks (100+ languages)
  • Low memory footprint (~6GB VRAM/​RAM)
  • Good quality for dialogue translation
  • Free with Ollama
# Install on VPS
ollama pull aya:8b

# Test
ollama run aya:8b "Translate to French: Hello, how are you?"

Live Model Search (OpenRouter)

def search_models(min_context=8000):
    """Search OpenRouter for available models with pricing"""
    r = requests.get("https://openrouter.ai/​api/​v1/​models")
    models = r.json().get("data", [])

    # Filter and sort by price
    suitable = []
    for m in models:
        ctx = m.get("context_length", 0)
        if ctx >= min_context:
            price_in = m.get("pricing", {}).get("prompt", 0)
            price_out = m.get("pricing", {}).get("completion", 0)
            suitable.append({
                "id": m["id"],
                "name": m.get("name", m["id"]),
                "context": ctx,
                "price_in": float(price_in) * 1_000_000,  # Per M tokens
                "price_out": float(price_out) * 1_000_000
            })

    return sorted(suitable, key=lambda x: x["price_in"])[:10]

Key Learnings (Production-Tested)

Cost Reality Check

Always multiply naive estimates by 1.5x due to:

  • System prompts repeated per batch
  • JSON formatting overhead
  • Instruction tokens
ModelInputOutputReal Cost/​Episode
Llama 3.3 70B$0.11/​M$0.34/​M~$0.007
GPT-4o-mini$0.15/​M$0.60/​M~$0.012

Optimal Configuration

BATCH_SIZE = 25          # Subtitles per API request (sweet spot)
DELAY_BETWEEN_REQUESTS = 0.5  # Avoid rate limits
MAX_RETRIES = 3          # Per batch
REQUEST_TIMEOUT = 90     # Seconds

Implementation Steps

1. Parse SRT Format

def parse_srt(content):
    """Parse SRT into list of (index, timing, text) tuples"""
    blocks = []
    current = []
    for line in content.strip().split('\n'):
        if line.strip() == '':
            if current:
                idx = current[0]
                timing = current[1]
                text = '\n'.join(current[2:])
                blocks.append((idx, timing, text))
                current = []
        else:
            current.append(line)
    if current:
        idx = current[0]
        timing = current[1]
        text = '\n'.join(current[2:])
        blocks.append((idx, timing, text))
    return blocks

2. HTML Tag Preservation (Critical)

Never send HTML tags to the LLM - they get corrupted. Strip before, reapply after.

import re

def extract_formatting(text):
    """Extract HTML tags with positions for later restoration"""
    tags = []
    for match in re.finditer(r'<[^>]+>', text):
        tags.append((match.start(), match.end(), match.group()))
    return tags

def strip_html_tags(text):
    """Remove HTML tags for clean translation"""
    return re.sub(r'<[^>]+>', '', text)

def apply_formatting(translated, original_tags):
    """Reapply original HTML structure to translation"""
    if not original_tags:
        return translated
    # Preserve italic tags at start/​end
    result = translated
    for start, end, tag in original_tags:
        if tag == '<i>' and not result.startswith('<i>'):
            result = '<i>' + result
        elif tag == '</​i>' and not result.endswith('</​i>'):
            result = result + '</​i>'
    return result

3. Batch Translation with Retry Queue

def translate_batch(texts, source='English', target='French'):
    """Translate batch of texts, return list or None on failure"""
    prompt = f"""Translate these {source} subtitles to {target}.
Return ONLY a JSON array of translated strings, same order.
Keep it natural and conversational.

{json.dumps(texts, ensure_ascii=False)}"""

    # API call with retries
    for attempt in range(MAX_RETRIES):
        try:
            response = call_api(prompt)
            return json.loads(response)
        except:
            time.sleep(2 ** attempt)  # Exponential backoff
    return None

4. Failed Batch Queue

Store failed batches for later retry:

def add_failed_batch(file_path, batch_index, blocks_data):
    """Queue failed batch for retry"""
    failed_data = load_failed_batches()
    failed_data["batches"].append({
        "fr_srt": str(file_path),
        "batch_index": batch_index,
        "blocks": blocks_data,
        "retry_count": 0,
        "timestamp": datetime.now().isoformat()
    })
    save_failed_batches(failed_data)

5. Resilient Execution

Always wrap main() in auto-restart:

def run_resilient():
    """Auto-restart on errors (up to 50 times)"""
    max_restarts = 50
    restart_count = 0

    while restart_count < max_restarts:
        try:
            main()
            break
        except KeyboardInterrupt:
            log("Manual stop (Ctrl+C)")
            break
        except Exception as e:
            restart_count += 1
            log(f"ERROR: {e}")
            log(f"Auto-restart {restart_count}/​{max_restarts} in 30s...")
            time.sleep(30)

6. Progress Tracking

PROGRESS_FILE = "translation_progress.json"

def load_progress():
    try:
        with open(PROGRESS_FILE) as f:
            return json.load(f)
    except:
        return {"completed": [], "failed": [], "total_cost": 0.0}

def save_progress(state):
    state["last_update"] = datetime.now().isoformat()
    with open(PROGRESS_FILE, 'w') as f:
        json.dump(state, f, indent=2)

API Configuration

OpenRouter (Recommended)

OPENROUTER_API_KEY = "sk-or-v1-..."
MODEL = "meta-llama/​llama-3.3-70b-instruct"
API_URL = "https://openrouter.ai/​api/​v1/​chat/​completions"

headers = {
    "Authorization": f"Bearer {OPENROUTER_API_KEY}",
    "Content-Type": "application/​json"
}

Check Credits

def get_credits():
    r = requests.get("https://openrouter.ai/​api/​v1/​credits",
                     headers={"Authorization": f"Bearer {API_KEY}"})
    data = r.json().get("data", {})
    return data.get("total_credits", 0) - data.get("total_usage", 0)

File Naming Convention

InputOutput
movie.eng.srtmovie.fr.srt
episode.en.srtepisode.fr.srt

Cost Estimation Formula

episodes × 250 subtitles × 50 tokens × 2 (in+out) × price/​token × 1.5 (overhead)

Example: 600 episodes EN→FR with Llama 3.3 70B:

  • Naive: 600 × 250 × 50 × 2 × $0.20/​M = $3.00
  • Real: $3.00 × 1.5 = ~$4.50

Common Issues & Solutions

IssueSolution
HTML tags corruptedStrip before translation, reapply after
Rate limit errorsAdd 0.5s delay between requests
Parsing failuresRetry with exponential backoff
Script stops randomlyUse run_resilient() wrapper
Cost higher than expectedMultiply estimates by 1.5x

Skill Chaining

Skills Required Before

  • None (can work standalone)

Input Expected

  • Directory path containing .srt files
  • Source/​target languages (default: EN→FR)
  • API provider choice (OpenRouter/​OpenAI/​Ollama)
  • API key (if not Ollama)

Output Produced

  • Translated .srt files with language suffix
  • translation_progress.json - tracks completed files
  • failed_batches.json - retry queue
  • translation.log - detailed logs

Compatible Skills After

  • video-transcoding: Burn subtitles into video
  • media-organization: Organize translated files

Tools Used

  • Write (create translation script)
  • Bash (run translation)
  • Read (check progress/​logs)
  • AskUserQuestion (provider/​model selection)
  • WebFetch (live model pricing)

Visual Workflow

User: "Translate my subtitles to French"
    ↓
[Ask] Which API provider?
    ├─► OpenRouter (recommended)
    ├─► OpenAI
    ├─► Ollama Local
    └─► Ollama Hostinger
    ↓
[Ask] Content complexity?
    ├─► Simple → mistral-7b ($0.03/​M)
    ├─► Standard → llama-3.3-70b ($0.20/​M)
    └─► Complex → claude-3.5-sonnet ($9/​M)
    ↓
[Calculate] Cost estimate × 1.5
    ↓
[Confirm] "~$X for Y episodes. Proceed?"
    ↓
[Execute] translate_srt.py
    ├─► Parse SRT → Strip HTML → Batch (25/​req)
    ├─► Translate → Reapply formatting
    └─► Track progress → Queue failures
    ↓
[Done] X.fr.srt files created

Usage Example

Scenario: Translate 600 One Piece episodes EN→FR

Interaction:

  1. Claude asks provider → User: "OpenRouter"
  2. Claude asks complexity → User: "Standard (anime)"
  3. Claude calculates: 600 × $0.007 × 1.5 = ~$6.30
  4. User confirms → Script runs
  5. Result: 600 .fr.srt files, actual cost ~$4-7

Output structure:

/​anime/​onepiece/
├── Episode.001.eng.srt  (original)
├── Episode.001.fr.srt   (NEW)
├── translation_progress.json
├── failed_batches.json
└── translation.log

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View