Supervertaler - AI Agent Documentation

Supervertaler - AI Agent Documentation

This is the single source of truth for AI coding assistants working on this project. Last Updated: February 1, 2026 | Version: v1.9.191

⚡ QUICK START FOR AI AGENTS

IMPORTANT: If you're continuing from a previous session or ran out of context:

1. Skip to the end of this file - The most recent development context is in the "🔄 Recent Development History" section (search for the latest date)
2. Current version: v1.9.191 - UI improvements (status icons, button padding, font sizes)
3. Read only what you need - The Project Overview and Architecture sections are reference material; the dated history entries contain the actual working context

Quick Navigation:

• Latest context: See CHANGELOG.md for v1.9.191 UI improvements (near end of file)
• Module list: Search for ## 🔌 Complete Module List
• Architecture: Search for ## 🏗️ Architecture Patterns
• Common pitfalls: Search for ## ⚠️ Common Pitfalls

🎯 Project Overview

Supervertaler is a professional desktop translation application built with Python and PyQt6. It serves as a companion tool for translators, integrating AI-powered translation with traditional CAT (Computer-Assisted Translation) tool workflows.

Key Capabilities

• Multi-LLM AI Translation: OpenAI GPT-4, Anthropic Claude, Google Gemini, Local Ollama
• CAT Tool Integration: Trados SDLPPX/SDLRPX, memoQ XLIFF, Phrase/Memsource DOCX, CafeTran DOCX, Déjà Vu X3 RTF
• Translation Memory: Fuzzy matching TM with TMX import/export + Supermemory (ChromaDB vector search)
• Terminology Management: SQLite-based termbases with priority highlighting and automatic extraction
• Document Handling: DOCX, bilingual DOCX, PDF (via OCR), simple TXT, Markdown (MD), Multi-file folder import
• Quality Assurance: Spellcheck, tag validation, consistency checking
• Superlookup: Unified concordance hub with TM, Termbase, Supermemory, MT, and Web Resources
• Batteries Included: Default install includes all major features and dependencies, except heavy optional components (Supermemory + offline Local Whisper)

📦 Installation (Simplified)

Supervertaler uses a batteries-included core install: pip install supervertaler pulls in everything needed for the major features, while keeping heavy optional components out of the default install.

Note: Offline dictation via Local Whisper is optional because it pulls in very large dependencies (PyTorch). The default/recommended voice path uses the OpenAI Whisper API.

Legacy note: older “extras” (e.g. supervertaler[all]) are still accepted for backward compatibility, but they no longer change what gets installed.

Installation Options

Feature Modules

Settings → Features Tab

Users can enable/disable features in Settings → 📦 Features.

Feature Manager Module

The modules/feature_manager.py provides:

• FeatureManager class for checking feature availability
• FEATURE_MODULES dict defining all optional features
• lazy_import_*() functions for conditional imports
• check_feature(id) quick availability check

🪟 Windows EXE Releases (CORE + FULL)

Supervertaler Windows releases are published as two separate ZIP assets on the same GitHub Release:

1. CORE (recommended for most users)

• Smaller download
• Does not bundle the heavy ML stack (Supermemory + offline Local Whisper)

2. FULL ("batteries included")

• Larger download
• Bundles Supermemory + offline Local Whisper (PyTorch / sentence-transformers / ChromaDB)

Key Rule (PyInstaller one-folder builds)

The EXE must be run from the extracted distribution folder. Do not separate Supervertaler.exe from _internal/.

If users see an error like missing python312.dll, they are almost always:

• running the wrong EXE (from an intermediate build folder), or
• moving the EXE away from _internal/.

How to Build (recommended)

Use the automated build script:

# Build BOTH core + full and create both ZIP assets
powershell -NoProfile -ExecutionPolicy Bypass -File .\build_windows_release.ps1

# Build only core
powershell -NoProfile -ExecutionPolicy Bypass -File .\build_windows_release.ps1 -CoreOnly

# Build only full
powershell -NoProfile -ExecutionPolicy Bypass -File .\build_windows_release.ps1 -FullOnly

# Clean build venvs + rebuild (keeps dist/ so multi-flavor builds can coexist)
powershell -NoProfile -ExecutionPolicy Bypass -File .\build_windows_release.ps1 -Clean

What it does:

• Uses two isolated build environments: .venv-build-core and .venv-build-full
• Runs PyInstaller with the corresponding spec:
  • Supervertaler.core.spec → dist\Supervertaler-core\...
  • Supervertaler.full.spec → dist\Supervertaler-full\...
• Zips each output using create_release_zip.py and writes a README_FIRST.txt into each dist folder.

Output Files

After a successful run, you should have:

• dist\Supervertaler-v<version>-Windows-CORE.zip
• dist\Supervertaler-v<version>-Windows-FULL.zip

GitHub Release Posting

Attach both ZIP files to the same GitHub Release tag.

VS Code Tasks

There are build tasks wired up in .vscode/tasks.json:

• "Build Windows EXE (core)"
• "Build Windows EXE (full)"
• "Build Windows EXE (core + full)"

📁 Project Structure

Supervertaler/
├── Supervertaler.py          # Main application (~38,000+ lines)
├── modules/                   # 60+ specialized modules
│   ├── feature_manager.py    # Modular feature management (NEW)
│   ├── llm_clients.py        # OpenAI, Anthropic, Google Gemini, Ollama
│   ├── translation_memory.py # TM matching and storage
│   ├── termbase_manager.py   # Terminology management
│   ├── docx_handler.py       # DOCX import/export
│   ├── sdlppx_handler.py     # Trados Studio packages
│   ├── phrase_docx_handler.py# Phrase/Memsource bilingual
│   ├── cafetran_docx_handler.py # CafeTran bilingual
│   ├── supermemory.py        # Vector-indexed semantic TM (ChromaDB)
│   ├── spellcheck_manager.py # Spellcheck with pyspellchecker/Hunspell
│   ├── prompt_library.py     # AI prompt management
│   └── ...                   # See module list below
├── user_data/                 # User content (gitignored)
│   ├── prompts/              # .svprompt files
│   ├── termbases/            # .db termbase files
│   ├── translation_memories/ # .db TM files
│   ├── dictionaries/         # Custom spellcheck words
│   └── supermemory/          # ChromaDB vector database
├── assets/                    # Icons, images
├── docs/                      # Documentation site
├── beijerterm/                # 🔗 GIT SUBMODULE - Beijerterm glossary website
├── tests/                     # Test files
└── legacy_versions/           # Historical Tkinter version

🔗 Beijerterm Website Submodule (IMPORTANT FOR AI AGENTS)

The beijerterm/ folder is a Git submodule - a separate repository embedded inside Supervertaler.

What is a Submodule?

• It's a pointer to a specific commit in another repository
• Regular git clone does NOT download submodule contents (saves ~15 MB)
• The submodule has its own .git and tracks michaelbeijer/beijerterm separately

Two Separate Projects

Note: The "Superlookup" name refers to the in-app lookup panel inside Supervertaler - don't confuse it with the Beijerterm website!

Working with the Submodule

To make changes to Beijerterm website:

cd beijerterm/
# Edit files...
git add .
git commit -m "your message"
git push origin main          # Pushes to michaelbeijer/beijerterm

Then update the parent reference:

cd ..                          # Back to Supervertaler root
git add beijerterm             # Stage the new submodule commit pointer
git commit -m "chore: Update beijerterm submodule"
git push origin main           # Pushes to michaelbeijer/Supervertaler

⚠️ Common Pitfalls

1. Commits in submodule aren't automatically tracked - After committing inside beijerterm/, you must also commit in the parent repo to update the pointer.

2. Changelogs are separate - Beijerterm website changes go in beijerterm/CHANGELOG.md, Supervertaler changes go in CHANGELOG.md at root.

3. Features in the wrong repo - The "Superlookup" panel inside Supervertaler.py is part of Supervertaler, not the Beijerterm website. Don't confuse them!

4. Building the website - Run python scripts/build_site.py from inside beijerterm/, not from root.

🔧 Key Technical Details

Main Application (Supervertaler.py)

The main file is a large monolithic PyQt6 application. Key sections:

Key Classes

@dataclass
class Project:
    segments: List[Segment]
    source_lang: str
    target_lang: str
    original_docx_path: Optional[str] = None
    memoq_source_path: Optional[str] = None
    sdlppx_source_path: Optional[str] = None
    phrase_source_path: Optional[str] = None
    original_txt_path: Optional[str] = None
    # ... 20+ fields total

@dataclass
class Segment:
    source: str
    target: str = ""
    status: str = "Not Started"
    notes: str = ""
    segment_type: str = "text"
    # ... additional fields

File Extensions

🔌 Complete Module List

AI & LLM (modules/)

• llm_clients.py - OpenAI, Anthropic Claude, Google Gemini, Ollama integration
• model_version_checker.py - Auto-detect new LLM models from providers
• model_update_dialog.py - UI for selecting new models
• prompt_library.py - Prompt management and favorites
• prompt_assistant.py - AI-powered prompt generation
• unified_prompt_library.py - Unified prompt system
• unified_prompt_manager_qt.py - Prompt manager UI
• voice_dictation.py - Whisper-based voice input
• voice_commands.py - Talon-style voice command system (NEW)
• ai_actions.py - AI action system for prompt library
• ai_attachment_manager.py - File attachment persistence
• ai_file_viewer_dialog.py - File viewing dialog

Translation Memory & Terminology

• translation_memory.py - Fuzzy matching TM system
• supermemory.py - ChromaDB vector semantic search (2100+ lines)
• termbase_manager.py - SQLite-based terminology
• term_extractor.py - Automatic term extraction
• termbase_entry_editor.py - Term editing UI
• termbase_import_export.py - TMX/TBX import/export
• tm_manager_qt.py - TM management UI
• tm_metadata_manager.py - TM metadata handling
• tm_editor_dialog.py - TM editing dialog
• tmx_editor.py / tmx_editor_qt.py - TMX file editing
• tmx_generator.py - TMX file generation

File Handlers

• docx_handler.py - Standard DOCX import/export
• sdlppx_handler.py - Trados Studio SDLPPX/SDLRPX packages (767+ lines)
• phrase_docx_handler.py - Phrase/Memsource bilingual DOCX
• cafetran_docx_handler.py - CafeTran bilingual DOCX
• trados_docx_handler.py - Trados bilingual review DOCX
• dejavurtf_handler.py - Déjà Vu X3 bilingual RTF (NEW in v1.9.91)
• mqxliff_handler.py - memoQ XLIFF files
• simple_segmenter.py - Text segmentation

Spellcheck & QA

• spellcheck_manager.py - Dual-backend spellcheck (pyspellchecker + Hunspell)
• non_translatables_manager.py - Non-translatable term management
• tag_cleaner.py - CAT tool tag removal
• tag_manager.py - Tag handling

UI Components

• ribbon_widget.py - Ribbon-style toolbar
• translation_results_panel.py - Match display panel
• termview_widget.py - Inline term display
• superlookup.py - Unified lookup window
• superbrowser.py - Multi-chat AI browser
• quick_access_sidebar.py - Quick access panel
• keyboard_shortcuts_widget.py - Shortcut management
• project_home_panel.py - Project home UI

Utilities

• database_manager.py - SQLite database operations
• database_migrations.py - Database schema migrations
• config_manager.py - Settings management
• file_dialog_helper.py - File dialog utilities
• find_replace.py - Find and replace functionality
• shortcut_manager.py - Keyboard shortcut handling
• theme_manager.py - UI theme management
• statuses.py - Segment status definitions

Specialized Tools

• pdf_rescue_Qt.py - AI OCR for PDF extraction
• image_extractor.py - Extract images from DOCX
• figure_context_manager.py - Image context for AI
• document_analyzer.py - Document analysis
• encoding_repair.py / encoding_repair_Qt.py - Fix encoding issues
• autofingers_engine.py - memoQ AutoFingers automation
• tracked_changes.py - Track changes analysis
• supercleaner.py / supercleaner_ui.py - Text cleaning

Benchmarking

• llm_leaderboard.py - LLM quality benchmarking
• superbench_ui.py - Benchmark UI
• local_llm_setup.py - Ollama setup wizard

🏗️ Architecture Patterns

UI Pattern

• PyQt6 with custom styled widgets
• Consistent styling:
  • Checkboxes: CheckmarkCheckBox (Standard), PinkCheckmarkCheckBox (Project), BlueCheckmarkCheckBox (Global)
  • Radio Buttons: CheckmarkRadioButton (Standard Green)
• Tag-based text formatting (<b>, <i>, <u>, <li-o>, <li-b>)
• Grid-based segment editor with source (read-only) and target (editable) columns

Data Flow

1. Import file → Parse to segments → Display in grid
2. User translates/edits → Status updates → Grid refreshes
3. Export → Reconstruct original format with translations

Settings Storage

• user_data/general_settings.json - App preferences
• user_data/ui_preferences.json - Window geometry, button states
• .svproj files - Per-project settings

📝 Development Guidelines

When Editing Supervertaler.py

1. The file is large (~32K lines) - use line ranges when reading
2. Search for method names with grep_search before editing
3. Follow existing patterns for new features
4. Update __version__ at the top when making changes

When Adding New Modules

1. Create in modules/ directory
2. Add import in main file where needed
3. Follow existing module patterns (docstrings, type hints)

Documentation Updates

Always update these files after changes:

1. AGENTS.md - Add dated entry to development history
2. CHANGELOG.md - Add version entry
3. README.md - Update version badge if needed

Commit Messages

Use semantic prefixes:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• refactor: - Code restructuring
• style: - Formatting

⚠️ Common Pitfalls

1. ElementTree namespaces - Always use namespace dict when working with SDLXLIFF:

   NAMESPACES = {'sdl': 'http://sdl.com/FileTypes/SdlXliff/1.0'}
   element.find('.//sdl:seg', NAMESPACES)
   

2. Grid widget access - Use table.cellWidget() for QTextEdit, table.item() for QTableWidgetItem

3. File paths - Store absolute paths, use os.path.exists() before accessing

4. Status updates - Remember to update both internal data and grid display

5. Signal blocking - When setting text programmatically, use blockSignals(True/False) to prevent cascading events

6. Qt event queue - Be aware that setPlainText() queues events even when signals are blocked

7. Hidden widget styling - Qt may not apply stylesheets to hidden widgets. If theme colors aren't appearing, apply styles when the widget becomes visible, not just at creation time

8. Race conditions & timing - When debugging UI issues, consider whether the problem might be timing-related:

   • Widgets created before theme manager is initialized
   • Styles applied while widgets are hidden
   • Signals firing before handlers are connected
   • Use QTimer.singleShot() for deferred initialization when needed

📋 Planned Features & Refactoring

🔧 Configuration File Consolidation (PRIORITY - Scheduled)

Identified: January 9, 2026
Status: Documented, not yet implemented
Complexity: Medium (30-40 file edits + migration script)

Current Problem: Configuration File Sprawl

Settings are currently scattered across multiple JSON files in user_data/:

• general_settings.json - General application preferences
• ui_preferences.json - Window geometry, button states (DEPRECATED, migrated to general_settings.json)
• themes.json - Theme definitions
• recent_projects.json - Recent project list
• feature_settings.json - Optional feature toggles
• find_replace_history.json - Find & Replace history
• superlookup_history.json - Superlookup search history
• voice_commands.json - Voice command library
• Plus module-specific configs...

Issues:

1. Scattered settings - Hard to find where a setting is stored
2. Code complexity - Multiple file read/write operations throughout codebase
3. Inconsistent structure - Each file has different patterns (nested vs flat, etc.)
4. Migration headaches - Changing structure requires updating multiple files
5. User confusion - Manual editing requires knowing which file to look in
6. Backup/restore complexity - Must backup multiple files to preserve all settings

Proposed Solution: Single config.json

Consolidate all settings into one well-structured file:

{
  "config_version": "1.0.0",
  "general": {
    "restore_last_project": false,
    "auto_propagate_exact_matches": true,
    "auto_center_active_segment": true,
    "auto_insert_100_percent_matches": true,
    "auto_confirm_100_percent_matches": false,
    "tm_save_mode": "latest",
    "enable_smart_word_selection": true,
    "enable_auto_backup": true,
    "backup_interval_minutes": 5
  },
  "ui": {
    "theme": "light",
    "window_geometry": {
      "x": 100,
      "y": 100,
      "width": 1200,
      "height": 800
    },
    "fonts": {
      "grid_family": "Segoe UI",
      "grid_size": 11,
      "results_match_size": 9,
      "results_compare_size": 9,
      "termview_family": "Segoe UI",
      "termview_size": 10,
      "termview_bold": false
    },
    "colors": {
      "tag_color": "#7f0001",
      "focus_border_color": "#2196F3",
      "focus_border_thickness": 2,
      "badge_text_color": "#333333",
      "invisible_char_color": "#999999",
      "even_row_color": "#FFFFFF",
      "odd_row_color": "#F0F0F0"
    },
    "layout": {
      "tabs_above_grid": false,
      "enable_alternating_row_colors": true,
      "show_invisibles": false
    }
  },
  "features": {
    "supermemory_enabled": true,
    "supermemory_auto_init": false,
    "voice_enabled": false,
    "web_browser_enabled": true,
    "pdf_rescue_enabled": true,
    "autofingers_enabled": false
  },
  "match_limits": {
    "LLM": 3,
    "MT": 5,
    "TM": 10,
    "Termbases": 10
  },
  "termbase": {
    "enable_grid_highlighting": true,
    "highlight_style": "semibold",
    "display_order": "appearance",
    "hide_shorter_matches": false,
    "dotted_color": "#808080"
  },
  "precision_scroll": {
    "divisor": 3
  },
  "recent_projects": [
    "/path/to/project1.svproj",
    "/path/to/project2.svproj",
    "/path/to/project3.svproj"
  ],
  "custom_themes": [
    {
      "name": "Dark Blue",
      "is_dark": true,
      "colors": {
        "background": "#1e1e1e",
        "foreground": "#d4d4d4",
        ...
      }
    }
  ],
  "history": {
    "find_replace": [
      {"find": "example", "replace": "sample"}
    ],
    "superlookup_searches": [
      "translation memory",
      "terminology"
    ]
  },
  "voice_commands": {
    "enabled": false,
    "recognition_engine": "openai_whisper",
    "custom_commands": [
      {
        "phrase": "next segment",
        "aliases": ["go next", "move forward"],
        "action_type": "internal",
        "action": "next_segment"
      }
    ]
  },
  "ollama": {
    "keepwarm": false
  },
  "autohotkey": {
    "path": "C:\\Program Files\\AutoHotkey\\v2\\AutoHotkey64.exe"
  }
}

Benefits:

• ✅ Single source of truth - All settings in one place
• ✅ Clear hierarchy - Logical grouping by functionality
• ✅ Easy to read/edit - Clear structure for manual editing
• ✅ Atomic saves - All settings updated together (no partial updates)
• ✅ Simple backup/restore - One file to backup
• ✅ Version tracking - config_version field for migrations
• ✅ Better defaults - Easy to see all default values at once

Implementation Plan:

1. Create modules/config_manager_v2.py (new unified config manager):

   • ConfigManager class with section accessors
   • get(section, key, default) method
   • set(section, key, value) method
   • save() method (atomic write)
   • load() method with validation

2. Migration script (scripts/migrate_config.py):

   • Read all existing JSON files
   • Map to new structure
   • Write config.json
   • Backup old files to user_data/config_backup/
   • Run automatically on first startup after update

3. Update all load/save calls (~30-40 locations):

   • Replace _load_general_settings_from_file() → config_manager.get('general', key)
   • Replace save_general_settings() → config_manager.set('general', key, value) + config_manager.save()
   • Update theme manager
   • Update recent projects
   • Update find/replace history
   • Update voice command loader

4. Backward compatibility:

   • Keep old loaders as fallback for 1-2 versions
   • Log migration warnings
   • Auto-migrate on first run

5. Testing checklist:

   • Fresh install (no config files)
   • Migration from old files
   • Settings persist correctly
   • All features still work
   • No performance regression

Files to modify:

• Supervertaler.py - Replace all config load/save calls
• modules/config_manager_v2.py - NEW unified config manager
• modules/theme_manager.py - Use new config manager
• modules/voice_commands.py - Use new config manager
• modules/find_replace_qt.py - Use new config manager
• scripts/migrate_config.py - NEW migration script

Estimated effort: 3-4 hours (careful testing needed)

Priority: High (improves maintainability significantly)

� Future Investigation: TMX Tag Export Format

Issue discovered December 22, 2025: Our TMX Editor stores formatting tags (like <b>, <i>) as escaped text (<b>) in the <seg> element. This is valid XML but may not be the optimal approach.

Three approaches exist:

What other tools do:

• memoQ: Uses TMX inline elements (<bpt>, <ept>) for proper tag preservation
• Trados Studio: Similar, uses inline elements with type attributes
• OmegaT: Generally uses escaped text for simplicity
• Many web tools: Just escape everything

Recommendation for future: Consider implementing proper TMX inline elements (<bpt>, <ept>, <ph>) when exporting. This would:

1. Maintain compatibility with professional CAT tools
2. Preserve tag type information (bold, italic, etc.)
3. Allow round-tripping without tag loss

Files to modify: modules/tmx_editor.py - TmxParser.save_file() method

�💡 Problem-Solving Tips for AI Agents

When stuck on a difficult bug, consider these approaches:

1. Think about timing: Is this a race condition? Are things happening in the wrong order?

   • Widget creation vs. theme application timing
   • Signal connections vs. signal emissions
   • Hidden vs. visible widget state changes

2. Think outside the box: The obvious solution may not work

   • If stylesheets aren't applying, try QPalette as an alternative
   • If a method isn't being called, check if the widget is even visible
   • If changes aren't reflected, check if there's caching involved

3. Add debug output: When behavior is mysterious, add logging to trace execution flow

   • Print method entry/exit with timestamps
   • Log parameter values and state
   • Write to a debug file if console output is too fast

4. Question assumptions: What do you THINK is happening vs. what is ACTUALLY happening?

   • The code might be running but not having the expected effect
   • A different code path might be executing
   • Something else might be overriding your changes

🧪 Testing

Running Tests

pytest tests/

Manual Testing Checklist

• Import DOCX, translate segment, export
• Save/load .svproj project
• TM matching works
• Termbase highlighting works
• AI translation (if API keys configured)
• Spellcheck toggles correctly
• SDLPPX import/export round-trip

🔑 API Keys

Unified Loading System with Persistent Storage:

API keys are stored in the persistent user data location (see Installation section).

User Data Locations (v1.9.148+):

Note: Users can choose their own data folder location on first run or via Settings → General → Data Folder Location.

For Developers (running from source):

• Store keys in: user_data_private/api_keys.txt
• This location is fully gitignored and will never be uploaded to GitHub
• All features (translation, AI Assistant, tests) will find keys here

For End Users (pip install):

• On first run, choose where to store your data (default: ~/Supervertaler/)
• Store API keys in: [your-data-folder]/api_keys.txt
• The app prints the exact path on startup: [Data Paths] User data: ...
• Keys persist across pip upgrades!

For Windows EXE Users:

• Same as pip users - choose your data folder on first run
• Default is visible in your home folder: C:\Users\Username\Supervertaler\

Format:

openai=sk-...
claude=sk-ant-...
google=AI...
gemini=AI...
deepl=...

Note: google= and gemini= are aliases - both work identically (v1.9.146+).

Implementation Details:

• Supervertaler.py: load_api_keys() method reads from user_data_path
• Automatic normalization: if google is set, gemini is also populated (and vice versa)
• All API key loading now unified through main app's method

🔄 Recent Development History

February 1, 2026 - Dark Mode Refinements & UI Improvements

✨ Feature Summary

Improved dark mode text visibility and fixed TM navigation arrows that were invisible or rendering incorrectly across light and dark themes.

Status: Implementation complete, version 1.9.184 released

Files Modified:

1. Supervertaler.py - Multiple UI improvements:

   • TermView source text color: Changed to #FFFFFF in dark mode for better contrast (lines 175, 456)
   • HTML tag colors: Light pink (#FFB6C1) in dark mode for <b>, </b> tags (lines 1403-1413, 2733-2743)
   • Navigation arrows: Implemented ClickableArrow class with Unicode symbols (◀ ▶) and theme-aware colors (lines 29674-29733)
   • Table header font: Reduced from font_size + 1 to font_size for better proportions (line 30834)
   • Theme refresh: Added arrow color updates in refresh_theme_colors() (lines 43993-43999)

2. modules/unified_prompt_manager_qt.py - Fixed Issue #112:

   • Prompt edits now immediately reflected in Prompt Library and Preview Combined
   • Cache refresh for both active primary and attached prompts (lines 2377-2384)

3. build_windows_release.ps1 - Added Start Menu shortcut scripts to release packages (lines 111-116)

4. create_release_zip.py - Added shortcut creation instructions to README (lines 28-31)

Key Code Locations:

ClickableArrow Class (Supervertaler.py:29684-29705):

class ClickableArrow(QLabel):
    clicked = pyqtSignal()

    def __init__(self, arrow_symbol, parent=None):
        self.arrow_symbol = arrow_symbol
        super().__init__("", parent)
        self.setCursor(Qt.CursorShape.PointingHandCursor)

    def set_color(self, color):
        """Update arrow color for current theme"""
        self.setStyleSheet(f"""
            QLabel {{
                color: {color};
                background: transparent;
                border: none;
                font-size: 11px;
                font-weight: bold;
            }}
        """)
        self.setText(self.arrow_symbol)

Theme Color Logic:

• Dark mode: White arrows (#FFFFFF), light pink tags (#FFB6C1)
• Light mode: Dark gray arrows (#333333), standard tag colors

Development Notes:

• Initially tried PNG arrow images but they rendered fuzzy
• Attempted Unicode angle brackets (❮ ❯) but font support was inconsistent
• Final solution: Unicode triangle symbols (◀ ▶) render crisply on all systems
• Arrow visibility issues were caused by arrows being created at startup before theme was applied
• Solution: ClickableArrow class with set_color() method called during theme refresh

PowerShell Scripts Created:

• create_start_menu_shortcut.ps1 - For end users (Supervertaler.exe)
• create_dev_start_menu_shortcut.ps1 - For developers (run.cmd)

Related Issues:

• Fixed #112: Prompt editing bug where saved prompts weren't updating in UI

January 30-31, 2026 - Total Recall Architecture & Build System Unification

✨ Feature Summary

Implemented CafeTran-inspired "Total Recall" architecture for instant grid navigation. Instead of querying giant TMs on every segment click, relevant segments are extracted into lightweight in-memory structures on project load.

Status: Implementation complete, ready for testing

Files Created:

1. modules/project_tm.py - In-memory TM for instant lookups
2. modules/extract_tm.py - Persistent TM extraction to .svtm files

Files Modified:

1. Supervertaler.py (~938 lines changed)
2. modules/database_manager.py - Reduced candidate limit
3. build_windows_release.ps1 - Unified build system

Implementation 1: In-Memory Termbase Index (Quick Win)

On project load, builds a Python dict mapping lowercase_word -> [term_info, ...] for O(1) termbase lookups.

Key code locations in Supervertaler.py:

• self.termbase_index initialization: ~line 6243
• _build_termbase_index(): ~line 22502
• _search_termbase_index(): ~line 22645
• Integration (called on project load): ~line 22265

Implementation 2: ProjectTM - In-Memory TM

File: modules/project_tm.py

On project load, extracts relevant TM segments (fuzzy matches ≥75%) into an in-memory SQLite database with FTS5 for fast fuzzy search.

Features:

• ProjectTM class with in-memory SQLite + FTS5
• extract_from_database() - extracts segments matching project content
• search() - instant lookup (exact match first, then FTS5 fuzzy)
• Thread-safe with locking

Integration in Supervertaler.py:

• self.project_tm initialization: ~line 6250
• Progress signal: _project_tm_progress_signal at ~line 6128
• Background extraction: _start_project_tm_extraction_background() at ~line 7553
• UI indicator in status bar: self.project_tm_indicator at ~line 7439

Implementation 3: ExtractTM - Persistent TM Extraction

File: modules/extract_tm.py

Extracts relevant segments from selected TMs into a .svtm file (SQLite) that persists across sessions.

Features:

• ExtractTM class with persistent SQLite storage
• extract_and_save() - extracts and saves to file
• load() - loads existing extraction
• search() - fast lookup with FTS5
• export_to_tmx() - export to standard TMX format
• File saved as {ProjectName}_Extract.svtm next to project

Integration in Supervertaler.py:

• Menu action: Bulk → Extract from TMs...
• Dialog: show_extract_tm_dialog() at ~line 33840

Implementation 4: Database Manager Optimization

File: modules/database_manager.py

Reduced TM candidate limit from 500 to 100 (~line 1016):

# Before
candidate_limit = max(500, max_results * 50)

# After
candidate_limit = max(100, max_results * 10)

Implementation 5: Unified Build System

File: build_windows_release.ps1

Removed CORE/FULL split, now uses single unified Supervertaler.spec:

# New usage
.\build_windows_release.ps1           # Build release
.\build_windows_release.ps1 -Clean    # Clean build

# Output
dist\Supervertaler-v{version}-Windows.zip

Expected Performance Improvements

Testing Checklist

• Open project with TMs - see ProjectTM extraction progress indicator
• Grid navigation feels faster after extraction
• Termbase matches appear instantly
• Bulk → Extract from TMs... dialog works
• .svtm file created next to project
• Build script: .\build_windows_release.ps1

Bug Fix (January 31, 2026)

Fixed attribute name mismatch: segment classes use source_text, but ProjectTM/ExtractTM were looking for source. Changed to try both:

source = getattr(seg, 'source', None) or getattr(seg, 'source_text', None)

Git Status (Uncommitted)

M Supervertaler.py
M build_windows_release.ps1
M modules/database_manager.py
?? modules/extract_tm.py
?? modules/project_tm.py

Related Documentation

• Design doc: CLAUDE_SESSION_HANDOFF.md - original architecture design

January 30, 2026 - Global UI Font Scale Feature (v1.9.180)

✨ Feature Summary

A user-configurable setting (50%-200%) that scales the entire application UI. Particularly useful for Linux/macOS users where Qt applications may render with smaller fonts, or for high-DPI displays.

Files Modified:

1. modules/theme_manager.py
2. Supervertaler.py
3. CHANGELOG.md
4. FAQ.md

Implementation Details:

Step 1: ThemeManager (modules/theme_manager.py)

In __init__ method, added after self.custom_themes:

# Global UI font scale (50-200%, default 100%)
self.font_scale: int = 100

In apply_theme method, added at the beginning (after getting theme = self.current_theme):

# Calculate scaled font sizes based on font_scale (default 100%)
base_font_size = int(10 * self.font_scale / 100)  # Base: 10pt at 100%
small_font_size = max(7, int(9 * self.font_scale / 100))  # Small text (status bar)

# Font scaling rules (only applied if scale != 100%)
font_rules = ""
if self.font_scale != 100:
    font_rules = f"""
    /* Global font scaling ({self.font_scale}%) */
    QWidget {{ font-size: {base_font_size}pt; }}
    QMenuBar {{ font-size: {base_font_size}pt; }}
    # ... (all Qt widget types)
    """

Then prepended font_rules to the stylesheet: stylesheet = font_rules + f"""...

Step 2: Supervertaler.py

• Replaced "Settings Panel Font Size" UI (~line 17721) in _create_view_settings_tab() with "Global UI Font Scale"
• Changed SpinBox range from 80-200 to 50-200
• Updated setting key from settings_ui_font_scale to global_ui_font_scale
• Replaced _apply_settings_ui_font_scale() with _apply_global_ui_font_scale():

  def _apply_global_ui_font_scale(self, scale_percent: int):
      """Apply font scale to the entire application UI"""
      general_settings = self.load_general_settings()
      general_settings['global_ui_font_scale'] = scale_percent
      # Remove old key if present (migration)
      if 'settings_ui_font_scale' in general_settings:
          del general_settings['settings_ui_font_scale']
      self.save_general_settings(general_settings)
  
      # Update ThemeManager and reapply theme
      if hasattr(self, 'theme_manager') and self.theme_manager is not None:
          self.theme_manager.font_scale = scale_percent
          self.theme_manager.apply_theme(QApplication.instance())
  
      # Update status bar and main tabs fonts
      self._update_status_bar_fonts(scale_percent)
      self._update_main_tabs_fonts(scale_percent)
      self.log(f"✓ Global UI font scale set to {scale_percent}%")
  

• Added helper methods: _update_status_bar_fonts(), _update_main_tabs_fonts(), _get_global_ui_font_scale()
• Applied font scale at startup after self.theme_manager = ThemeManager(...):

  saved_font_scale = self._get_global_ui_font_scale()
  self.theme_manager.font_scale = saved_font_scale
  

Settings Storage:

• Key: global_ui_font_scale (replaces settings_ui_font_scale)
• File: general_settings.json
• Default: 100
• Range: 50-200

January 28, 2026 - Fresh Projects Start Clean (v1.9.172)

🐛 Bug Fix: TM/Glossary Deactivation on Project Load

Fixed bug where TMs and glossaries remained activated from previous sessions when loading or creating new projects. Users expected a clean slate but saw resources from previous work.

Root Cause: In load_project(), TM deactivation only ran if the project had saved activated_tm_ids in its tm_settings. For older projects or newly created projects without tm_settings, deactivation was skipped entirely.

Fix: Now follows the same pattern as glossaries:

1. Always deactivate all TMs for the project first (start clean)
2. Then restore saved TM activations if they exist in the project file
3. *Always

…(truncated)