🌐 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 Google Cloud Translation (100+ languages).
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
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 Google Cloud API
- Context-aware translation option
- Incremental updates for faster response
- Generates overlay URL automatically
Workflow:
- Open
translate_premium.html
- Enter your Google API key
- 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 Google Cloud API key, enable automatic source language detection:
overlay.html?room=yourRoom&translate=en&fromlang=auto&googlekey=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 Google Cloud Translation API key
- Google automatically detects if the speaker is using French or English
- French → translated to English; English → passed through
Note: Auto-detect only works with Google Cloud Translation (premium). 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