tools-only Supervertaler - Frequently Asked Questions
Current Version: v1.9.74 (December 31, 2025) Framework: PyQt6 Last Updated: January 1, 2026
Welcome to the Supervertaler FAQ! Find answers to common questions about installation, features, workflow, and troubleshooting.
📑 Table of Contents
About Supervertaler
What is Supervertaler?
Supervertaler is The Ultimate Translation Workbench. It works alongside your CAT tool (memoQ, Trados, CafeTran) to provide:
- AI-enhanced translation with GPT-4, Claude, and Gemini
- Project termbases with automatic term extraction
- Translation memory with fuzzy matching
- AI Assistant for conversational prompt generation
- Voice dictation (100+ languages via Whisper)
- Unified prompt library with 38+ built-in prompts
- CAT tool integration (memoQ, Trados, CafeTran)
Think of it as a professional CAT tool that specializes in AI integration and prompt management, designed to complement (not replace) your existing workflow.
Who created Supervertaler?
Michael Beijer - Professional translator and language technology enthusiast
Website: michaelbeijer.co.uk
GitHub: github.com/michaelbeijer/Supervertaler
Developed with assistance from Claude AI (Anthropic) using collaborative human-AI coding:
- Michael: Translation expertise, workflow design, feature requirements
- Claude: Implementation, architecture, debugging, optimization
- Framework: PyQt6 (modern Python GUI)
- Language: Python 3.10+
Who is Supervertaler for?
Primary Users:
- Professional translators seeking AI-enhanced workflows
- CAT tool users wanting better AI integration
- Freelance translators managing multiple language pairs
- Translation agencies handling diverse projects
- Anyone needing advanced prompt management for translation
Not For:
- Casual users needing quick Google Translate-style translation
- Users unwilling to manage Python/command-line tools
- Those seeking fully automated, zero-configuration translation
How does Supervertaler compare to other translation tools?
vs. DeepL/Google Translate:
- ✅ Multi-provider AI (Claude, GPT-4, Gemini) vs single engine
- ✅ Custom prompts and instructions vs generic translation
- ✅ Translation memory and termbase integration
- ✅ Project-based workflow with status tracking
- ⚠️ Requires API keys (paid) vs free web interface
vs. CAT Tools (memoQ, Trados):
- ✅ Works alongside CAT tools as companion
- ✅ Better AI integration with prompt management
- ✅ Conversational AI Assistant for prompt generation
- ✅ Voice dictation built-in (100+ languages)
- ⚠️ Not a full CAT tool replacement (no alignment, LiveDocs, etc.)
vs. AI Translation Plugins:
- ✅ Provider-agnostic (switch between OpenAI, Claude, Gemini)
- ✅ Open source - audit and customize the code
- ✅ Advanced features: Superbench, AI Assistant, project termbases
- ✅ No vendor lock-in or monthly subscriptions
Unique Selling Points:
- 2-Layer Prompt Architecture with AI-generated custom prompts
- Project Termbases with automatic term extraction
- Supervoice - F9 voice dictation in 100+ languages
- Superbench - Benchmark AI models on YOUR projects
- Universal Lookup - Ctrl+Alt+L system-wide TM search
Getting Started
What do I need to run Supervertaler?
System Requirements:
- OS: Windows 10/11, macOS 10.13+, or Linux
- Python: 3.10+
- RAM: 4GB minimum, 8GB recommended
- Disk: ~500 MB
- Internet: Required for AI API calls
Required API Key (at least one):
- Anthropic Claude (recommended): https://console.anthropic.com/
- OpenAI GPT: https://platform.openai.com/
- Google Gemini: https://aistudio.google.com/
Installation:
# Clone or download from GitHub
git clone https://github.com/michaelbeijer/Supervertaler.git
cd Supervertaler
# Install dependencies
pip install -r requirements.txt
# Setup API keys
cp api_keys.example.txt api_keys.txt
# Edit api_keys.txt with your keys
# Launch
python Supervertaler.py
See Installation for detailed instructions.
How much does it cost?
Supervertaler Itself:
- ✅ 100% Free - MIT License, open source
- ✅ No subscriptions, no hidden fees
- ✅ Commercial use allowed
AI API Costs (Pay-as-you-go):
- Claude 3.5 Sonnet: ~$3 per million input tokens, $15 per million output tokens
- GPT-4o: ~$2.50 per million input tokens, $10 per million output tokens
- Gemini 2.0 Flash: Generous free tier, then ~$0.075/$0.30 per million tokens
Typical Costs:
- Average project (10,000 words): $0.50 - $2.00
- Heavy user (100,000 words/month): $5 - $20/month
- Much cheaper than DeepL Pro ($9.49/month) or CAT tool subscriptions
How do I install Supervertaler?
# 1. Install Python 3.10+ from python.org
# 2. Download Supervertaler
git clone https://github.com/michaelbeijer/Supervertaler.git
cd Supervertaler
# 3. Install dependencies
pip install -r requirements.txt
# 4. Setup API keys
cp api_keys.example.txt api_keys.txt
# Edit api_keys.txt with your keys
# 5. Launch
python Supervertaler.py
Full guide: Installation
How do I get API keys?
Anthropic Claude (Recommended):
- Visit: https://console.anthropic.com/
- Sign up or log in
- Settings → API Keys → "Create Key"
- Copy key (starts with
sk-ant-api03-...) - Add to
api_keys.txt:ANTHROPIC_API_KEY=sk-ant-api03-...
OpenAI GPT:
- Visit: https://platform.openai.com/
- Sign up or log in
- API Keys section → "Create new secret key"
- Copy key (starts with
sk-proj-...orsk-...) - Add to
api_keys.txt:OPENAI_API_KEY=sk-proj-...
Google Gemini:
- Visit: https://aistudio.google.com/
- Sign up or log in
- Click "Get API Key"
- Copy key (starts with
AIza...) - Add to
api_keys.txt:GOOGLE_API_KEY=AIza...
Security Tip: Never commit api_keys.txt to version control!
Features & Capabilities
What are the key features of v1.9.27?
📄 Simple Text File Import/Export (NEW in v1.9.27)
- Import plain text files where each line becomes a source segment
- Export translations as matching text file with target text
- UTF-8, Latin-1, Windows-1252 encoding support with auto-detection
- Perfect for translating simple line-by-line text content
- File → Import → Simple Text File (TXT) / File → Export → Simple Text File - Translated (TXT)
🔄 Automatic Model Version Checker (v1.9.26)
- Auto-detects new LLM models from OpenAI, Anthropic, and Google
- Checks once per 24 hours on startup (configurable)
- Popup dialog with easy model selection when new models detected
- Settings → AI Settings → Model Version Checker
- Manual "Check for New Models Now" button
🎨 UI Standardization (NEW in v1.9.26)
- All checkboxes standardized to green with white checkmark design
- Refined 16x16px size for cleaner, modern appearance
- Consistent visual language throughout entire application
📁 Custom File Extensions (v1.9.6)
- Branded file extensions:
.svproj(projects),.svprompt(prompts),.svntl(non-translatables) - Full backward compatibility - opens legacy
.json,.md,.ntlfiles - Industry standards retained:
.tmxfor TM exports
🌐 Monolingual DOCX Import (v1.9.6)
- Language pair selection dialog when importing monolingual DOCX files
- Explicitly set source and target languages (12 languages supported)
- No more unreliable auto-detection
📤 Target-Only DOCX Export (v1.9.6)
- Export > Target Only (DOCX)... preserves original document structure
- Tables, formatting, styles, headers/footers all preserved
- Original DOCX path saved in project for reliable exports
📤 Send Segments to TM (v1.9.5)
- Bulk send translated segments to Translation Memories
- Access via Edit > Bulk Operations > Send Segments to TM
- Filter by scope: All segments, Current selection, or row range
- Filter by status: Translated, Reviewed, Approved, Needs Review, Final
- Select multiple TMs to write to simultaneously
🏷️ memoQ Tag Shortcuts (v1.9.5)
- Ctrl+, - Insert next memoQ tag pair or wrap selection with tags
- Smart detection of memoQ tags from source:
[1},{1],[3], etc. - With selection: Wraps text with next unused tag pair
- Without selection: Inserts tag pair at cursor position
🏷️ Tag-Based Formatting System (v1.9.4)
- Import memoQ bilingual DOCX preserves bold/italic/underline as
<b>,<i>,<u>tags - Toggle between WYSIWYG and Tag view with Ctrl+Alt+T
- Ctrl+B/I/U shortcuts to apply formatting tags to selected text
- AI translation preserves and repositions tags intelligently
- Export converts tags back to Word formatting
🔍 Filter Highlighting (v1.7.8)
- Type search term in "Filter Source" or "Filter Target" box
- Matching segments highlighted in yellow
- Case-insensitive, supports multiple matches per cell
- Press Enter to apply filter
🎯 Termbase Display Customization (v1.7.7)
- Sort termbase matches: order of appearance, alphabetical, or by length
- Hide shorter matches contained within longer terms
- Settings → General → TM/Termbase Options
📚 Project Termbases (v1.7.0)
- One dedicated termbase per project
- Automatic term extraction from source segments
- Pink highlighting for project terms vs blue for background termbases
- Extract Terms button in Termbases tab
💾 Auto-Backup System (v1.7.6)
- Configurable intervals (1-60 minutes, default 5 min)
- Automatic project.json and TMX backups
- Never lose your work during translation
🤖 AI Assistant
- Conversational interface in Prompt Manager tab
- Analyze documents and generate custom prompts
- Attach files (PDF, DOCX, TXT, MD) for context
- Ask questions about segments and terminology
🎤 Supervoice Voice Dictation
- F9 global hotkey (press-to-start/stop)
- 100+ language support via OpenAI Whisper
- 5 model sizes (tiny to large)
- Dictate directly into target cells
📊 Superbench (LLM Benchmarking)
- Test GPT-4o, Claude, Gemini on YOUR projects
- chrF++ scoring with adaptive segment sampling
- Excel export with side-by-side comparison
- Find best model for your language pair/domain
💾 Translation Memory
- SQLite-based TM with FTS5 full-text search
- Fuzzy matching with visual diff
- TMX import/export
- Auto-propagation of exact matches
🔍 Universal Lookup
- Ctrl+Alt+L system-wide hotkey
- Search TM from ANY application
- Instant terminology lookup
- Works in Word, browser, email, etc.
📝 TMX Editor
- Database-backed professional TMX editor
- Handle massive 1GB+ TMX files
- Filter, search, bulk edit entries
What are the three view modes?
Supervertaler previously offered three editing views. Current versions focus on a single primary editing workflow: the Grid View.
1. Grid View (Default)
- Spreadsheet-like segment editor
- Columns: #, Source, Target, Status
- Inline editing, multi-selection
- Best for: segment-by-segment translation
Note: Document/List views were removed during cleanup because the grid workflow is the core production workflow.
What is the Unified Prompt Library?
2-Layer Prompt Architecture:
Layer 1: System Prompts
- Core translation infrastructure
- CAT tag handling, formatting rules
- Settings → System Prompts
Layer 2: Custom Prompts
- 38+ built-in prompts in organized folders
- Domain expertise (Legal, Medical, Financial, Technical)
- Project-specific instructions
- Style guides
Key Features:
- Multi-attach: Combine multiple prompts
- Favorites: Star frequently-used prompts
- AI-generated: Ask AI Assistant to create prompts
- Unlimited folders: Organize your way
Usage:
- Prompt Manager tab → Browse folders
- Right-click prompt → "Set as Primary" or "Attach"
- Translate normally - prompts automatically applied
See: Prompt Library
What is figure/image context support?
Load images to provide visual context for AI translation - essential for technical documents.
How it works:
- Prepare folder with images:
Figure 1.png,Figure 2A.jpg, etc. - Resources → 🖼️ Load Figure Context → Select folder
- When AI detects "Figure 1" in text, it includes the image automatically
- AI can "see" diagrams, understand part numbers, spatial relationships
Example:
- Text: "As shown in Figure 1A, the motor (12) connects to shaft (14)..."
- AI receives: Text + Image of Figure 1A
- Result: Accurate translation of technical details with visual understanding
Supported formats: PNG, JPG, JPEG, WEBP, GIF, BMP, TIFF
How does the translation memory work?
SQLite-based TM:
- Full-text search with FTS5
- Fuzzy matching algorithm
- Stores source + target + metadata
Features:
- Auto-save: Confirmed segments saved to active TMs
- Fuzzy matching: 70-99% matches with visual diff
- Multiple TMs: Activate/deactivate per project
- TMX import/export: Standard format compatibility
Match display:
- 100% match: Green
- 95-99% match: Light green with diff highlighting
- 70-94% match: Yellow with diff highlighting
- Match shortcuts: Ctrl+1-9 to insert
Settings:
- Settings → TM/Termbase Options
- Enable/disable matching
- Configure auto-propagation
How do keyboard shortcuts work?
Main Translation:
- F5: Translate selected segments (or active segment if none selected)
- F9: Start/stop voice dictation (global hotkey - works in any app)
- Ctrl+Alt+L: Universal Lookup (system-wide TM search)
- Ctrl+P: Open Unified Prompt Library
Navigation:
- Ctrl+1/2/3: Switch between Grid/Document/List views
- Arrow keys: Navigate between segments in Grid view
- Page Up/Down: Scroll through segments
Editing:
- Double-click cell: Edit segment in-place (Grid view)
- Ctrl+C/V: Copy/paste segments
- Ctrl+F: Find & Replace dialog
- Ctrl+Z: Undo (where supported)
TM Shortcuts:
- Ctrl+1-9: Insert TM match (1=best match, 2=second best, etc.)
- Ctrl+M: Show TM matches for active segment
Formatting (v1.9.4+):
- Ctrl+B: Apply/toggle bold tags
<b>...</b> - Ctrl+I: Apply/toggle italic tags
<i>...</i> - Ctrl+U: Apply/toggle underline tags
<u>...</u> - Ctrl+Alt+T: Toggle Tag view (show/hide formatting tags)
- Ctrl+,: Insert memoQ tag pair or wrap selection with tags
Project:
- Ctrl+S: Save project
- Ctrl+O: Open project
- Ctrl+N: New project
See: Full keyboard shortcut list in Keyboard Shortcuts
What is CAT tag handling?
What are CAT tags?
- Formatting markers from CAT tools:
<b>text</b>,{1},[tag] - Represent bold, variables, placeholders, etc.
- Must be preserved exactly in translation
How Supervertaler handles them:
- Detection: System prompts identify common CAT tag patterns
- Instruction: AI told to preserve ALL tags unchanged
- Validation: Tags verified after translation (future feature)
- Recovery: If AI modifies tags, manual correction needed
Supported tag formats:
- XML-style:
<tag>content</tag> - Curly braces:
{1},{placeholder} - Square brackets:
[tag],[0] - memoQ:
{0>text<0},{1/} - Trados:
<cf>,<c0>content</c0>
Best practice:
- Use specialized system prompts (memoQ, Trados, etc.)
- Review tag preservation after AI translation
- Lock segments with complex tags after confirming correctness
Technical Questions
What AI models are supported?
OpenAI:
- GPT-4o (recommended - best balance of speed/quality)
- GPT-4 Turbo
- GPT-4
- GPT-3.5 Turbo (economical option)
Anthropic Claude:
- Claude 3.5 Sonnet (excellent for translation)
- Claude 3.5 Haiku (fast and economical)
- Claude 3 Opus (highest capability, slower)
- Claude 3 Sonnet
- Claude 3 Haiku
Google Gemini:
- Gemini 1.5 Pro (2M token context window)
- Gemini 1.5 Flash (cost-effective)
- Gemini 2.0 Flash Exp (experimental)
Recommendations:
- Best Quality: Claude 3.5 Sonnet, GPT-4o
- Best Value: Gemini 1.5 Flash, Claude 3.5 Haiku
- Best Context: Gemini 1.5 Pro (2M tokens)
- General Use: GPT-4o or Claude 3.5 Sonnet
Test models with Superbench to find best for your language pair/domain!
How does AI translation work in Supervertaler?
Context Provision: Supervertaler provides AI with multiple layers of context:
- Document context: Surrounding segments for coherence
- Translation Memory: Fuzzy matches from active TMs
- Termbase matches: Relevant terminology highlighted
- System prompt: CAT tag handling instructions
- Custom prompts: Domain expertise, style guides
- Figure context: Images referenced in technical documents
Translation Process:
- You select segments and press F5 (or Translate button)
- Supervertaler assembles context: TM matches, termbase, prompts, figures
- Sends source + context to AI API
- AI generates translation following all instructions
- Translation inserted into target cell
- Confirmed segments auto-saved to active TMs
Why this approach is powerful:
- AI understands document flow and terminology
- Maintains consistency with your TM and termbases
- Adapts to domain-specific requirements
- Preserves CAT tags and formatting
- Cost-effective: only translates what you need
What file formats are supported?
Import Formats:
- DOCX: Microsoft Word documents (segment by paragraph)
- TXT: Plain text files (segment by line or paragraph)
- TMX: Translation Memory eXchange format
- XLIFF: XML Localization Interchange File Format
- JSON: Project files (.json)
- Images: PNG/JPG/JPEG/WEBP/GIF/BMP/TIFF (figure context)
Export Formats:
- DOCX: Microsoft Word with translations
- TMX: Translation memory export
- XLIFF: XML format for CAT tools
- TXT: Plain text export
- Excel (XLSX): Spreadsheet with source/target columns
CAT Tool Integration:
- CafeTran bilingual DOCX (import/export)
- memoQ bilingual DOCX (import/export)
- Universal TMX (all CAT tools)
- XLIFF (most CAT tools)
What programming language is it built with?
Primary: Python 3.8+
Key Libraries:
- PyQt6: Modern GUI framework
- SQLite3: Translation memory database
- python-docx: DOCX file handling
- lxml: XLIFF and XML processing
- openai: OpenAI API client
- anthropic: Claude API client
- google-generativeai: Gemini API client
- openai-whisper (optional): Offline/local voice dictation (very large dependency; installs PyTorch). The default/recommended path uses the OpenAI Whisper API via
openai. - Pillow (PIL): Image processing for figure context
Architecture:
- Modular design: 50+ modules in
modules/folder - Main file:
Supervertaler.py(21,600+ lines) - Database-backed TM with FTS5 full-text search
- Event-driven UI with PyQt6 signals/slots
Why Python?
- Rapid development
- Excellent AI/ML library ecosystem
- Cross-platform (Windows/Mac/Linux)
- Easy to read and contribute to
Can I use Supervertaler offline?
Partially:
Online Features (require internet):
- AI translation via OpenAI/Claude/Gemini APIs
- Superbench model testing
- AI Assistant (document analysis, prompt generation)
Offline Features:
- Edit existing translations in Grid/Document/List views
- Search TM and termbases (if already loaded)
- Export to DOCX/TMX/XLIFF
- TMX Editor (work with TM files)
- Project management
- All UI features except AI translation
Voice Dictation (Supervoice):
- Fully offline if using "tiny" or "base" Whisper models
- Downloads once, runs locally on your machine
- No internet required after initial model download
Local LLM (Ollama):
- Fully offline AI translation on your own computer
- No API keys or internet required
- Complete privacy - your text never leaves your machine
- See "How do I set up Local LLM?" below
How do I set up Local LLM (Ollama)?
Local LLM allows you to run AI translation entirely on your computer - no API costs, complete privacy, works offline.
Step 1: Install Ollama
- Download Ollama from https://ollama.com
- Run the installer (Windows/Mac/Linux supported)
- Ollama starts automatically in the background
Step 2: Download a Model Open a terminal/command prompt and run:
# Recommended for most users (8GB+ RAM):
ollama pull qwen2.5:7b
# For 16GB+ RAM (better quality):
ollama pull qwen2.5:14b
# For 4GB RAM (lighter, faster):
ollama pull qwen2.5:3b
Step 3: Configure Supervertaler
- Go to Settings → LLM Settings
- Select "🖥️ Local LLM (Ollama)" as your provider
- Choose your downloaded model from the dropdown
- Click Save LLM Settings
Model Recommendations by RAM:
| RAM | Recommended Model | Quality |
|---|---|---|
| 4 GB | qwen2.5:3b | ★★★☆☆ |
| 8 GB | qwen2.5:7b | ★★★★☆ |
| 10 GB | gemma2:9b | ★★★★★ |
| 16 GB+ | qwen2.5:14b | ★★★★★ |
Tips:
- First translation may take 30-60 seconds (model loading)
- Subsequent translations are much faster
- Use the Setup... button in Settings for guided installation
- GPU acceleration is automatic if you have NVIDIA/AMD GPU
What are the system requirements?
Minimum:
- OS: Windows 10/11, macOS 10.15+, or Linux
- Python: 3.8 or higher
- RAM: 4 GB (8 GB recommended for large projects)
- Disk: 500 MB for application + space for TM/projects
- Internet: Required for AI translation
Recommended:
- RAM: 8 GB or more
- CPU: Multi-core processor for faster processing
- Disk: SSD for faster TM searches
- Display: 1920x1080 or higher resolution
For Voice Dictation (Supervoice):
- RAM: 8 GB minimum (16 GB for "large" model)
- Disk: 1-3 GB for Whisper models (varies by size)
- Microphone: Any USB or built-in microphone
For Local LLM (Ollama):
- RAM: 4 GB minimum (8 GB+ recommended)
- Disk: 2-10 GB per model (varies by size)
- GPU: Optional but recommended (NVIDIA/AMD for faster inference)
- Internet: Only needed for initial model download
For Superbench:
- Multiple API keys (GPT-4o, Claude, Gemini)
- Sufficient API credits for testing runs
Why is my antivirus flagging Supervertaler as malware?
This is a known false positive that affects applications built with PyInstaller (the tool used to create the Windows EXE).
Why it happens:
- PyInstaller bundles Python + all libraries into a single package
- This binary pattern triggers heuristic detection in some AV software (especially Norton 360)
- Generic detections like "Win64:Malware-gen" are pattern matches, not actual malware signatures
- The executable is not code-signed (certificates cost ~$300/year)
Solutions:
Use pip install (Recommended)
- Install:
pip install supervertaler - Run:
supervertaler - No AV warnings because it runs from Python source
- Install:
Whitelist the application
- Add an exception in your antivirus settings
- The application is safe - you can verify by checking the source code on GitHub
Report as false positive
- Norton: https://submit.norton.com/
- Windows Defender: Click "More info" → "Run anyway"
- Other AV: Check vendor's false positive submission page
This is common for PyInstaller apps - it affects tools like Calibre, many game mods, and scientific software. See the PyInstaller FAQ for more details.
Workflow & Integration
How do I integrate Supervertaler with my CAT tool?
Method 1: TMX Exchange (Most Compatible)
- In CAT tool: Export source segments as TMX
- In Supervertaler: Import TMX → Translate → Export TMX
- In CAT tool: Import translated TMX
- Result: Target segments populated in your CAT project
Method 2: XLIFF (Standard)
- In CAT tool: Export XLIFF file
- In Supervertaler: Import XLIFF → Translate → Export XLIFF
- In CAT tool: Import translated XLIFF
- Result: Translations with segment metadata preserved
Method 3: Copy-Paste (Quick)
- In CAT tool: Copy source segments
- In Supervertaler: Paste as TXT → Import → Translate → Copy targets
- In CAT tool: Paste translations
- Result: Fast but manual, no metadata
Method 4: CAT Tool-Specific
- CafeTran: Bilingual DOCX import/export
- memoQ: Bilingual DOCX import/export
- Check documentation for CAT tool-specific formats
What's the typical translation workflow?
Quick Translation (Simple Document):
- Launch Supervertaler
- File → Import → Select DOCX or TXT
- Select segments (or Ctrl+A for all)
- Press F5 to translate
- Review and edit translations
- File → Export → DOCX
Professional Project Workflow:
Setup:
- Create new project (Ctrl+N)
- Import document (DOCX/XLIFF/TMX)
- Activate relevant TMs (TM tab)
- Activate termbases (Termbases tab)
- Select prompts (Prompt Manager tab)
Translate:
- Select segments to translate
- Press F5
- AI translates with TM/termbase/prompt context
- Segments auto-saved to active TMs
Review & Edit:
- Switch to Document View for readability check
- Use Grid View for detailed editing
- Check termbase matches (blue/pink highlighting)
- Insert TM matches manually if preferred (Ctrl+1-9)
Quality Assurance:
- Search for specific terms (Ctrl+F)
- Check consistency of key terminology
- Review AI Assistant suggestions
Export & Deliver:
- Export to DOCX/TMX/XLIFF
- Save project (Ctrl+S) for future reference
- Deliver to client or reimport to CAT tool
Voice Dictation Workflow:
- Press F9 to start dictating (works system-wide)
- Speak your translation
- Press F9 to stop and insert text
- Edit as needed in Grid View
How do I handle large documents?
Strategy 1: Segment-by-Segment
- Grid View with 50 segments per page
- Translate one page at a time
- Full control over progress
- Best for: Documents requiring careful review
Strategy 2: Batch Translation
- Select all segments (Ctrl+A)
- Press F5 to translate all at once
- AI processes in batches automatically
- Best for: Clean source documents with good TM coverage
Strategy 3: Selective Translation
- Use Filter Source/Target to find untranslated segments
- Select filtered results
- Translate only what's needed
- Best for: Partially translated documents
Performance Tips:
- Auto-backup saves progress every 5 minutes (default)
- TM matching is fast (SQLite FTS5 full-text search)
- Large projects (10,000+ segments) still load quickly
- Export to TMX regularly as backup
Cost Management:
- Use Superbench to test which model gives best value for your content
- Consider using Gemini Flash (economical) for first draft
- Then use Claude 3.5 Sonnet or GPT-4o for final polish
- Check TM matches before translating (100% matches = free)
Can I customize the AI prompts?
Yes! The Unified Prompt Library provides complete control:
Built-in Prompts (38+):
- Organized in folders: Legal, Medical, Financial, Technical, Creative, etc.
- Domain-specific expertise pre-configured
- Style guides for common requirements
- CAT tag handling templates
Custom Prompts:
- Prompt Manager tab → Right-click folder → New Prompt
- Write your instructions in plain language
- Save to appropriate folder
- Right-click prompt → "Set as Primary" or "Attach"
AI-Generated Prompts:
- AI Assistant tab → Attach document (PDF/DOCX)
- Ask: "Analyze this style guide and create a prompt"
- AI generates custom prompt based on document
- Save and use for your projects
Multi-Attach:
- Attach multiple prompts simultaneously
- Example: Legal domain + Client style guide + Formality preference
- All prompts combined and sent to AI
System Prompts:
- Core CAT tag handling instructions
- Manages formatting preservation
- Edit in Settings → System Prompts
Variables:
{source_lang}- Automatically filled with source language{target_lang}- Automatically filled with target language{client_name}- Custom variable (if supported)
See: Prompt Library for full details
How do I use Universal Lookup?
System-Wide TM Search:
- Activate Universal Lookup: Settings → General → Enable Universal Lookup
- Press Ctrl+Alt+L from ANY application (Word, browser, email, etc.)
- Select text you want to look up
- Press Ctrl+Alt+L
- Supervertaler searches active TMs and shows matches in popup
Use Cases:
- Check terminology while writing emails
- Look up translations in Word documents
- Verify terms while browsing source documents
- Quick TM search without opening Supervertaler
Requirements:
- Supervertaler running in background
- At least one TM activated in TM tab
- Text selected before pressing hotkey
Troubleshooting
Why is translation slow?
Common Causes:
- Model choice: Claude 3 Opus, GPT-4 are slower than Flash/Haiku variants
- Large context: Many TM matches, large document, figure images
- Internet speed: Slow connection increases API response time
- Provider rate limits: Some API plans throttle requests
- Many segments: Translating 1000+ segments takes time
Solutions:
- Try faster models: Gemini 1.5 Flash, Claude 3.5 Haiku, GPT-3.5 Turbo
- Reduce context: Deactivate unused TMs, remove unnecessary termbases
- Translate in batches: Select 50-100 segments at a time instead of all
- Check internet: Use wired connection if possible
- Upgrade API plan: Higher-tier plans have better rate limits
Use Superbench to test which model gives best speed/quality balance for your content!
API errors - what do they mean?
"Invalid API Key" / "Authentication Failed":
- Check
api_keys.txtfor typos - Ensure format:
openai_key=sk-...oranthropic_key=sk-ant-...orgemini_key=AI... - Verify key is active on provider dashboard
- Check no extra spaces or quotes around key
"Rate Limit Exceeded":
- Too many requests too quickly
- Wait 1-2 minutes and retry
- Upgrade to higher API tier for increased limits
- Translate smaller batches
"Context Length Exceeded" / "Token Limit":
- Document + TM matches + prompts + images exceed model's context window
- Solution 1: Use model with larger context (Gemini 1.5 Pro: 2M tokens)
- Solution 2: Translate fewer segments at once
- Solution 3: Reduce number of TM matches shown
- Solution 4: Remove figure context if not needed
"Insufficient Credits" / "Quota Exceeded":
- API account out of credits
- Add funds to provider billing dashboard
- Check current balance and usage
"Connection Error" / "Timeout":
- Internet connection lost
- Firewall blocking API requests
- Try different network or VPN
- Check antivirus isn't blocking connections
Filter highlighting not working
Issue: Text doesn't highlight when I type in Filter Source/Target box
Solution:
- Make sure you press Enter after typing search term
- Filter applies when you press Enter, not automatically while typing
- Check spelling of search term (case-insensitive but must match)
Issue: No results found but I know the term exists
Solution:
- Ensure you're searching in correct column (Source vs Target)
- Check for typos in search term
- Try simpler search (single word instead of phrase)
Termbase matches not showing
Issue: Termbase loaded but no blue/pink highlighting
Solution:
- Check termbase is activated: Termbases tab → Termbase checkbox should be checked
- Ensure terms exist in termbase: Termbases tab → Right-click → View Terms
- Check if source segments actually contain termbase terms
- Try Extract Terms button if using project termbase
Issue: Too many/too few matches highlighted
Solution:
- Settings → General → TM/Termbase Options
- Adjust "Hide shorter matches" setting
- Change sort order (appearance / alphabetical / length)
- Create more specific termbase entries
Voice dictation (Supervoice) not working
Issue: F9 doesn't start recording
Solution:
- Check Supervoice is enabled: Settings → General → Enable Supervoice
- Ensure Whisper model is downloaded: First use downloads model automatically
- Check microphone permissions (Windows: Settings → Privacy → Microphone)
- Test microphone in other apps to verify it works
Issue: Recording starts but no text appears
Solution:
- Wait a moment - processing takes a few seconds
- Check if you spoke loudly/clearly enough
- Try larger Whisper model (base or small instead of tiny)
- Ensure microphone volume is adequate
Issue: Wrong language recognized
Solution:
- Supervoice uses target language by default
- Make sure target language is set correctly for your project
- Some accents may be harder to recognize - try clearer pronunciation
Universal Lookup not working
Issue: Ctrl+Alt+L does nothing
Solution:
- Check Universal Lookup is enabled: Settings → General → Enable Universal Lookup
- Ensure Supervertaler is running (doesn't need to be focused window)
- Make sure you selected text before pressing Ctrl+Alt+L
- Check if another program is using the same hotkey
Issue: "No matches found"
Solution:
- Ensure at least one TM is activated in TM tab
- Check selected text actually exists in your TMs
- Try selecting less text (single term instead of full sentence)
How do I report a bug?
Before Reporting:
- Check if issue is already known: GitHub Issues
- Update to latest version (current: v1.7.8)
- Update Python libraries:
pip install -r requirements.txt --upgrade
When Reporting:
Version info:
- Supervertaler version (shown in window title)
- Python version:
python --version - OS: Windows 10/11, macOS version, or Linux distro
Error details:
- Exact error message (screenshot if possible)
- Steps to reproduce the bug
- What you expected vs what happened
Context:
- Which feature were you using? (AI translation, voice dictation, TM, etc.)
- File formats involved (DOCX, TMX, XLIFF, etc.)
- Any relevant settings or configuration
Submit to: github.com/michaelbeijer/Supervertaler/issues
Response time: Typically 1-3 days depending on complexity
Project Management
What is a project file (.svproj)?
A .svproj file is a Supervertaler project file. It stores your segments (source/target), statuses, language pair, and per-project settings so you can close and continue later.
How do I save and reopen a project?
- Save: Ctrl+S
- Open: Ctrl+O
You can also use the File menu to save/open projects.
Does Supervertaler support multi-file projects?
Yes. You can import an entire folder of supported files as a single project via File → Import → Folder (Multiple Files).
Development & Community
Why was Supervertaler created?
Problem:
- Existing CAT tools had limited or expensive AI integration
- Needed flexible multi-provider access (OpenAI, Claude, Gemini)
- Wanted custom prompt control and termbase integration
- Required context-aware translation, not just sentence-by-sentence MT
Solution: Michael Beijer, a professional translator, created Supervertaler to:
- Provide powerful AI translation with full context
- Enable custom prompts and domain expertise
- Support multiple AI providers (avoid vendor lock-in)
- Integrate with existing CAT tools (TMX, XLIFF, bilingual DOCX)
- Offer professional features (TM, termbases, voice dictation)
- Share openly with translation community (open source)
Philosophy:
- Human translator + AI assistant = best results
- Flexibili
…(truncated)