🌐 Caption.Ninja Translation Guide

Home Free Translation Premium Translation GitHub

Quick Start: Caption.Ninja translates captions in real-time using Mozilla Bergamot, an open-source translation engine that runs entirely in your browser. No API keys or external translation services are used.

Translation Methods Overview

Method	Languages	Cost	Quality	Setup Required	Best For
Local Translation (Mozilla Bergamot)	17 languages	Free	Good	None	Personal use, privacy-focused

Method 1: Direct Overlay Translation (Simplest)

Free Local Translation

Add translation directly to any overlay URL using Mozilla's Bergamot translation engine.

overlay.html?room=yourRoomID&translate=es

Supported Languages:

bg (Bulgarian), cs (Czech), nl (Dutch), en (English), et (Estonian), de (German), fr (French), is (Icelandic), it (Italian), nb (Norwegian Bokmål), nn (Norwegian Nynorsk), fa (Persian), pl (Polish), pt (Portuguese), ru (Russian), es (Spanish), uk (Ukrainian)

URL Parameters:

translate=XX - Target language code
lang=XX - Alternative parameter (same as translate)
ln=XX - Alternative parameter (same as translate)
fromlang=XX - Override source language (local Bergamot cannot auto-detect)
context=1 - Enable context-aware translation
contextsize=3 - Number of previous messages for context (default: 2)

Translation is local-only. Remote providers (Google Cloud Translation, OpenAI-compatible and Anthropic APIs) are not part of this fork; captions and models never leave your browser or the deployment host.

Method 2: Premium Translation Page

The premium translation page provides a full interface for speech recognition and translation.

Features:

Speech recognition with language selection
Real-time local translation (Mozilla Bergamot)
Context-aware translation option
Incremental updates for faster response
Generates overlay URL automatically

Workflow:

Open translate_premium.html
Select source and target languages
Enable microphone and start speaking
Use the generated overlay URL in OBS

Method 3: Free Translation Page

The free translation page uses local Mozilla Bergamot models.

Features:

No API key required
Privacy-focused (translation happens locally)
Limited to 17 languages
Works offline once models are loaded

Note: First-time use requires downloading translation models (~20MB per language pair).

Advanced Features

🌍 Multiple Language Overlays

Create separate overlay windows for different languages:

Window 1: overlay.html?room=abc&translate=es
Window 2: overlay.html?room=abc&translate=fr
Window 3: overlay.html?room=abc&translate=de

📝 Context-Aware Translation

Include previous messages for better translation accuracy:

&context=1&contextsize=5

Especially useful for conversations and technical content.

🔊 Text-to-Speech Integration

Add speech synthesis to translated captions:

&speech=1&voice=US English

Supports native browser TTS and optional TTS services, with no cloud dependency.

🎨 Styling Options

Customize overlay appearance:

&clear=1&showtime=3000&html=1

Control caption persistence and formatting.

Multi-Language Speakers

Handling Speakers Who Switch Between Languages

For events where speakers alternate between languages (e.g., French and English), Caption.Ninja offers two approaches:

Option 1: Manual Language Toggle (Free)

Add a quick-switch toggle to the capture page that lets a producer switch between languages on the fly:

index.html?room=yourRoom&lang=en-US&togglelang=en-US,fr-FR

togglelang=XX,YY - Comma-separated list of languages to cycle through
Click the toggle button or press Ctrl+L to switch languages
The overlay automatically adapts when the source language changes
Works with free local translation (Bergamot)

Workflow:

Open index.html?room=myroom&lang=en-US&togglelang=en-US,fr-FR
Open overlay.html?room=myroom&translate=en in OBS
When speaker switches to French, press Ctrl+L or click the toggle
French speech will be transcribed and translated to English

Option 2: Auto-Detect Language (Removed)

Automatic source language detection required a remote translation provider and is no longer available. This fork is local-only.

Local Bergamot translation requires the source language to be specified
Use Option 1 above to toggle languages manually when speakers switch

Language Codes Reference

Full Language Code List: View all supported language codes at:

ISO 639-1 Language Codes

Common Use Cases

Live Streaming with Multi-Language Support

Set up your main caption source (e.g., speechin.html)
Create multiple overlay URLs with different target languages
Add each overlay as a separate browser source in OBS
Position overlays for different regions or create scene variants

International Conferences

Use translate_premium.html for source language input
Enable context-aware translation for accuracy
Create overlay URLs for each target language
Provide separate streams or overlay options for attendees

Troubleshooting

Common Issues:

WASM Loading Error: Occurs when trying to load translation for same source/target language. Solution: Remove translation parameter or ensure source and target differ.
Model Installing Forever: The bundled Bergamot model download may be blocked. Check browser console and that /models is served by the host.
No Translation Happening: Check browser console for errors. Verify language codes are correct.
Auto-Detect Not Working: Local translation cannot auto-detect the source language; specify it with the manual language toggle.

Cost Considerations

Local Translation Pricing

Translation is free - it runs locally with bundled Mozilla Bergamot models
No API keys or usage quotas
No text leaves the browser or deployment host

Back to Home Report Issues Contribute