# Supervertaler User Guide
## AI-Powered Professional Translation Tool

> **⚠️ OUTDATED DOCUMENTATION**  
> This guide was last updated for v3.7.1 (October 2025) and contains outdated information.  
> **Current Version:** v1.7.8 (November 22, 2025)  
> **For up-to-date information, see:**
> - [CHANGELOG.md](../../CHANGELOG.md) - Latest features and changes
> - [PROJECT_CONTEXT.md](../PROJECT_CONTEXT.md) - Complete project reference
> - [Supervertaler Website](https://supervertaler.com) - Current documentation

**Last Updated**: October 22, 2025  
**Guide Version**: v3.7.1 (OUTDATED)

---

## 🚀 What Makes Supervertaler Different?

Supervertaler combines two groundbreaking capabilities that set it apart from all other translation tools:

### 1. 🎯 Multi-Context Intelligence

**The Problem**: Traditional AI translation tools treat each document in isolation. They see words, not context.

**The Supervertaler Solution**: Feed the AI multiple context sources simultaneously:
- � **Translation Memory** - Your institution's terminology and style
- 📝 **Custom Instructions** - Project-specific guidance
- 📋 **Tracked Changes** - Learn from your editing patterns
- 🖼️ **Document Images** - Visual context for figures and diagrams
- 🎨 **Style Guides** - Tone, register, and formatting rules

**Result**: The AI understands your document like a human translator would—seeing the full picture, not just words in isolation.

### 2. 🧠 Unified Prompt Intelligence System

**The Problem**: Most tools apply one generic prompt to all content. Supervertaler's innovation is fundamentally different.

**The Supervertaler Approach** (3-tier system):
1. **System Prompt** - Core translation philosophy and rules
2. **Custom Instructions** - Document-specific requirements  
3. **Style Guide** - Tone, formatting, and presentation

**The Magic Part**: You don't write these manually. **Ask Supervertaler to analyze YOUR document and generate these prompts for you.** Then it uses those same prompts to translate.

**Why This Works**: Instead of generic rules applied to specific content, the AI understands *your* content first, then applies tailored rules to it.

**Vision (Coming Soon)**: One-click process:
```
Click "Auto-Translate"
  ↓
Supervertaler analyzes your document
  ↓
Generates optimized prompts based on content
  ↓
Translates/proofreads/localizes using those prompts
  ↓
Optional: Proofreading pass for final quality
  ↓
Done - Professional results in seconds
```

---

## 📖 Quick Navigation

### Getting Started
- **[Installation](#installation--setup)** - 5 minutes to launch
- **[API Keys Setup](#api-keys-setup)** - Secure key configuration
- **[First Translation](#quick-start-guide)** - Your first 5-minute translation

### Core Workflows
- **[Document Import & CAT Editing](#bilingual-docx-workflow-v241)** - Professional document translation
- **[Prompt Customization](#prompt-manager)** - Build better AI with system prompts, custom instructions, style guides
- **[Module Usage](#specialized-modules)** - PDF Rescue, Text Repair, and more

### Reference
- **[Translation Memory](#translation-memory)** - Consistency and efficiency
- **[AI Providers](#ai-provider-settings)** - Model selection guide
- **[Troubleshooting](#troubleshooting)** - Problem solving

---

## Table of Contents

1. [Installation & Setup](#installation--setup)
2. [API Keys Setup](#api-keys-setup)
3. [Quick Start Guide](#quick-start-guide)
4. [Prompt Manager](#prompt-manager)
5. [Prompt Assistant](#prompt-assistant)
6. [Document Import & CAT Workflow](#bilingual-docx-workflow-v241)
7. [Translation Mode](#translation-mode)
8. [Proofreading Mode](#proofreading-mode)
9. [Context Sources](#context-sources)
10. [Specialized Modules](#specialized-modules)
11. [Project Library](#project-library)
12. [AI Provider Settings](#ai-provider-settings)
13. [Troubleshooting](#troubleshooting)

## Installation & Setup

### System Requirements

- **OS**: Windows 10/11, macOS 10.13+, or Linux (any recent distribution)
- **Python**: 3.8+ (3.12 recommended)
- **RAM**: 4GB minimum, 8GB recommended
- **Disk**: ~50 MB for Supervertaler + dependencies
- **Internet**: Required for AI API calls
- **API Keys**: At least one from: OpenAI (GPT-4/GPT-5), Anthropic (Claude), or Google (Gemini)

### Windows Installation

**Step 1: Verify Python**
```powershell
python --version
```
If missing, download from [python.org](https://www.python.org/downloads) and install with "Add Python to PATH" checked.

**Step 2: Download Supervertaler**
```powershell
git clone https://github.com/michaelbeijer/Supervertaler.git
cd Supervertaler
```
Or manually download ZIP from GitHub and extract.

**Step 3: Install Dependencies**
```powershell
pip install anthropic openai google-generativeai python-docx pillow lxml
```

**Step 4: Setup API Keys**
See [API Keys Setup](#api-keys-setup) below.

**Step 5: Launch**
```powershell
python Supervertaler_v3.7.1.py
```

### macOS Installation

```bash
# Verify Python
python3 --version

# Clone repository
git clone https://github.com/michaelbeijer/Supervertaler.git
cd Supervertaler

# Install dependencies
pip3 install anthropic openai google-generativeai python-docx pillow lxml

# Launch
python3 Supervertaler_v3.7.1.py
```

### Linux Installation

**Ubuntu/Debian**:
```bash
sudo apt update
sudo apt install python3 python3-pip python3-tk

git clone https://github.com/michaelbeijer/Supervertaler.git
cd Supervertaler

pip3 install anthropic openai google-generativeai python-docx pillow lxml

python3 Supervertaler_v3.7.1.py
```

**Fedora/RHEL**:
```bash
sudo dnf install python3 python3-pip python3-tkinter

git clone https://github.com/michaelbeijer/Supervertaler.git
cd Supervertaler

pip3 install anthropic openai google-generativeai python-docx pillow lxml

python3 Supervertaler_v3.7.1.py
```

---

## API Keys Setup

### 🔒 Security Model

Your API keys are **100% local** and never uploaded:
- ✅ `api_keys.txt` (your keys) - Excluded from git
- ✅ `user data/` folder - Excluded from git
- ✅ `api_keys.example.txt` (template) - Safe to share

### Quick Setup (3 Steps)

**Step 1: Copy the template**
```powershell
Copy-Item "api_keys.example.txt" "api_keys.txt"  # Windows
cp api_keys.example.txt api_keys.txt              # macOS/Linux
```

**Step 2: Get your keys** (choose at least one):

| Provider | How | Pricing |
|----------|-----|---------|
| **OpenAI** | https://platform.openai.com/api-keys | ~$0.01-0.15 per 1K words |
| **Claude** | https://console.anthropic.com/settings/keys | ~$0.015-0.075 per 1K words |
| **Gemini** | https://aistudio.google.com/app/apikey | Free tier + pay-as-you-go |

**Step 3: Edit `api_keys.txt`**

Remove `#` from lines you want to use:
```
openai = sk-proj-YOUR_KEY_HERE
claude = sk-ant-YOUR_KEY_HERE
#google = YOUR_KEY_HERE
```

**No quotes, spaces around `=` are fine, one key per line.**

### Verify Setup

Launch Supervertaler and click **"List Models"**. You should see available models for your configured providers.

---

## Quick Start Guide

### Your First Translation (5 Minutes)

**Input** (`test.txt`):
```
Hello, world!
This is a test translation.
```

**Steps**:
1. Launch Supervertaler
2. **Input File**: Click Browse, select `test.txt`
3. **Source**: English
4. **Target**: Dutch
5. **Provider**: OpenAI (or your configured provider)
6. **Model**: GPT-4o
7. Click **"Start Process"**

**Output** (`test_translated.txt`):
```
Hello, world!	Hallo, wereld!
This is a test translation.	Dit is een testvertaling.
```

Two files are created:
- `test_translated.txt` - Tab-separated translations
- `test_translated.tmx` - Translation memory file

---

## Prompt Manager

### 🧠 The Three-Tier Prompt System

Supervertaler's power comes from a unified prompt hierarchy that works together:

```
System Prompt (Foundation)
    ↓
Custom Instructions (Project-specific)
    ↓
Style Guide (Tone & Formatting)
```

All three feed into the AI for superior translation accuracy.

### System Prompts

**Purpose**: Core translation philosophy and rules

**Creating a System Prompt**:
1. Click **"Prompt Manager"** tab
2. Click **"System Prompts"** subtab
3. Click **"➕ New"** button
4. Enter descriptive name (e.g., "Medical Terminology")
5. Write your prompt template

**Example System Prompt**:
```
You are an expert {source_lang} to {target_lang} translator 
specializing in medical documentation.

KEY RULES:
- Preserve all drug names unchanged
- Use formal medical register
- Maintain accuracy for dosage information
- Never translate acronyms (FDA, WHO, etc.)

TERMINOLOGY:
- "adverse event" → "evento adverso"
- "off-label" → "fuera de ficha técnica"
```

**Template Variables**:
- `{source_lang}` - Auto-replaced with actual source language
- `{target_lang}` - Auto-replaced with actual target language

**File Location**: `user data/Prompt_Library/System_prompts/`

**Naming Convention**: `Name (system prompt).md`

### Custom Instructions

**Purpose**: Document-specific requirements beyond system rules

**Creating Custom Instructions**:
1. Click **"Prompt Manager"** tab
2. Click **"Custom Instructions"** subtab  
3. Click **"➕ New"** button
4. Name it (e.g., "Project_ABC_Terminology")
5. Add specific guidance

**Example Custom Instructions**:
```
This document is a marketing brochure for eco-friendly products.

REQUIREMENTS:
- Emphasize environmental benefits
- Use conversational, engaging tone
- Adapt brand voice for target culture
- Keep sentences short and punchy

GLOSSARY:
- "sustainable packaging" → remains "sustainable packaging"
- "eco-friendly" → "respetuoso del medio ambiente"
- Company names: DO NOT TRANSLATE
```

**File Location**: `user data/Prompt_Library/Custom_instructions/`

**Naming Convention**: `Name (custom instruction).md`

### Style Guides

**Purpose**: Tone, formatting, and presentation rules

**Creating a Style Guide**:
1. Click **"Prompt Manager"** tab
2. Click **"Style Guides"** subtab
3. Click **"➕ New"** button
4. Name it (e.g., "Formal_Legal_Register")
5. Define the style

**Example Style Guide**:
```
FORMAL LEGAL REGISTER

TONE: Formal, precise, unambiguous
AUDIENCE: Lawyers and legal professionals

RULES:
- Use passive voice where appropriate
- Maintain legal terminology consistency
- Full formal titles (not abbreviations)
- Serial comma style: "a, b, and c"

FORMATTING:
- Numbered lists for legal points
- Bold for defined terms
- Italics for foreign language insertions

REGISTER EXAMPLES:
- "must" (not "should")
- "shall" (not "will")
- "aforementioned" (not "mentioned above")
```

**File Location**: `user data/Prompt_Library/Style_Guides/`

**Naming Convention**: `Name (style guide).md`

### Using Prompts in Translation

1. Select **System Prompt**: Click to highlight
2. Select **Custom Instructions**: Add project-specific guidance
3. Select **Style Guide**: Define output tone
4. All three are sent to the AI together
5. Run translation

The AI receives all three contexts simultaneously, producing superior results.

---

## Prompt Assistant

### 🤖 AI-Powered Prompt Generation

**The Innovation**: Instead of manually writing prompts, let Supervertaler analyze your document and generate optimized prompts automatically.

### How It Works

**Step 1: Upload Your Document**
- Click **"Prompt Assistant"** tab
- Click **"📄 Analyze Document"**
- Select your source document or paste sample text
- Click **"Analyze"**

**Step 2: AI Analysis**
- Supervertaler reads your document
- Identifies domain, tone, complexity, terminology, style
- Generates three tailored prompts based on your content

**Step 3: Review Generated Prompts**
Three prompts appear in the interface:
1. **System Prompt** - Domain-specific rules for translation
2. **Custom Instructions** - Document-specific requirements
3. **Style Guide** - Tone and formatting rules

Each prompt is specifically tailored to your document's characteristics.

**Step 4: Optional - Edit Style Guides**
- Click **"🎨 Edit Style Guide"** to customize tone
- Adjust formality, register, target audience
- Changes apply to the analysis results

**Step 5: Use for Translation**
- Click **"✅ Use These Prompts"** to apply them
- All three prompts are selected in Prompt Manager
- Run your translation with document-optimized prompts

### Example: Auto-Generated Prompts

**Input Document**: "Medical device manual for emergency room nurses"

**Generated System Prompt**:
```
You are an expert English to Dutch translator specializing in 
medical device documentation for clinical settings.

FOCUS AREAS:
- Patient safety is paramount
- Preserve all warnings and cautions exactly
- Medical terminology must be precise
- Never translate equipment model numbers
- Maintain formal, professional tone
```

**Generated Custom Instructions**:
```
This is a clinical medical device manual targeting emergency nurses.

CHARACTERISTICS:
- Audience: Medical professionals (high literacy)
- Content: Safety-critical procedures and warnings
- Format: Procedural steps with visual elements
- Tone: Clear, precise, action-oriented

CRITICAL: Safety warnings must be prominent and unambiguous.
```

**Generated Style Guide**:
```
MEDICAL-CLINICAL REGISTER

TONE: Professional, authoritative, safety-focused
AUDIENCE: Emergency room nursing staff

TERMINOLOGY:
- "must" for critical safety procedures
- "should" for best practices
- "may" for optional procedures
- All drug names unchanged
- All equipment codes unchanged

FORMATTING:
- Numbered procedures (not bullets)
- ⚠️ WARNING in capitals
- Bold for critical information
```

### Best Practices

1. **Analyze Samples First**: Paste first 500 words to generate initial prompts
2. **Review Carefully**: Check generated prompts make sense for your content
3. **Edit If Needed**: Refine any prompts that miss the mark
4. **Iterate**: Analyze again if you want different prompts
5. **Save Good Prompts**: Save regularly-used prompts to your library

---

## Bilingual DOCX Workflow (v2.4.1)

### Import, Translate, Export with Formatting Preserved

**Workflow**:
```
CAT Tool (memoQ/Trados)
    ↓ Export Bilingual DOCX
Supervertaler
    ↓ Import → Configure → Translate → Export
CAT Tool
    ↓ Re-import
Done
```

### Step-by-Step

**Step 1: Export from CAT Tool**
- Open project in memoQ (or Trados, CafeTran, etc.)
- Export bilingual DOCX file
- Save to your working folder

**Step 2: Import to Supervertaler**
- Click **"📄 Import Bilingual DOCX"** button
- Select bilingual DOCX file
- ✅ Segments, formatting, and CAT tags automatically extracted

**Step 3: Configure**
- **Source/Target Languages**: Auto-detected
- **Provider/Model**: Select your AI service
- **Prompts** (optional): Choose domain prompts if desired

**Step 4: Translate**
- Click **"Start Process"**
- Watch progress bar
- ✅ Formatting preserved automatically

**Step 5: Export**
- Click **"💾 Export to Bilingual DOCX"**
- File saved with `_translated` suffix
- ✅ Ready to re-import to CAT tool

### What Gets Preserved

✅ **Formatting**: Bold, italic, underline text  
✅ **CAT Tags**: memoQ, Trados, CafeTran tag formats  
✅ **Metadata**: Segment IDs, project info, status  
✅ **Success Rate**: 100% in testing

### Important: Trados Studio Re-Import Rule

⚠️ **Critical**: Trados only imports changes to **already-translated** segments.

**Correct Workflow**:
1. In Trados: Pre-translate or add dummy translation
2. Export bilingual file
3. In Supervertaler: Import → Translate → Export
4. In Trados: Re-import
5. ✅ Changes accepted

**Incorrect Workflow**:
1. In Trados: Export with empty/untranslated segments
2. In Supervertaler: Add translations
3. In Trados: Re-import
4. ❌ Changes ignored (segments stay empty)

**Solution**: Pre-translate in Trados first, then refine in Supervertaler.

---

---

## Project Library

The Project Library enables complete workspace management, allowing you to save and restore entire application configurations for different clients, projects, or content types.

### Creating Projects

#### Step 1: Configure Your Workspace

Set up all your settings:
- **File Paths**: Input file, TM, tracked changes, images
- **Language Pair**: Source and target languages
- **AI Provider and Model**: Selected AI service
- **Custom Instructions**: Project-specific guidance
- **Active Prompts**: Domain-specific prompts

#### Step 2: Save Project

1. Click **"Project Library"** button
2. Click **"Save Current Configuration"**
3. Enter a descriptive name

**Naming Convention Examples**:
- `Client_ProjectName_ContentType`
- `ABC_Corp_TechnicalManuals`
- `XYZ_Legal_Contracts_2024`
- `Medical_Device_Manual_ClientABC`

#### Step 3: Verify Save

Project saved to `user data/Projects/` or `user data/Projects_private/` folder as JSON file

### Loading Projects

#### Step 1: Browse Library

Click **"Project Library"** to view saved configurations

#### Step 2: Select Project

Click desired project from the list

#### Step 3: Automatic Loading

All settings restored instantly:
- ✅ File paths updated to saved locations
- ✅ Language pair set
- ✅ AI provider and model selected
- ✅ Custom instructions loaded
- ✅ Active prompts restored

### Project Management

**Organization Strategy**:
- **Client-Based**: Separate projects per client
- **Content-Based**: Group by content type (legal, technical, marketing)
- **Time-Based**: Include dates for version control

**File Management**:
- Projects stored as JSON files in `user data/Projects/` folder
- Private projects in `user data/Projects_private/` (excluded from git)
- Include timestamps for version tracking
- Export important projects for backup
- Cross-platform path compatibility (Windows, macOS, Linux)

### Advanced Features

**Cross-Platform Support**:
- File paths automatically adjust between operating systems
- Clickable folder paths work on Windows, macOS, and Linux
- Seamless collaboration across different platforms

**Version Control**:
- Projects include creation timestamps
- Easy to track configuration evolution
- Backup and restore capabilities

---

## Translation Mode

Translation mode is designed for translating source text into target language with maximum accuracy and context awareness.

### Input Requirements

**File Format**: Plain text file (.txt)  
**Content Structure**: One segment per line

**Example**:
```
CLAIMS
A vehicle control method, comprising:
obtaining sensor information of different modalities...
sending the short-cycle message information to a first data model...
```

### Configuration Options

#### Basic Settings
- **Input File**: Source text file path (Browse button)
- **Source Language**: Source language (e.g., "English", "German")
- **Target Language**: Target language (e.g., "Dutch", "French")
- **Switch Languages**: ⇄ button to quickly swap source/target
- **Chunk Size**: Number of lines processed per AI request (default: 50)

#### AI Provider Selection

**OpenAI Models**:
- **GPT-5**: Latest reasoning model - excellent for complex content
- **GPT-4o**: Multimodal capabilities with strong general performance
- **GPT-4**: Reliable baseline performance
- **GPT-4-turbo**: Enhanced context window

**Claude Models**:
- **Claude-3.5-Sonnet**: Excellent creative and nuanced content
- **Claude-3-Haiku**: Fast processing for simpler content

**Gemini Models**:
- **Gemini-2.5-Pro**: Strong technical performance
- **Gemini-1.5-Flash**: Fast processing option

### Context Sources

#### Translation Memory (TM)
**Supported Formats**: TMX, TXT (tab-separated)  
**Benefits**: 
- Exact matches provide instant consistency
- Fuzzy matches guide similar content
- Builds institutional knowledge

#### Custom Instructions
**Purpose**: Project-specific guidance

**Examples**:
```
This is a technical manual for automotive engineers.
Maintain formal tone and use metric measurements.
Preserve all part numbers exactly as written.
```

#### Tracked Changes
**Input**: DOCX files with revision tracking or TSV editing patterns  
**Function**: AI learns from human editing patterns  
**Benefits**: Adapts to preferred terminology and style choices

#### Document Images
**Format**: PNG, JPG, GIF supported  
**Function**: Visual context for figure references  
**Usage**: AI automatically detects figure mentions and provides relevant images

### Domain-Specific Prompts

Choose from 8 professional prompt collections:
- Medical, Legal, Patent, Financial
- Technical, Marketing, Crypto, Gaming

Active prompts shown with ⚡ symbol.

### Output Files

#### Primary Output: `filename_translated.txt`
Tab-separated source and target:
```
Source Text[TAB]Translated Text
CLAIMS[TAB]CONCLUSIES
A vehicle control method[TAB]Een voertuigbesturingsmethode
```

#### Translation Memory: `filename_translated.tmx`
Standard TMX format compatible with:
- memoQ
- Trados Studio
- CafeTran Espresso
- Wordfast Pro
- OmegaT

#### Session Report: `filename_translated_report.md`
Comprehensive documentation including:
- Complete AI prompts used
- Session settings and configuration
- Processing statistics
- Context sources utilized
- Timestamp and version information

### Best Practices

**File Preparation**:
1. Extract clean source text from CAT tool bilingual export
2. One segment per line, no empty lines
3. Preserve original segmentation from CAT tool
4. Save as UTF-8 encoded text file

**Context Optimization**:
1. Load relevant Translation Memory for consistency
2. Add project-specific custom instructions
3. Include tracked changes from similar previous work
4. Provide document images for visual context

**Quality Assurance**:
1. Review session report for prompt transparency
2. Import generated TMX into CAT tool for exact matches
3. Spot-check translations against original document context
4. Use proofreading mode for revision and refinement

---

## Proofreading Mode

Proofreading mode is designed for revising and improving existing translations, providing detailed change tracking and explanatory comments.

### Input Requirements

**File Format**: Tab-separated text file (.txt)  
**Structure**: Source{TAB}Target format

**Example**:
```
Source Text[TAB]Existing Translation
CLAIMS[TAB]BEWERINGEN
A vehicle control method[TAB]Een werkwijze voor voertuigbesturing
```

### Configuration

#### Basic Settings
- **Input File**: Bilingual tab-separated file
- **Source/Target Languages**: Language pair for the content
- **Provider/Model**: AI selection for proofreading analysis

#### Context Sources (Same as Translation Mode)
- Translation Memory for consistency checking
- Custom instructions for revision guidelines
- Tracked changes for learning preferred revision patterns
- Document images for visual context verification

### Proofreading Process

#### Analysis Approach

The AI performs comprehensive revision focusing on:

**Accuracy Assessment**:
- Terminology consistency
- Technical precision
- Cultural appropriateness
- Completeness verification

**Quality Enhancement**:
- Grammar and syntax improvement
- Style and tone optimization
- Readability enhancement
- Professional register maintenance

**Consistency Checking**:
- Cross-reference with Translation Memory
- Terminology standardization
- Style guide compliance
- Figure reference accuracy

### Output Format

#### Revised Translation: `filename_proofread.txt`

Three-column format with explanations:
```
Source[TAB]Revised_Translation[TAB]Change_Comments
CLAIMS[TAB]CONCLUSIES[TAB]Changed from "BEWERINGEN" to standard patent terminology
A vehicle control method[TAB]Een voertuigbesturingsmethode[TAB]Simplified compound structure for clarity
```

#### Column Structure:
1. **Source**: Original source text
2. **Revised_Translation**: AI-improved translation
3. **Change_Comments**: Explanation of revisions made

#### Session Report: `filename_proofread_report.md`
- Complete proofreading prompts
- Revision statistics and analysis
- Context sources used
- Session configuration details

### Integration Workflow

#### CAT Tool Re-integration:
1. **Import Revised File**: Load 3-column output into spreadsheet/CAT tool
2. **Review Changes**: Use comments column to understand revisions
3. **Selective Application**: Accept/reject changes based on professional judgment
4. **Update Translation Memory**: Add approved revisions to TM database

#### Quality Assurance:
1. **Change Tracking**: Comments explain every modification made
2. **Consistency Verification**: Cross-check with project terminology
3. **Client Review**: Use explanatory comments for client communication
4. **Learning Integration**: Feed back patterns into tracked changes

---

## Context Sources

Supervertaler's multicontextual approach leverages multiple information sources simultaneously to deliver superior translation accuracy.

### Translation Memory (TM)

#### Supported Formats

**TMX Files**: Standard translation memory exchange format
- Full compatibility with major CAT tools
- Preserves metadata and timestamps
- Language pair matching

**TXT Files**: Tab-separated format
```
Source Text[TAB]Translation
Hello world[TAB]Hallo wereld
```

#### Integration Benefits
- **Exact Matches**: Instant consistency for repeated content
- **Fuzzy Matches**: Guidance for similar segments
- **Terminology Consistency**: Standardized term translations
- **Quality Baseline**: Professional translation references

#### Best Practices
1. Use TM from same domain/client for consistency
2. Clean TM data before import (remove outdated entries)
3. Combine multiple relevant TM files
4. Regular TM maintenance and updates

### Custom Instructions

#### Purpose
Project-specific guidance that adapts AI behavior to your requirements.

#### Effective Instructions

**Domain Guidance**:
```
This is a technical manual for automotive engineers.
Use formal, professional language.
Preserve all part numbers and model codes exactly.
Convert imperial measurements to metric.
```

**Style Requirements**:
```
Target audience: General public
Use simple, accessible language
Avoid technical jargon
Maintain friendly, helpful tone
```

**Terminology Guidelines**:
```
Company name "TechCorp" should remain in English
"Software" translates to "Software" (not "Programmatuur")
Use "gebruiker" for "user" (not "afnemer")
```

#### Best Practices
1. Be specific and actionable
2. Include positive examples ("use X") and negative examples ("avoid Y")
3. Address known problem areas from previous work
4. Update instructions based on feedback and results

### Tracked Changes Integration

#### Input Sources

**DOCX Revision Tracking**: Import tracked changes from Word documents
- Captures human editing patterns
- Learns preferred terminology choices
- Understands style preferences

**TSV Editing Patterns**: Before/after comparison data
```
Original[TAB]Edited_Version
Old terminology[TAB]Preferred terminology
Awkward phrasing[TAB]Improved phrasing
```

#### Learning Mechanism

AI analyzes patterns in human edits to understand:
- Terminology preferences
- Style improvements
- Grammar corrections
- Cultural adaptations

#### Benefits
- **Personalized**: Adapts to your editing style
- **Consistent**: Applies learned patterns automatically
- **Improving**: Gets better with more data
- **Efficient**: Reduces post-editing time

### Document Images

#### Visual Context Integration

When source text references figures, charts, or diagrams, Supervertaler can automatically provide visual context to the AI.

#### Supported Formats
- PNG, JPG, JPEG, GIF
- High-resolution images preferred
- Multiple images per document supported

#### Automatic Detection

AI automatically detects figure references in text:
```
"As shown in Figure 1A..."
"See diagram below..."
"The flowchart illustrates..."
```

#### Benefits
- **Accuracy**: Visual context prevents misinterpretation
- **Completeness**: Ensures all visual elements are properly referenced
- **Technical Precision**: Critical for technical/scientific content
- **Cultural Adaptation**: Visual elements may need localization

---

## Translation Memory

Translation Memory (TM) integration provides consistency and efficiency by leveraging previously translated content and professional translation databases.

### Supported Formats

#### TMX (Translation Memory eXchange)

**Industry Standard**: Compatible with all major CAT tools

```xml
<?xml version="1.0" encoding="UTF-8"?>
<tmx version="1.4">
  <header>
    <prop type="x-filename">project.tmx</prop>
  </header>
  <body>
    <tu tuid="1">
      <tuv xml:lang="en">
        <seg>Hello world</seg>
      </tuv>
      <tuv xml:lang="nl">
        <seg>Hallo wereld</seg>
      </tuv>
    </tu>
  </body>
</tmx>
```

**Features**:
- Metadata preservation
- Multiple language pairs
- Timestamps and attributes
- Quality scoring

#### Tab-Separated TXT

**Simple Format**: Easy creation and editing

```
Source Text[TAB]Target Translation
Hello world[TAB]Hallo wereld
Good morning[TAB]Goedemorgen
```

**Use Cases**:
- Quick terminology lists
- Client-specific glossaries
- Manual TM creation
- Legacy data import

### TM Integration Process

#### Loading Translation Memory

1. **File Selection**: Browse and select TMX or TXT files
2. **Language Verification**: Confirm source/target language matching
3. **Import Process**: TM data loaded into memory for matching
4. **Status Confirmation**: Log shows successful import with entry count

#### Matching Algorithm

**Exact Matches**: 100% identical segments
- Instant application for consistency
- Highest confidence level
- Automatic terminology alignment

**Fuzzy Matches**: Similar but not identical segments
- Provides guidance for translation decisions
- Similarity scoring and ranking
- Context-aware matching

**Terminology Extraction**: Key term identification
- Domain-specific vocabulary recognition
- Consistent term translation
- Glossary integration

### Integration with CAT Tools

Generated TMX files integrate directly with:

**memoQ**:
- Import as translation memory
- Apply in real-time during translation
- Leverage for quality assurance

**Trados Studio**:
- Add to project TM
- Use for fuzzy matching
- Integration with terminology database

**CafeTran Espresso**:
- Load as project memory
- Auto-substitution features
- Terminology management

**OmegaT**:
- Import as project TM
- Real-time matching
- Open-source compatibility

---

## AI Provider Settings

Supervertaler supports multiple AI providers, each with different models and capabilities optimised for various translation scenarios.

### OpenAI Integration

#### Available Models

**GPT-5** 🔥 *Latest Reasoning Model*
- **Advanced Capabilities**: Logical analysis and reasoning
- **Token Limit**: Up to 50,000 tokens for large documents
- **Strengths**: Complex content, technical documentation, nuanced translation
- **Special Features**: Automatic reasoning effort optimization
- **Best For**: Patent documents, legal texts, complex technical content
- **v2.4.1+**: Full automatic parameter handling

**GPT-4o**
- **Multimodal**: Text and image processing
- **Token Limit**: 128,000 tokens
- **Strengths**: Visual context integration, balanced performance
- **Best For**: Documents with figures, charts, diagrams

**GPT-4**
- **Reliable**: Consistent baseline performance
- **Token Limit**: 32,000 tokens
- **Strengths**: General-purpose translation, stable output
- **Best For**: Standard translation work, consistent results

**GPT-4-turbo**
- **Enhanced**: Improved context handling
- **Token Limit**: 128,000 tokens
- **Strengths**: Large document processing, cost efficiency
- **Best For**: Long documents, batch processing

#### GPT-5 Special Considerations (v2.4.1+)

**Automatic Parameter Handling**:
- Uses `max_completion_tokens` instead of `max_tokens`
- Temperature parameter automatically handled
- Reasoning effort set to "low" for optimal output

**Token Management**:
- Dynamic allocation based on content size
- Accounts for reasoning token overhead
- Minimum 32,000 tokens, up to 50,000 for large jobs

**Output Processing**:
- Automatic cleanup of formatting quirks
- Removes double numbering artifacts
- Ensures clean, professional output

### Claude Integration

#### Available Models

**Claude-3.5-Sonnet**
- **Creative Excellence**: Superior cultural adaptation
- **Context**: 200,000 tokens
- **Strengths**: Literary translation, marketing content, cultural nuance
- **Best For**: Creative content, transcreation, cultural adaptation

**Claude-3-Haiku**
- **Speed**: Fast processing for simpler content
- **Context**: 200,000 tokens
- **Strengths**: Efficiency, cost-effective, quick turnaround
- **Best For**: Simple translations, batch processing, time-sensitive work

#### Claude Advantages
- **Cultural Sensitivity**: Excellent cross-cultural adaptation
- **Creative Content**: Superior for marketing and creative materials
- **Safety**: Built-in content filtering and ethical guidelines
- **Context Handling**: Excellent long-document processing

### Gemini Integration

#### Available Models

**Gemini-2.5-Pro**
- **Technical Excellence**: Strong analytical capabilities
- **Context**: 1,000,000+ tokens
- **Strengths**: Technical documentation, analytical content
- **Best For**: Technical manuals, scientific papers, data analysis

**Gemini-1.5-Flash**
- **Speed**: Rapid processing capabilities
- **Context**: 1,000,000+ tokens
- **Strengths**: Efficiency, cost-effective, high throughput
- **Best For**: Large volume processing, simple content

#### Gemini Advantages
- **Massive Context**: Exceptional long-document handling
- **Technical Accuracy**: Strong performance on technical content
- **Cost Efficiency**: Competitive pricing for large volumes
- **Speed**: Fast processing for time-sensitive projects

### Model Selection Guidelines

#### Content-Based Selection

**Complex Technical Content**:
- **First Choice**: GPT-5 (reasoning capabilities)
- **Alternative**: Gemini-2.5-Pro (technical accuracy)

**Creative/Marketing Content**:
- **First Choice**: Claude-3.5-Sonnet (cultural adaptation)
- **Alternative**: GPT-4o (balanced creativity)

**Legal/Patent Documents**:
- **First Choice**: GPT-5 (precision and reasoning)
- **Alternative**: Claude-3.5-Sonnet (formal register)

**Large Volume/Batch Work**:
- **First Choice**: Gemini-1.5-Flash (efficiency)
- **Alternative**: Claude-3-Haiku (speed)

**Visual Content (Figures/Charts)**:
- **First Choice**: GPT-4o (multimodal)
- **Alternative**: Gemini-2.5-Pro (analytical)

### Model Management Controls

#### 🔄 Refresh Models Button

**Primary Function**: Updates the model dropdown menu with current available models

**What It Does**:
- ✅ Updates model dropdown for selected provider
- ✅ Sets appropriate default model
- ✅ Quick operation with minimal logging
- ✅ Essential for UI maintenance

**When to Use**:
- Model dropdown appears empty or outdated
- After switching between AI providers
- When you want latest Gemini models
- UI appears unresponsive
- After updating API keys

#### 📋 List Models Button

**Primary Function**: Displays comprehensive model information in the log panel

**What It Does**:
- ✅ Shows detailed model information
- ✅ Provides model descriptions and capabilities
- ✅ Functions as diagnostic tool
- ✅ Verbose logging with details

**When to Use**:
- Research available models and capabilities
- Determine multimodal support
- Troubleshoot API connectivity
- Copy exact model names
- Evaluate models for specific use cases

---

## Troubleshooting

### Common Issues and Solutions

#### API and Connection Issues

**"API Key not found" or "Invalid API Key"**
- **Check**: `api_keys.txt` file exists and has correct format
- **Verify**: API key is valid and active
- **Test**: Use "List Models" button to verify connection
- **Solution**: Copy working API key from provider dashboard

**"Model not available" or "Model access denied"**
- **GPT-5 Access**: Ensure you have access through OpenAI
- **Claude Access**: Verify Anthropic API access level
- **Gemini Access**: Check Google AI Studio permissions
- **Solution**: Contact provider for model access or use alternative

**Connection timeout or network errors**
- **Network**: Verify internet connection stability
- **Firewall**: Check corporate firewall settings
- **VPN**: Try with/without VPN connection
- **Solution**: Use "Refresh Models" to test connection

#### File and Path Issues

**"File not found" or "Path does not exist"**
- **Absolute Paths**: Ensure file paths are complete and absolute
- **File Existence**: Verify all input files exist at specified locations
- **Permissions**: Check read permissions on input files
- **Solution**: Use "Browse" buttons to select files correctly

**"Unicode decode error" or "Encoding issues"**
- **File Encoding**: Save text files as UTF-8
- **Special Characters**: Ensure proper character encoding
- **BOM**: Remove Byte Order Mark if present
- **Solution**: Re-save files as UTF-8 without BOM

**Cross-platform path issues (Windows/Mac/Linux)**
- **Path Separators**: Use forward slashes (/) for compatibility
- **Drive Letters**: Windows drive letters may not work on other systems
- **Solution**: Use relative paths or Project Library for portability

#### Translation and Processing Issues

**GPT-5 returns empty translations**
- **Token Limit**: Automatic allocation should handle this (v2.4.1+)
- **Content Length**: Try reducing chunk size for very long segments
- **API Limits**: Check OpenAI usage limits and quotas
- **Solution**: Use smaller chunks or alternative model

**Double numbering in output (e.g., "1. 1. Text")**
- **GPT-5 Issue**: Fixed in v2.4.1 with automatic cleanup
- **Other Models**: Check system prompt configuration
- **Solution**: Update to v2.4.1 or manually clean output

**Inconsistent terminology across chunks**
- **Context**: Ensure Translation Memory is loaded
- **Instructions**: Add terminology guidelines to Custom Instructions
- **Chunk Size**: Reduce chunk size for better consistency
- **Solution**: Use tracked changes to learn terminology preferences

**AI refuses to translate certain content**
- **Content Policy**: Check for content that may violate AI policies
- **Language Support**: Verify source/target language combination
- **Model Limitations**: Try different AI provider/model
- **Solution**: Modify content or use alternative provider

#### Memory and Performance Issues

**"Out of memory" or application crashes**
- **Large Files**: Process in smaller chunks
- **System RAM**: Close other applications to free memory
- **Python Memory**: Restart application periodically for large jobs
- **Solution**: Increase chunk size or process files separately

**Slow processing speeds**
- **Network**: Check internet connection speed
- **API Limits**: Some providers have rate limits
- **Chunk Size**: Optimise chunk size for provider
- **Solution**: Adjust chunk size or use faster model variant

**GUI freezing or unresponsive**
- **Background Processing**: Translation runs in background thread
- **Large Jobs**: Very large files may take time
- **System Resources**: Check CPU and memory usage
- **Solution**: Wait for completion or restart if necessary

### Getting Help

**Information to Provide**:
1. Supervertaler version number (v2.4.1 or v2.5.0)
2. Operating system (Windows/Mac/Linux)
3. Python version
4. AI provider and model used
5. Error message from log
6. Session report (if generated)
7. Input file sample (if not confidential)

**Common Resolution Steps**:
1. Update to latest Supervertaler version
2. Verify API key validity
3. Test with different AI provider/model
4. Check file encoding and format
5. Try smaller chunk size
6. Review session report for details

---

## Advanced Tips

### Bulk Operations Guide (v3.3.0-beta)

**New in v3.3.0-beta**: Comprehensive bulk editing tools for managing large projects efficiently.

#### Accessing Bulk Operations

All bulk operations are in: **Edit → Bulk Operations**

#### Select All Segments (Ctrl+A)

- Selects all visible segments (respects current filter)
- Shows count and available operations
- Foundation for multi-selection features

**Use Cases**:
- Quick overview of project size
- Identify segments affected by bulk operations
- Combined with filters for targeted selection

#### Clear All Targets

**Purpose**: Remove all target translations at once

**Workflow**:
```
Edit → Bulk Operations → Clear All Targets...
[Confirmation dialog shows count]
Click "Yes" → All targets cleared
```

**When to Use**:
- Starting fresh translation after major source changes
- Clearing MT output before AI translation
- Resetting project for re-translation
- Testing workflows without losing source text

**⚠️ Warning**: This action cannot be undone! Save project first.

#### Change Status (All/Filtered)

**Two Options**:
1. **Change Status (All)** - Affects entire project
2. **Change Status (Filtered)** - Affects only visible segments

**Available Statuses**:
- Untranslated
- Translated
- Approved
- Draft

**Workflow Example** - Mark filtered segments as approved:
```
1. Set filter: Status = "Translated"
2. Edit → Bulk Operations → Change Status (Filtered)...
3. Select "Approved"
4. Click "Apply"
→ Only translated segments change to approved
```

**Use Cases**:
- Mark batch of AI translations as "Draft" for review
- Approve all segments after QA review
- Reset status after major revisions
- Mark filtered segments (e.g., all table cells) with specific status

#### Lock/Unlock Segments

**What is Locking?**
- **Locked segments** are marked as "final" and protected from accidental edits
- Lock status saved in project file
- Useful for reviewed/approved content

**Four Options**:
1. **Lock All Segments** - Lock entire project
2. **Unlock All Segments** - Unlock entire project
3. **Lock Filtered Segments** - Lock only visible segments
4. **Unlock Filtered Segments** - Unlock only visible segments

**Workflow Example** - Lock approved segments:
```
1. Set filter: Status = "Approved"
2. Edit → Bulk Operations → Lock Filtered Segments
→ Only approved segments are locked
```

**Lock Current Segment**:
- **Edit → Segment → Lock Current Segment**
- Quick way to lock single segment
- Useful during review workflow

**Use Cases**:
- Lock approved segments to prevent accidental changes
- Lock client-reviewed content
- Lock glossary entries or boilerplate text
- Unlock batch for revision after client feedback

**🔒 Pro Tip**: Combine filters with lock operations:
```
Filter: Source contains "Copyright"
→ Lock Filtered Segments
→ All copyright notices locked
```

#### Combining Filters with Bulk Operations

**Powerful Workflow**: Filter → Bulk Operation

**Example 1** - Clear targets in table cells:
```
1. Set filter: Source contains "Table"
2. Edit → Bulk Operations → Clear All Targets
→ Only table segments cleared
```

**Example 2** - Mark all headings as translated:
```
1. Set filter: Status = "Draft"
2. Set filter: Target contains text
3. Edit → Bulk Operations → Change Status (Filtered)
4. Select "Translated"
→ All drafted segments marked as translated
```

**Example 3** - Lock client-reviewed segments:
```
1. Set filter: Status = "Approved"
2. Edit → Bulk Operations → Lock Filtered Segments
→ Client-approved content protected
```

#### Keyboard Shortcuts

| Action | Shortcut |
|--------|----------|
| Select All Segments | `Ctrl+A` |
| Find/Replace | `Ctrl+F` |
| Apply Filters | `Ctrl+Shift+A` |
| Toggle Filter Mode | `Ctrl+M` |

---

### Workflow Optimization

#### Project Setup Strategies

**Client-Specific Configurations**:
Create dedicated project configurations for each client with:
- Language pair and preferred models
- Client-specific Translation Memory
- Custom instructions with style guidelines
- Tracked changes from previous work
- Domain-specific prompts

**Content-Type Templates**:
- **Legal Documents**: Formal prompts, legal TM, conservative models
- **Marketing Materials**: Creative prompts, cultural adaptation focus
- **Technical Manuals**: Safety-focused prompts, technical terminology
- **Medical Content**: Regulatory compliance, medical terminology

#### Batch Processing Strategies

**Sequential Processing**:
For related documents:
1. Load comprehensive TM with all previous translations
2. Process documents in logical order
3. Add each output TMX to master TM database
4. Use accumulated knowledge for subsequent documents

**Parallel Processing**:
For independent documents:
- Process simultaneously using different AI providers
- Compare results for quality assurance
- Identify best-performing provider for content type

### Quality Assurance Techniques

#### Multi-Provider Validation

**Critical Content Double-Check**:
1. Primary translation: GPT-5 (reasoning capability)
2. Secondary validation: Claude-3.5-Sonnet (creative accuracy)
3. Compare outputs for consistency
4. Highlight discrepancies for human review

#### Context Optimization

**Layered Context Strategy**:
1. **Base Layer**: Domain-specific Translation Memory
2. **Enhancement Layer**: Project-specific Custom Instructions
3. **Learning Layer**: Tracked Changes from Previous Work
4. **Visual Layer**: Document Images and Figures
5. **Prompt Layer**: Domain-Specific System Prompts

### Professional Integration

#### CAT Tool Ecosystem

**memoQ Integration Workflow**:
1. **Pre-translation**: Export segments for Supervertaler processing
2. **AI Translation**: Process with optimal context and prompts
3. **TMX Integration**: Import generated TMX into project
4. **Quality Layer**: Use exact matches, review fuzzy matches
5. **Post-editing**: Refine with memoQ's built-in tools

**Trados Studio Integration**:
1. **Project Setup**: Configure with Supervertaler TMX
2. **Batch Processing**: Process multiple files with consistent settings
3. **Terminology Integration**: Combine with existing termbases
4. **Quality Assurance**: Leverage Trados QA with AI translations

---

*This comprehensive user guide covers all aspects of Supervertaler v2.4.1 and v2.5.0. For additional support or advanced enterprise features, please contact the development team or visit the GitHub repository.*

**Repository**: https://github.com/michaelbeijer/Supervertaler  
**Documentation**: See `docs/` folder for technical guides  
**Support**: GitHub Issues for bug reports and feature requests
