🌐 Caption.Ninja Translation Guide

Home Free Translation Premium Translation GitHub

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 code
lang=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 key
context=1 - Enable context-aware translation
contextsize=3 - Number of previous messages for context (default: 2)
forcelocal=1 - Force local translation even with API key

Get Google API Key: Google Cloud Console

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.

Language Codes Reference

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

Google Cloud Translation Languages (100+ languages)
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.
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

Back to Home Report Issues Contribute