# Supervertaler - Frequently Asked Questions

> Welcome to the Supervertaler FAQ! Find answers to common questions about installation, features, workflow, and troubleshooting.

- Skill: `tools-only/supervertaler-frequently-asked-questions-5` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/supervertaler-frequently-asked-questions-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/supervertaler-frequently-asked-questions-5/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/supervertaler-frequently-asked-questions-5

---

# 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](#about-supervertaler)
   - [What is Supervertaler?](#what-is-supervertaler)
   - [Who created Supervertaler?](#who-created-supervertaler)
   - [Who is Supervertaler for?](#who-is-supervertaler-for)
   - [How does Supervertaler compare to other translation tools?](#how-does-supervertaler-compare-to-other-translation-tools)

- [Getting Started](#getting-started)
   - [What do I need to run Supervertaler?](#what-do-i-need-to-run-supervertaler)
   - [How much does it cost?](#how-much-does-it-cost)
   - [How do I install Supervertaler?](#how-do-i-install-supervertaler)
   - [How do I get API keys?](#how-do-i-get-api-keys)

- [Features & Capabilities](#features-capabilities)
   - [What are the key features of v1.9.27?](#what-are-the-key-features-of-v1927)
   - [What are the three view modes?](#what-are-the-three-view-modes)
   - [What is the Unified Prompt Library?](#what-is-the-unified-prompt-library)
   - [What is figure/image context support?](#what-is-figureimage-context-support)
   - [How does the translation memory work?](#how-does-the-translation-memory-work)
   - [How do keyboard shortcuts work?](#how-do-keyboard-shortcuts-work)
   - [What is CAT tag handling?](#what-is-cat-tag-handling)

- [Technical Questions](#technical-questions)
   - [What AI models are supported?](#what-ai-models-are-supported)
   - [How does AI translation work in Supervertaler?](#how-does-ai-translation-work-in-supervertaler)
   - [What file formats are supported?](#what-file-formats-are-supported)
   - [What programming language is it built with?](#what-programming-language-is-it-built-with)
   - [Can I use Supervertaler offline?](#can-i-use-supervertaler-offline)
   - [How do I set up Local LLM (Ollama)?](#how-do-i-set-up-local-llm-ollama)
   - [What are the system requirements?](#what-are-the-system-requirements)

- [Workflow & Integration](#workflow-integration)
   - [How do I integrate Supervertaler with my CAT tool?](#how-do-i-integrate-supervertaler-with-my-cat-tool)
   - [What's the typical translation workflow?](#whats-the-typical-translation-workflow)
   - [How do I handle large documents?](#how-do-i-handle-large-documents)
   - [Can I customize the AI prompts?](#can-i-customize-the-ai-prompts)
   - [How do I use Universal Lookup?](#how-do-i-use-universal-lookup)

- [Troubleshooting](#troubleshooting)
   - [Why is translation slow?](#why-is-translation-slow)
   - [API errors - what do they mean?](#api-errors-what-do-they-mean)
   - [Filter highlighting not working](#filter-highlighting-not-working)
   - [Termbase matches not showing](#termbase-matches-not-showing)
   - [Voice dictation (Supervoice) not working](#voice-dictation-supervoice-not-working)
   - [Universal Lookup not working](#universal-lookup-not-working)
   - [How do I report a bug?](#how-do-i-report-a-bug)

- [Project Management](#project-management)
   - [What is a project file (.svproj)?](#what-is-a-project-file-svproj)
   - [How do I save and reopen a project?](#how-do-i-save-and-reopen-a-project)
   - [Does Supervertaler support multi-file projects?](#does-supervertaler-support-multi-file-projects)

- [Development & Community](#development-community)
   - [Why was Supervertaler created?](#why-was-supervertaler-created)
   - [What's the development history?](#whats-the-development-history)
   - [Why is it open source?](#why-is-it-open-source)
   - [Why the name "Supervertaler"?](#why-the-name-supervertaler)

- [Privacy & Commercial Use](#privacy-commercial-use)
   - [Is my translation data private?](#is-my-translation-data-private)
   - [Are my website passwords stored by the embedded browser?](#are-my-website-passwords-stored-by-the-embedded-browser)
   - [Can I use Supervertaler commercially?](#can-i-use-supervertaler-commercially)
   - [How can I support the project?](#how-can-i-support-the-project)

- [More Resources](#more-resources)
   - [Where can I learn more?](#where-can-i-learn-more)
   - [What's next for Supervertaler?](#whats-next-for-supervertaler)

- [Need More Help?](#need-more-help)

---

## 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](https://michaelbeijer.co.uk/)  
**GitHub**: [github.com/michaelbeijer/Supervertaler](https://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:**
```bash
# 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](../get-started/installation.md) 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?

```bash
# 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](../get-started/installation.md)

### How do I get API keys?

**Anthropic Claude (Recommended):**
1. Visit: https://console.anthropic.com/
2. Sign up or log in
3. Settings → API Keys → "Create Key"
4. Copy key (starts with `sk-ant-api03-...`)
5. Add to `api_keys.txt`: `ANTHROPIC_API_KEY=sk-ant-api03-...`

**OpenAI GPT:**
1. Visit: https://platform.openai.com/
2. Sign up or log in
3. API Keys section → "Create new secret key"
4. Copy key (starts with `sk-proj-...` or `sk-...`)
5. Add to `api_keys.txt`: `OPENAI_API_KEY=sk-proj-...`

**Google Gemini:**
1. Visit: https://aistudio.google.com/
2. Sign up or log in
3. Click "Get API Key"
4. Copy key (starts with `AIza...`)
5. 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`, `.ntl` files
- Industry standards retained: `.tmx` for 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:**
1. Prompt Manager tab → Browse folders
2. Right-click prompt → "Set as Primary" or "Attach"
3. Translate normally - prompts automatically applied

See: [Prompt Library](../ai-translation/prompt-library.md)

### What is figure/image context support?

Load images to provide visual context for AI translation - essential for technical documents.

**How it works:**
1. Prepare folder with images: `Figure 1.png`, `Figure 2A.jpg`, etc.
2. Resources → 🖼️ Load Figure Context → Select folder
3. When AI detects "Figure 1" in text, it includes the image automatically
4. 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](../editor/keyboard-shortcuts.md)

### 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:**
1. **Detection**: System prompts identify common CAT tag patterns
2. **Instruction**: AI told to preserve ALL tags unchanged
3. **Validation**: Tags verified after translation (future feature)
4. **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:

1. **Document context:** Surrounding segments for coherence
2. **Translation Memory:** Fuzzy matches from active TMs
3. **Termbase matches:** Relevant terminology highlighted
4. **System prompt:** CAT tag handling instructions
5. **Custom prompts:** Domain expertise, style guides
6. **Figure context:** Images referenced in technical documents

**Translation Process:**
1. You select segments and press F5 (or Translate button)
2. Supervertaler assembles context: TM matches, termbase, prompts, figures
3. Sends source + context to AI API
4. AI generates translation following all instructions
5. Translation inserted into target cell
6. 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**
1. Download Ollama from https://ollama.com
2. Run the installer (Windows/Mac/Linux supported)
3. Ollama starts automatically in the background

**Step 2: Download a Model**
Open a terminal/command prompt and run:
```bash
# Recommended — purpose-built translation model (12GB+ RAM):
ollama pull translategemma:12b

# For 24GB+ RAM (highest translation quality):
ollama pull translategemma:27b

# For 6GB RAM (lighter, still translation-tuned):
ollama pull translategemma:4b
```

**Step 3: Configure Supervertaler**
1. Go to **Settings → LLM Settings**
2. Select **"🖥️ Local LLM (Ollama)"** as your provider
3. Choose your downloaded model from the dropdown
4. Click **Save LLM Settings**

**Model Recommendations by RAM:**
| RAM | Recommended Model | Quality |
|-----|------------------|---------|
| 4 GB | qwen3:4b | ★★★☆☆ |
| 6 GB | translategemma:4b | ★★★★☆ |
| 12 GB | translategemma:12b | ★★★★★ |
| 24 GB+ | translategemma:27b | ★★★★★ |

**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:**

1. **Use pip install (Recommended)**
   - Install: `pip install supervertaler`
   - Run: `supervertaler`
   - No AV warnings because it runs from Python source

2. **Whitelist the application**
   - Add an exception in your antivirus settings
   - The application is safe - you can verify by checking the [source code on GitHub](https://github.com/michaelbeijer/Supervertaler)

3. **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](https://pyinstaller.org/en/stable/faq.html) for more details.

---

## Workflow & Integration

### How do I integrate Supervertaler with my CAT tool?

**Method 1: TMX Exchange (Most Compatible)**
1. **In CAT tool:** Export source segments as TMX
2. **In Supervertaler:** Import TMX → Translate → Export TMX
3. **In CAT tool:** Import translated TMX
4. **Result:** Target segments populated in your CAT project

**Method 2: XLIFF (Standard)**
1. **In CAT tool:** Export XLIFF file
2. **In Supervertaler:** Import XLIFF → Translate → Export XLIFF
3. **In CAT tool:** Import translated XLIFF
4. **Result:** Translations with segment metadata preserved

**Method 3: Copy-Paste (Quick)**
1. **In CAT tool:** Copy source segments
2. **In Supervertaler:** Paste as TXT → Import → Translate → Copy targets
3. **In CAT tool:** Paste translations
4. **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):**
1. Launch Supervertaler
2. File → Import → Select DOCX or TXT
3. Select segments (or Ctrl+A for all)
4. Press F5 to translate
5. Review and edit translations
6. File → Export → DOCX

**Professional Project Workflow:**
1. **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)

2. **Translate:**
   - Select segments to translate
   - Press F5
   - AI translates with TM/termbase/prompt context
   - Segments auto-saved to active TMs

3. **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)

4. **Quality Assurance:**
   - Search for specific terms (Ctrl+F)
   - Check consistency of key terminology
   - Review AI Assistant suggestions

5. **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:**
1. Press F9 to start dictating (works system-wide)
2. Speak your translation
3. Press F9 to stop and insert text
4. 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:**
1. Prompt Manager tab → Right-click folder → New Prompt
2. Write your instructions in plain language
3. Save to appropriate folder
4. Right-click prompt → "Set as Primary" or "Attach"

**AI-Generated Prompts:**
1. AI Assistant tab → Attach document (PDF/DOCX)
2. Ask: "Analyze this style guide and create a prompt"
3. AI generates custom prompt based on document
4. 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](../ai-translation/prompt-library.md) for full details

### How do I use Universal Lookup?

**System-Wide TM Search:**
1. Activate Universal Lookup: Settings → General → Enable Universal Lookup
2. Press Ctrl+Alt+L from ANY application (Word, browser, email, etc.)
3. Select text you want to look up
4. Press Ctrl+Alt+L
5. 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:**
1. **Model choice:** Claude 3 Opus, GPT-4 are slower than Flash/Haiku variants
2. **Large context:** Many TM matches, large document, figure images
3. **Internet speed:** Slow connection increases API response time
4. **Provider rate limits:** Some API plans throttle requests
5. **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.txt` for typos
- Ensure format: `openai_key=sk-...` or `anthropic_key=sk-ant-...` or `gemini_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:**
1. Check termbase is activated: Termbases tab → Termbase checkbox should be checked
2. Ensure terms exist in termbase: Termbases tab → Right-click → View Terms
3. Check if source segments actually contain termbase terms
4. 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:**
1. Check Supervoice is enabled: Settings → General → Enable Supervoice
2. Ensure Whisper model is downloaded: First use downloads model automatically
3. Check microphone permissions (Windows: Settings → Privacy → Microphone)
4. 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:**
1. Check Universal Lookup is enabled: Settings → General → Enable Universal Lookup
2. Ensure Supervertaler is running (doesn't need to be focused window)
3. Make sure you selected text before pressing Ctrl+Alt+L
4. 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:**
1. Check if issue is already known: [GitHub Issues](https://github.com/michaelbeijer/Supervertaler/issues)
2. Update to latest version (current: v1.7.8)
3. Update Python libraries: `pip install -r requirements.txt --upgrade`

**When Reporting:**
1. **Version info:**
   - Supervertaler version (shown in window title)
   - Python version: `python --version`
   - OS: Windows 10/11, macOS version, or Linux distro

2. **Error details:**
   - Exact error message (screenshot if possible)
   - Steps to reproduce the bug
   - What you expected vs what happened

3. **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](https://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 communit

…(truncated)