🌐 Caption.Ninja Translation Guide
Quick Start: Caption.Ninja offers multiple ways to translate captions in real-time. Choose between free local translation (17 languages) or premium remote APIs (Google/OpenAI-compatible/Anthropic).
Translation Methods Overview
| Method |
Languages |
Cost |
Quality |
Setup Required |
Best For |
Local Translation
(Mozilla Bergamot) |
17 languages |
Free |
Good |
None |
Personal use, privacy-focused |
| Google Cloud Translation |
100+ languages |
Pay-per-use |
Excellent |
API Key required |
Professional, multi-language |
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 codelang=XX - Alternative parameter (same as translate)ln=XX - Alternative parameter (same as translate)fromlang=XX - Override source language detection (default: auto-detect)
Google Cloud Translation in Overlay
Use Google's premium translation API directly in the overlay for 100+ languages.
overlay.html?room=yourRoomID&translate=es&googlekey=YOUR_API_KEY
Additional Parameters:
googlekey=KEY or gkey=KEY - Your Google Cloud API keycontext=1 - Enable context-aware translationcontextsize=3 - Number of previous messages for context (default: 2)forcelocal=1 - Force local translation even with API key
OpenAI-Compatible / Anthropic Providers
You can also use OpenAI-compatible APIs (including Ollama-compatible endpoints) or Anthropic via URL parameters.
Example URLs:
overlay.html?room=yourRoomID&translate=es&tprovider=openai&tmodel=gpt-4o-mini&tkey=YOUR_KEY
overlay.html?room=yourRoomID&translate=es&tprovider=ollama&turl=http://127.0.0.1:11434/v1&tmodel=llama3.1
overlay.html?room=yourRoomID&translate=es&tprovider=anthropic&tmodel=claude-3-5-haiku-latest&tkey=YOUR_KEY
Additional Parameters:
tprovider=google|openai|anthropic|ollama|local - Select translation providerturl=URL - Custom API base URL (for proxy/self-hosted endpoints)tmodel=MODEL - Model id (for OpenAI-compatible/Anthropic providers)tkey=KEY or translatekey=KEY - API key for remote provider
UI Shortcut: On index.html, click Customize Overlay and use the Provider dropdown to build these URLs without manual query editing.
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 translation with provider selection (Google/OpenAI-compatible/Anthropic/Ollama)
- Context-aware translation option
- Incremental updates for faster response
- Generates overlay URL automatically
Workflow:
- Open
translate_premium.html
- Select your translation provider
- Enter API key (if required) and optional endpoint/model for advanced providers
- 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=Google US English
Supports native browser TTS and premium services.
🎨 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 (Premium)
With a remote translation provider, enable automatic source language detection:
overlay.html?room=yourRoom&translate=en&fromlang=auto&googlekey=YOUR_KEY
OpenAI-compatible example:
overlay.html?room=yourRoom&translate=en&fromlang=auto&tprovider=openai&turl=https://your-proxy.example/v1&tmodel=gpt-4o-mini&tkey=YOUR_KEY
Or use the dedicated parameter:
overlay.html?room=yourRoom&translate=en&autodetect&googlekey=YOUR_KEY
fromlang=auto or autodetect - Enable automatic language detection- Requires a configured remote provider (Google/OpenAI-compatible/Anthropic)
- The provider detects if the speaker is using French or English
- French → translated to English; English → passed through
Note: Auto-detect only works with remote providers. The free local translation (Bergamot) requires you to specify the source language manually using the toggle feature.
Language Codes Reference
Full Language Code List: View all supported language codes at:
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.
- API Key Invalid: Ensure your Google Cloud Translation API is enabled and key has proper permissions.
- No Translation Happening: Check browser console for errors. Verify language codes are correct.
- Rate Limiting: Google API has quotas. Consider caching or reducing update frequency.
Cost Considerations
Google Cloud Translation Pricing
- First 500,000 characters per month: Free
- Beyond 500,000 characters: ~$20 per million characters
- Prices vary by region and features used
Cost Optimization Tips:
- Enable caching in overlay (automatic)
- Avoid incremental updates for cost savings
- Use context wisely (increases character count)
- Consider local translation for supported languages