Supervertaler Workbench: Docs for the standalone Workbench app only # Supervertaler Workbench Welcome to the help center for 🖥️ **Supervertaler Workbench** – a free, open-source translation application built by translators, for translators.  **Supervertaler Workbench** integrates AI-powered translation with traditional CAT tool workflows. It runs on Windows, macOS, and Linux. * **Translate with AI** – GPT-4, Claude, Gemini, or local models via Ollama * **Work with CAT tools** – import/export files from memoQ, Trados, Phrase, CafeTran * **Translation Memory** – fuzzy matching, TMX import, concordance search * **Terminology** – termbases, automatic term highlighting, TermLens * **Companion tabs** – Chat (AI conversation), SuperLookup, Clipboard manager, Voice * **Voice** – always-on voice commands and push-to-talk dictation for any application * **SuperLookup** – system-wide translation lookup (TM, termbase, MT, web) * **QuickTrans Popup** – always-on-top popup with simultaneous translations from every enabled provider * **Quality Assurance** – spellcheck, tag validation, non-translatables | Requirement | Details | | ----------- | ------------------------------------------------------------------------------------------------------------ | | **OS** | Windows 10/11, macOS, Linux | | **Python** | 3.10 or higher | | **License** | Free and open source (MIT) | | **Source** | [github.com/Supervertaler/Supervertaler-Workbench](https://github.com/Supervertaler/Supervertaler-Workbench) | Start here: [Quick Start Guide](/workbench/get-started/quick-start/) *** ## Supervertaler for Trados Looking for the **Trados Studio plugin**? It has its own help center: [**Supervertaler for Trados Help →**](https://docs.supervertaler.com/trados/) Both tools share the same SQLite-based termbase format (`.db`) – termbases created in one work in the other. *** ## Getting Help * Browse this help center using the sidebar * Report issues on [GitHub](https://github.com/Supervertaler/Supervertaler-Workbench/issues) * Ask in [GitHub Discussions](https://github.com/orgs/Supervertaler/discussions) * Visit [supervertaler.com](https://supervertaler.com) # Autoprompt AutoPrompt uses an LLM to analyse your current project and generate a comprehensive, project-specific translation prompt. The generated prompt embeds the document’s domain, language pair, termbase, confirmed translations, detected source defects, terminology collisions, and preference cascades – ready to use as the **Custom Prompt** for AI translation. ## When to use it AutoPrompt is most useful when: * You are starting a new project and want a strong starting prompt instead of writing one from scratch. * You are translating in an unfamiliar domain and want the LLM to identify the EPO / IFRS / Terminologia Anatomica / domain conventions for you. * You want the prompt to reflect terminology decisions already made elsewhere in the project (confirmed segment translations, attached termbase) without having to retype them. If you already have a hand-tuned prompt that works for your client, you do not need AutoPrompt – just keep using it. ## Launching it 1. Open the **✨ AI** tab. 2. In the **Prompt Manager** sub-tab, find Section 2 (**Custom Prompt**) on the left side of the panel. The right column of that section is labelled “Generate one automatically” and contains a single **✨ AutoPrompt** button. Click it. 3. Supervertaler briefly reads a sample of the document with the AI to detect its context, then an **“AutoPrompt – confirm context”** dialog appears. It shows the detected domain (e.g. *Marketing – creative marketing copy, playful tone*) with: * a **Domain** dropdown you can leave as-is or correct, and * an optional **Context briefing** box where you can type a short note (e.g. “creative copy, playful tone, keep product names untranslated”). Click **Generate** to proceed (this is the normal case — just press Enter), or **Cancel** to abort. Anything you type in the briefing is treated as authoritative and overrides the detected domain where they conflict. 4. A **“Generating AutoPrompt”** progress dialog appears with an indeterminate busy bar. Reasoning-capable models (Opus, GPT-5, etc.) take 1–3 minutes; the rest of Supervertaler stays responsive while you wait. The dialog has a working Cancel button — cancelling stops the response being processed, though it can’t actually abort the HTTP request in-flight on the provider’s side. 5. When generation finishes, a **“Save AutoPrompt”** dialog opens. It shows a read-only preview of the generated content, plus a **Name** field (pre-filled with your project name) and a **Folder** dropdown (defaulting to **Translate** but listing every other top-level folder in your library — editable, so you can type a brand-new folder name and it’ll be created on save). 6. Click **Save** to write the prompt to the library and set it as the **Custom Prompt ⭐** for this project. Click **Cancel** to discard — the generated content stays in the chat log above so you can copy it out manually if you want it as text but not as a file. ## What gets analysed AutoPrompt gathers the following from your project and sends it to your configured AI provider: | Data | Purpose | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Full source document** (up to 50,000 characters) | Context classification, terminology extraction, defect detection, cascade detection, project-context summary | | **All termbase entries** | Locked termbase embedded in the generated prompt | | **Confirmed segment translations** | Used as TM anchors – the highest-authority style and terminology reference, because they are decisions you have already made for this exact document | | **Translation Memory entries** (if attached) | Style anchors – the LLM matches the register and lexical choices of validated TM pairs | | **Language pair** | Embedded in the generated prompt | ## Source-aware pre-generation passes Before the meta-prompt is sent to the LLM, Workbench runs several lightweight passes against the source content and injects the findings into the meta-prompt. The findings tell the LLM what to look for and give it concrete document-specific anchors instead of generic scaffolding. ### Context detection (AI-based) When you click AutoPrompt, Supervertaler sends a sample of the source to the AI and asks it to classify the document into one of: * **Patent** – claims, embodiments, prior art, figures, patent conventions * **Legal** – contracts, clauses, statutory references, notarial titles * **Medical** – clinical terms, dosages, anatomical terminology * **Technical** – specifications, software terms, standards * **Financial** – figures, IFRS / GAAP, regulatory language * **Marketing** – brand, audience, campaign language * **General** – fallback for mixed or unclassified content The AI reads the actual text rather than counting keywords, so classification is reliable across languages and doesn’t get fooled by superficial cues (for example a creative text that happens to mention a “Fig. 1” is no longer mistaken for a patent). The detected domain is shown in the **confirm-context** dialog before generation, where you can override it or add a briefing (see [Launching it](#launching-it) above). ### Terminology-collision detection A built-in helper scans for known cross-term collisions in the source – groups of source-language terms whose natural English candidates would all map to the same target. Currently the helper covers Dutch mechanical / patent vocabulary (the highest-traffic source-language case): the `mantel` / `huls` / `mantelbuis` / `beschermhuls` cluster, the `pijp` / `buis` / `flexibele buis` cluster, the `voorzijde` / `voorvlak` / `achterzijde` distinction, and the `as` (axle vs geometrical axis) homograph. Each detected collision is presented with the EPO-conventional resolution so the LLM-generated prompt locks the correct mapping rather than picking arbitrarily. For any other source language or any other domain, the meta-prompt instructs the LLM to **perform its own collision scan** using patterns appropriate to the actual source language and detected domain – with explicit examples for medical (`arteria vs vena`, ligament vs tendon), legal (`agreement vs contract vs covenant`, liability vs responsibility), and financial (`revenue vs turnover vs sales`) collisions. The LLM-driven scan works for every language pair Workbench supports. ### Defect-detection pass A built-in helper extracts up to five verbatim defect examples from the source – hanging mid-sentence breaks ending in subordinating conjunctions, doubled spaces, plausible verb-ending typos (Dutch `-d` / `-t` confusion), and broken-compound double-space patterns. The Dutch-specific conjunction list catches the highest-traffic case; for other languages the meta-prompt instructs the LLM to perform the scan itself using equivalents in the actual source language (`weil` in German, `parce que` in French, `porque` in Spanish, `perché` in Italian, etc.). Quoting real defects in the generated prompt is far more effective than abstract “preserve defects faithfully” rules – the translator AI sees the actual surface forms it will encounter, not hypothetical examples. ### Preference-cascade extraction A built-in helper extracts up to three real `bij voorkeur ... bij nog meer voorkeur` cascades from Dutch sources (and `preferably ... more preferably ... even more preferably` from English). For other languages the meta-prompt instructs the LLM to look for source-language equivalents – `vorzugsweise / besonders bevorzugt` in German, `de préférence / plus préférablement` in French, `preferiblemente / más preferiblemente` in Spanish, `preferibilmente / più preferibilmente` in Italian, and `preferencialmente / mais preferencialmente` in Portuguese. Quoting one real cascade from the source anchors the generated prompt’s anti-truncation rule in a concrete example: “preserve THIS pattern, here is one from your own document”. ### TM-anchor wiring Confirmed source → target pairs from the project’s own segments are surfaced as TM anchors of the highest authority – they are locked decisions for this exact document. Pairs from any separately-attached `.tm` file are added with lower priority. If neither source has any pairs, the generated prompt’s “Previous Correct Translations” section is omitted entirely (rather than padded with “No TM data available”, which used to give the false impression that AutoPrompt had not even looked). ### Legal-entity scaffolding gate If the source contains no legal-entity markers (BV, NV, GmbH, Ltd., Meester, notaris, etc.), the generated prompt omits the BV/NV/Meester legal-entity-handling and statutory-reference sections. They are noise for a mechanical patent body where no entity names appear in running text, and they used to waste prompt-token budget that could have been spent on real document-specific anchors. ## Output format Generated prompts are formatted as proper Markdown – `##` headings for each major section, `-` bullet lists, `**bold**` for emphasised terms, a Markdown table for the project-specific termbase, and `---` horizontal rules between major sections. Open one in Obsidian, VS Code, GitHub, or any Markdown-aware viewer and it renders cleanly with a navigable outline. The Markdown markup is structural – it does not change what the translator AI does at translation time. The generated prompt’s inner OUTPUT FORMAT rule still says “translation only, no markdown formatting in the translation output”, so per-segment AI translations remain plain target text. ## Translator’s Comment methodology (always-on) Since v1.10.46, every AutoPrompt-generated prompt embeds the **Translator’s Comment** (TC) methodology by default, regardless of source language or domain. The methodology asks the translator AI to silently correct obvious mechanical defects in the source (typos, broken words, hanging mid-sentence breaks, doubled spaces, stray punctuation, reference-numeral mismatches that are unambiguous in context, missing diacritics, etc.) and append a single concise comment at the end of the segment in this exact format: ```plaintext ⟦TC: short factual description of the fix(es)⟧ ``` * The brackets are the mathematical white square brackets **U+27E6** (⟦) and **U+27E7** (⟧). These characters do not occur in source documents, so they are safe as out-of-band markers that can be extracted reliably in post-processing. * One marker per segment maximum; multiple fixes are joined with semicolons inside one marker. * Segments with no defects emit no marker. * When the translator AI inserts a word or short phrase to fill a clear gap, that supplied text is wrapped in standard ASCII square brackets `[like this]` inside the running translation, and the trailing marker references it (e.g. `⟦TC: [bracketed text] supplied to close hanging sentence⟧`). * Numerical values, dates, dosages, legal scope language, headings, identifiers, and proper names are never silently “corrected” – defects in those zones are preserved verbatim, with an optional `⟦TC: source ambiguous – ...⟧` marker if doubt exists. The defect categories that count as “obvious” are adapted to the actual source language by the LLM (Dutch -d/-t verb typos, German missing umlauts, French accent slips, Spanish/Italian conjugation typos, etc.). Caution **Want a generated prompt without the TC methodology?** Edit the generated prompt after creation and remove the TRANSLATOR COMMENT FORMAT section plus any TRANSLATION MANDATE language about silent correction. A per-project opt-out via a UI toggle may be added in a future version – open an issue if you’d like to see it. ## Reviewing and refining the result The generated prompt appears in the prompt library tree and is loaded into the **Prompt Editor** automatically. You can: * **Read through the prompt** to verify it matches your project’s actual needs. * **Edit any section** directly in the editor – the generated prompt is just a regular `.md` file in your prompt library. * **Use AutoPrompt as a starting point** – the goal is to give you a high-quality first draft, not the final word. Adjust termbase entries, add client-specific quirks, tighten the register guidance. * **Re-run AutoPrompt later** if the project grows (more confirmed segments, more termbase entries) – each run is independent, so a later run produces a fresh prompt that reflects the project’s current state. ## Tips and limitations * **AutoPrompt cost scales with document size.** For very large projects (hundreds of thousands of words) the per-run cost can become significant. Consider running AutoPrompt against a representative subset rather than the full project for very large jobs. * **Termbase quality matters.** If you have an attached termbase that contains generic technical words (“system”, “board”, “installation”) that match almost any document, AutoPrompt will include those entries in the locked termbase and force the AI to follow them. Disable irrelevant termbases before running AutoPrompt. * **AutoPrompt does not guess.** If a pre-generation pass finds nothing in the source (no collisions for this domain / language combination, no defects, no cascades), the corresponding section is omitted from the generated prompt rather than padded with hypothetical examples. Hypothetical examples are worse than nothing. * **AutoPrompt and Supervertaler for Trados share the same prompt library folder.** A prompt generated in Workbench is immediately visible in the Trados plugin and vice versa. * **Vision-aware AutoPrompt is opt-in (since v1.10.178).** By default, AutoPrompt sends a text-only meta-prompt — figure *references* in the source are counted but the actual image files are not transmitted. Tick the **“🖼️ Include loaded figure images”** checkbox under the **✨ AutoPrompt** button in Section 2 to ship the figure images loaded in Section 4 alongside the meta-prompt. The LLM can then visually ground its terminology decisions — labelled parts, reference numerals, captions, visible components — directly into the generated terminology table. Three pre-flight gates apply: images must already be loaded in Section 4, the active model must support vision (Claude Sonnet/Opus 4.x, GPT-4o or newer, Gemini), and a confirmation dialog shows the estimated extra cost before the request goes out. Typical extra spend: roughly $0.05–$0.30 for 10–20 figures with a Sonnet-class model, or $0.25–$1.50 with Opus. For a high-value project (patent, technical spec), this is usually a worthwhile trade for a noticeably better-anchored generated prompt. ## See also * [Prompt Manager](/workbench/ai-translation/prompt-library/) – manage and organise generated prompts * [Creating Prompts](/workbench/ai-translation/prompts/) – write prompts from scratch * [AI Translation Overview](/workbench/ai-translation/overview/) – how the Custom Prompt is used during translation # AutoTagger AutoTagger looks at where the inline tags sit in the **source** segment and inserts that same set of tags into your **existing translation** at the right places – without changing any of the translated words. It is for the common case where a target has the correct translation but is **missing its tags or has them in the wrong spots** – typically after machine translation, pasting from another tool, or typing the target by hand. Those segments otherwise trip tag-validation checks even though the wording is fine. ## How it works 1. AutoTagger strips whatever tags are currently in the target. 2. It asks the AI to re-place the **full set of tags from the source** at the correct positions in your translation. 3. It **validates** the result before writing it: the tag set must match the source, the words must be unchanged, and the tags must be well-formed. 4. If the AI’s output doesn’t validate, it **retries once**. If it still fails, AutoTagger leaves the target **untouched** – so it never writes broken tags. Because the words are preserved exactly, AutoTagger is safe to run on a translation you have already reviewed. ## Running it on a single segment Run AutoTagger on the active segment one of three ways: * Click the **🏷️ AutoTagger** button on the editor toolbar. * Choose **Translate → 🏷️ Auto-tag Current Segment**. * Press **Ctrl+Alt+G**. Undo (`Ctrl+Z`) reverts it. ## Running it on many segments Use **Bulk Operations → 🏷️ Auto-tag Segments** to re-tag segments that are **already translated**. It runs over the selected segments (or all segments if none are selected) and the whole run is a single Undo. > **Note:** Ordinary AI translation (single-segment or Batch Translate) already places inline tags as part of the translation, so you do **not** need to run AutoTagger after translating. AutoTagger is for fixing tags on text that was translated some **other** way (MT, paste, hand-typed). The older “Fix tags with AutoTagger after translating” toggle in the Batch Translate dialog was removed in v1.10.319 for this reason. ## Configuring it Settings → **System Prompts** → **AutoTagger Instruction**. This editable template tells the AI how to place the tags. It supports these placeholders: | Placeholder | Meaning | | ----------------- | ---------------------------------------- | | `{{SOURCE_TEXT}}` | The source segment, with its inline tags | | `{{TARGET_TEXT}}` | Your current translation (tags stripped) | | `{{TAG_LIST}}` | The list of tags that must be placed | ## Tracking cost AutoTagger’s AI calls are logged under their own **“AutoTagger”** task in [Token Usage & Costs](/workbench/ai-translation/usage-costs/) (a bulk pass logs the tag-placement step as AutoTagger). Group the usage table by Task to see them broken out. *** ## See Also * [FuzzyFixer](/workbench/ai-translation/fuzzyfixer/) * [Tag Validation](/workbench/qa/tag-validation/) * [Batch Translation](/workbench/ai-translation/batch-translation/) * [Prompts](/workbench/ai-translation/prompts/) * [Token Usage & Costs](/workbench/ai-translation/usage-costs/) # Batch Translation Translate multiple segments at once with AI. ## Starting Batch Translation 1. **Select segments** to translate: * Click first segment, Shift+click last for a range * Or use **Edit → Select All** (`Ctrl+A`) 2. **Start batch**: * Press `Ctrl+Shift+T` * Or go to **Translate → Batch Translate** ## Batch Dialog Options ### Provider Selection Choose your LLM provider: * OpenAI (GPT-5.5, GPT-5.4 Mini) * Anthropic (Claude Sonnet 4.6, Claude Haiku 4.5, Claude Opus 4.8) * Google (Gemini 3.1 Flash-Lite, Gemini 2.5 Pro, Gemini 3.1 Pro) * Mistral, DeepSeek * Ollama (local models) ### Translation Mode | Mode | Description | | ---------------- | ------------------------------------------- | | **LLM Only** | Use AI for all segments | | **TM First** | Use TM matches above threshold, AI for rest | | **TM + Context** | Include TM matches as context for AI | ### Options * **Skip confirmed segments**: Don’t re-translate ✅ segments * **Include context**: Send surrounding segments for better quality * **Retry until complete**: Auto-retry segments that return empty ## Progress Tracking During translation: * Progress bar shows completion * Per-segment status updates * Can cancel anytime ## Retry Feature Enable **”🔄 Retry until all segments are translated”** to: * Automatically detect empty translations * Retry failed segments (up to 5 passes) * Ensure all segments get translated ## Tips ### Optimal Batch Size * 50-100 segments per batch works well * Very large batches may timeout * Split by page if needed ### Quality vs Speed * Claude Sonnet 4.6: Good all-round balance of speed and quality * GPT-5.5 / Claude Opus 4.8: Highest quality, slower and more expensive * GPT-5.4 Mini / Gemini 3.1 Flash-Lite: Fastest, lower cost ### Post-Edit Strategy After batch translation: 1. Review each segment 2. Fix any obvious errors 3. Confirm with `Ctrl+Enter` *** ## See Also * [AI Translation Overview](/workbench/ai-translation/overview/) * [Creating Prompts](/workbench/ai-translation/prompts/) * [Single Segment Translation](/workbench/ai-translation/single-segment/) # Chat The **💬 Chat** panel is a full AI assistant that supports OpenAI, Claude, Gemini, Ollama, and any OpenAI-compatible custom provider. It’s available in two places: as the **Chat** sub-tab of the **✦ AI** top tab, and as a **💬 Chat** tab in the editor’s right panel so you can keep a conversation visible while you translate. When you have **Supervertaler for Trados** running with its Assistant panel active, Chat automatically picks up the project context from Trados – active segment, surrounding segments, TM matches, termbase hits, project metadata – and answers questions about your real translation work without you having to switch out of Trados. This is especially useful on small laptop screens where there’s not enough room to keep the in-Trados Assistant panel visible alongside the editor. Summon Workbench, click the **💬 Chat** tab, and ask away while Trados stays in front for the actual editing. ## How it works Supervertaler for Trados runs a tiny localhost-only HTTP service called the **Supervertaler Bridge** while the AI Assistant panel is active. (The name is historical – it predates the Sidekick retirement in Workbench v1.10.4 and is kept stable because the Trados-side C# class looks up the bridge by that name.) Workbench’s Chat panel detects the bridge automatically and uses it to fetch the current Trados project state on every message you send. Nothing leaves your computer – the bridge listens only on `127.0.0.1`, requires a per-session authentication token, and is never reachable from outside the machine. ## The 🔗 Trados chip Above the chat input you’ll see a row of context chips (Document, TMs, Termbases, Files). When the Trados plugin is detected, a fifth chip appears: * **Hidden** until the bridge is detected for the first time. Users without the Trados plugin never see this chip. * **Lit green** – bridge is reachable; Trados context is included in chat messages. * **Greyed** – the bridge was previously available but is now unreachable (e.g. you closed Trados mid-session). The chip recovers automatically when Trados restarts. Click the chip to toggle it off if you want to ask a non-Trados-related question without the project context being included. The chip pref is shared across all chat views – toggling it in one place affects every send path. ## What the chat sees When the chip is on, every message you send to Chat is preceded by a context block that contains: | Field | What it is | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Project name and file name** | So the AI knows what document you’re working on | | **Source and target language** | The language pair from Trados, used as a sanity-check against the chat’s reasoning | | **Active segment** | The source segment you’re currently editing in Trados, plus your current target draft (if any) | | **Surrounding segments** | A few segments before and after the active one – gives the AI enough context to know what kind of document this is (legal, technical, marketing, patent…) | | **TM matches** | Fuzzy and exact matches Trados has found for the active segment, with their match percentages and TM names | | **Termbase hits** | Term entries from your enabled termbases that match the active segment, including definitions, domains, and notes | This is the same context the in-Trados Supervertaler Assistant chat already uses, so answer quality is comparable. ## QuickLauncher prompts from Trados When **Supervertaler for Trados** is running, you can also send a Trados QuickLauncher prompt (Ctrl+Q from inside Trados Studio) over the bridge to be processed by Workbench’s Chat panel instead of the in-Trados Assistant. The Trados plugin builds a redacted *display* version (e.g. `[source document — N segments]` instead of the full project text) for the chat transcript and sends the fully-expanded prompt to the LLM. Workbench pops to the foreground on the Chat tab, the prompt and response render there, and the user can carry on the conversation as a normal Chat session. This is opt-in on the Trados side – a dropdown in Trados → **Settings → AI Settings → “QuickLauncher prompts go to:”** picks between the in-Trados Assistant (default) and Workbench Chat. Workbench is always ready to receive; nothing in Workbench needs to be configured. If Workbench isn’t running when Trados tries to send a prompt, Trados silently falls back to its own Assistant – the prompt is never lost. → [Supervertaler Bridge (Trados help)](https://docs.supervertaler.com/trados/ai-assistant/supervertaler-bridge/) – wire format and troubleshooting ## Example questions The Trados-aware chat shines when you ask questions that depend on what you’re actually translating right now: > *Which termbase entries apply to this segment?* The chat will list the termbase hits and explain how to apply them. > *What’s a more natural English translation for the segment I’m currently editing?* The chat will read the source, your draft target (if any), and any surrounding segments, and propose a polished translation. > *Are there any TM matches I should reuse for this segment?* The chat will summarise the TM matches and tell you which ones are close enough to confirm as-is. > *What domain is this document about?* The chat will infer the domain from the surrounding segments and reply. ## Privacy * The bridge listens **only on `127.0.0.1`** (loopback). Other devices on your network can never reach it. * Each Trados session gets a **fresh authentication token** – stale tokens from old sessions are useless. * The bridge **only starts when you have Assistant access** (paid subscription or trial). Without Assistant access, no bridge is started. * You can disable the bridge entirely on the Trados side by editing the plugin’s `settings.json` and setting `"sidekickBridgeEnabled": false`. See [Supervertaler Bridge](/trados/ai-assistant/supervertaler-bridge/) for details. ## Troubleshooting **The 🔗 Trados chip never appears.** The bridge isn’t being detected. Check: 1. Trados Studio is running with **Supervertaler for Trados v4.19.52 or later** 2. You have a paid subscription or active trial (the bridge is gated behind Assistant access) 3. You’ve **opened the Supervertaler Assistant panel** at least once in this Trados session – the bridge starts lazily when the panel is first activated 4. The handshake file `~/Supervertaler/trados/runtime/bridge.json` exists. If it doesn’t, check the bridge log at `%TEMP%\Supervertaler-bridge.log` for diagnostic information. **The chip appears but the answers don’t seem to use the project context.** Send a question that explicitly references your segment, like *“Which termbase entries apply to this segment?”*. If the answer cites specific terms from your termbases, the bridge is working. If the answer is generic, the chip may have been toggled off, or the bridge may have lost reachability – check the chip’s tooltip. **The chip is greyed out.** The bridge was reachable earlier but is no longer responding. Make sure Trados Studio is still running and the Supervertaler Assistant panel hasn’t been closed. The chip recovers automatically (within \~3 seconds) when Trados is reachable again. *** ## Related pages * [AI Translation Overview](/workbench/ai-translation/overview/) * [Supervertaler Bridge (Trados side)](/trados/ai-assistant/supervertaler-bridge/) * [Supervertaler (Trados)](/trados/ai-assistant/) # FuzzyFixer FuzzyFixer adapts an existing fuzzy TM match to the current source segment instead of translating it from scratch. When an 80–95% match is sitting right next to a segment, FuzzyFixer feeds that match into the AI prompt and asks the model to make only the edits the source change requires – keeping the existing wording, terminology, and tags wherever the source is unchanged. This is useful for repetitive, lightly-revised content (updated manuals, contract variants, new product revisions) where translating cold throws away a near-perfect human translation that is already in your TM. > Inspired by a suggestion from David Turnbull. ## Why use it By default the AI never sees a segment’s fuzzy TM match – it translates from the source alone, even when a high match is available. FuzzyFixer closes that gap: the model starts from the TM target and revises it minimally, so the result stays closer to your approved style and terminology than a fresh translation would. ## Running it on a single segment 1. Move to a segment that has a fuzzy match in range (see **Match range** below). 2. Run FuzzyFixer one of three ways: * Click the **🔧 FuzzyFixer** button on the Match Panel’s **TM Source** box (it is enabled only when the shown match is in range). * Choose **Translate → 🔧 Fuzzy Fix Current Segment**. * Press **Ctrl+Alt+F**. After it runs, the **TM Target** box shows a **track-changes view** of what the AI changed: the original TM target with the AI’s insertions underlined and removed words struck through, so you can see the edit at a glance before confirming. ## Using it in batch translation In the **Batch Translate** dialog, tick **🔧 Use FuzzyFixer**. When enabled: * The AI pass runs **per segment** (no batching), so each segment gets its own in-range fuzzy match injected into the prompt. * Segments **without** an in-range match are translated normally. * The toggle is remembered between sessions. Because it disables batching, FuzzyFixer batch mode is slower and costs more per segment than ordinary batch translation – use it on jobs that are genuinely revision-heavy. ## Configuring it ### Match range Settings → **AI Settings** → **🔧 FuzzyFixer**. FuzzyFixer only acts on matches inside a percentage range (default **75%–99%**). 100% exact matches are **never** altered. Lower the floor to catch looser matches, or raise it to limit FuzzyFixer to very close matches only. ### Instruction template Settings → **System Prompts** → **FuzzyFixer Instruction**. This editable template tells the model how aggressively to revise. In addition to the usual `{{SOURCE_TEXT}}`, it supports these placeholders: | Placeholder | Meaning | | ----------------- | ------------------------------------------------------------------ | | `{{TM_SOURCE}}` | The matched TM entry’s source text | | `{{TM_TARGET}}` | The matched TM entry’s target text (the translation being adapted) | | `{{MATCH_PCT}}` | The match percentage | | `{{TM_NAME}}` | The name of the TM the match came from | | `{{SOURCE_TEXT}}` | The current segment’s source text | ## Tracking cost FuzzyFixer’s AI calls are logged under their own **“FuzzyFixer”** task in [Token Usage & Costs](/workbench/ai-translation/usage-costs/). Group the usage table by Task to see them broken out from ordinary translation. *** ## See Also * [Fuzzy Matching](/workbench/translation-memory/fuzzy-matching/) * [AutoTagger](/workbench/ai-translation/autotagger/) * [Batch Translation](/workbench/ai-translation/batch-translation/) * [Prompts](/workbench/ai-translation/prompts/) * [Token Usage & Costs](/workbench/ai-translation/usage-costs/) # Image Context The **Image Context** viewer lets Supervertaler attach figure images to AI translation requests so the model can see the document’s drawings, photos, schematics or labelled parts in addition to the text. When a segment contains `Figure 1`, `Fig. 2A`, `Table 3`, etc., the matching image is shipped with the request so the AI’s translation is anchored in what the figure actually depicts — not just the words around it. The same viewer doubles as Supervertaler’s **DOCX image extractor**: point it at a Word document and it pulls every embedded image out into a numbered folder of PNG files, ready to load straight back as AI context. So the most common flow is one button-press: extract from a DOCX → context is auto-loaded → start translating. ## Where to find it The viewer is folded into the **Prompt Manager** (since v1.10.176; it used to be a standalone AI sub-tab): 1. Switch to the **✨ AI** tab → **Prompt Manager** sub-tab. 2. On the left of the panel, find **Section 4 — Image Context**. 3. Click the green **`Open ▸`** button. The right-hand panel swaps from the Prompt Editor to the Image Context viewer. 4. The viewer’s **`← Back to Prompt Editor`** button (or clicking any prompt in Section 5) returns you to the Prompt Editor. ## Extract images from a DOCX The viewer is a single toolbar at the top, with a results list + image preview below. 1. Add input files to the extraction queue: * **📄 Add DOCX** — pick one DOCX file * **📁 Add Folder** — add every DOCX file in a folder (batch input) 2. Choose an output strategy: * Enable **Auto-folder** to create an `Images` folder next to each DOCX * Or set a single output directory in the **Output directory** field 3. Set **Prefix** (default `Fig.`). 4. Click **🖼️ Extract Images**. 5. The freshly-extracted folder is automatically loaded as AI context for figure-aware translation — no second click required. 6. Use **📂 Extracted Files (click to preview)** below to preview images. ### Filename detection Since v1.10.190, extracted files are named after the **caption visible in the document** rather than sequential `Fig. N.png` numbers. So if your document labels figures as `FIG. 7`, the extracted file is `FIG. 7.png` — matching what the reader sees. The detector recognises the following label vocabularies (case-insensitive): | Pattern | Example filename | | -------------------------- | ----------------------------------- | | `FIG. N` / `FIGS. N` | `FIG. 7.png` (patent figures) | | `Figure N` / `Figs N` | `Figure 7.png` (academic / general) | | `Fig. N` | `Fig. 7.png` | | `Table N` | `Table 3.png` | | `Diagram N` | `Diagram 4.png` | | `Chart N` | `Chart 2.png` | | `Photo N` / `Photograph N` | `Photograph 12.png` | | `Scheme N` (chemistry) | `Scheme 1.png` | | `Plate N` / `Plate IV` | `Plate IV.png` (Roman numerals OK) | | `Exhibit A` (legal) | `Exhibit A.png` | The ID portion accepts `N`, `Na`, `NB` shapes (e.g. `FIG. 6a`, `Table 3B`). Documents that use Word’s built-in **Caption** paragraph style are detected even when no pattern matches — the leading sentence of the caption becomes the filename (capped at 80 chars). Images for which no caption can be detected fall back to the sequential `Fig. N.png` form. ### 🤖 AI label detection (opt-in) For documents that don’t follow the standard label vocabularies — marketing copy, blog posts, cookbooks, photo essays, foreign-language documents — tick **”🤖 AI label”** in the toolbar before clicking Extract Images. Each image that the text-pattern detector couldn’t label is sent to the active vision AI alongside surrounding text from the document, with a request to identify the figure’s label. **Requirements:** * A vision-capable model configured in Settings (Claude Sonnet/Opus 4.x, GPT-4o or newer, Gemini) * Internet connection **Cost:** roughly $0.005–$0.02 per AI-labelled image depending on provider — only spent on images the free text-pattern detector missed. A confirmation dialog showing the estimated extra cost appears before any API call is made; click Cancel to abort or run text-pattern only. **Pre-flight gates** that may interrupt the run: * No chat backend / API keys configured → friendly message, AI step skipped * Active model doesn’t support vision → choose between proceeding text-only or cancelling * Zero images need AI (all already pattern-detected) → silently skipped, no dialog, no cost If the AI replies `unlabelled` for a given image, that image falls back to the sequential `Fig. N.png` form. So the AI step is purely additive — it can only improve filenames, never make them worse. ## Load a pre-existing folder of images If you already have a folder of images ready (e.g. one you extracted in an earlier session, or one you assembled by hand): 1. Click **📁 Load Folder** (the green button, to the right of Extract Images). 2. Pick the folder. 3. The images load into the AI context **and** populate the preview list below — just like a fresh extraction. ## Filename → figure-reference matching Supervertaler infers the figure reference from each image’s filename. Recognised patterns: | Filename example | Matched reference | | ---------------- | ----------------- | | `Figure 1.png` | `1` | | `Fig. 2A.jpg` | `2a` | | `figure3-b.png` | `3b` | | `Fig 10.tif` | `10` | When the AI later sees `Figure 1` or `Fig. 2A` in a segment’s source text, the matching image (case-insensitive, whitespace-/dash-/dot-normalised) is attached to the request. References that don’t match any loaded image are simply ignored — no error, no warning, the segment translates text-only. ## How loaded images reach the AI When AI translation runs (single-segment or batch), Supervertaler scans each segment’s source text for figure references. If a match is found AND a corresponding image file is loaded AND the active model supports vision (Claude Sonnet/Opus 4.x, GPT-4o or newer, Gemini), the image is base64-encoded (or passed as PIL data for Gemini) and attached to the request. Segments without figure references are translated text-only. A line appears in the log for every match, e.g. ```plaintext 🖼️ Detected figure references in segment #42: 1, 2a ✅ Including 2 figure images: 1, 2a ``` If the model is text-only (older GPT, Ollama models without vision, etc.), the figures are silently skipped and a warning goes to the log so you know why visual grounding didn’t fire. ## Using images with AutoPrompt (opt-in) Since v1.10.178, the loaded figures can ALSO be sent to the **AutoPrompt** generator — not just to the per-segment translator. Section 2 of the Prompt Manager has a companion checkbox under the **✨ AutoPrompt** button labelled **“🖼️ Include loaded figure images”**. Tick it before clicking AutoPrompt to ship the loaded figures alongside the meta-prompt. The LLM then uses the drawings to lock terminology decisions directly into the generated translation prompt — *“part 7 in Figure 1 is labelled ‘cylindrical sleeve’ → lock ‘mantelbuis’ → ‘cylindrical sleeve’ in the termbase”* — instead of having to guess from textual references alone. * **Off by default** — opting in is a deliberate per-project choice. * **Adds a small extra cost** — roughly $0.05–$0.30 for 10–20 figures with a Sonnet-class model, more with Opus. Negligible vs. the value of a typical project (a €1000 patent will spend less than 0.1% on visual grounding). * **Cost-confirmation dialog** pops up before the request so you can back out. See [AutoPrompt](/workbench/ai-translation/autoprompt/) for the full flow and pre-flight gates (vision-model check, missing-figures friendly message, etc.). ## Project persistence The currently-loaded folder path is saved into the `.svproj` file, so reopening a project automatically re-loads its image context. If the folder has moved or been deleted, you get a warning in the log and the project opens with no images loaded — re-pick the folder via **Load Folder** to restore. ## See also * [Prompt Manager](/workbench/ai-translation/prompt-library/) — where Section 4 (Image Context) lives * [AutoPrompt](/workbench/ai-translation/autoprompt/) — opt-in to ship figures with the meta-prompt * [AI Translation Overview](/workbench/ai-translation/overview/) — how images flow into per-segment translations # Using Local LLMs (Ollama) Ollama lets you run LLMs locally for privacy and offline translation. ## Install Ollama 1. Download and install from 2. Start Ollama 3. Pull a model (example): ```bash ollama pull llama3 ``` ## Use in Supervertaler Once Ollama is installed and running, Supervertaler can use it as a provider. # Overview Supervertaler integrates with leading AI language models for high-quality translation. ## Supported Providers | Provider | Models | | -------------- | -------------------------------------------------------------------------------- | | **OpenAI** | GPT-5.5, GPT-5.4 Mini | | **Anthropic** | Claude Sonnet 4.6, Claude Haiku 4.5, Claude Opus 4.8 | | **Google** | Gemini 3.1 Flash-Lite, Gemini 2.5 Pro, Gemini 3.1 Pro (Preview), Gemma 4 26B MoE | | **Mistral** | Mistral Large, Mistral Small | | **DeepSeek** | DeepSeek V4 Pro, DeepSeek V4 Flash | | **OpenRouter** | 200+ models via a single API key | | **Ollama** | TranslateGemma, Qwen 3, Aya Expanse (local, free) | | **Custom** | Any OpenAI-compatible endpoint | See [Supported LLM Providers](/workbench/ai-translation/providers/) for setup instructions for each provider. ## Quick Start 1. [Set up API keys](/workbench/get-started/api-keys/) 2. Open a project with segments to translate 3. Select a segment 4. Press `Ctrl+T` to translate ## Translation Methods ### Single Segment Translate one segment at a time: * Select a segment * Press `Ctrl+T` or click **Translate** button * AI translation appears in the target cell * Review, edit, and confirm ### Batch Translation Translate multiple segments at once: * Select segments (Shift+click for range) * Press `Ctrl+Shift+T` or use **Translate → Batch Translate** * Configure options in the dialog * All selected segments are translated ### TM + AI Hybrid Combine Translation Memory with AI: 1. TM matches are checked first 2. High matches (e.g., >90%) are used directly 3. Lower matches are AI-translated with TM context 4. No matches use pure AI translation ## Prompts Prompts control how the AI translates. A good prompt includes: * Translation direction (source → target language) * Domain/subject matter * Style guidelines * Terminology rules * Special instructions ### Example Prompt ```plaintext You are a professional Dutch-to-English translator specializing in technical documentation. Maintain formal register. Use American English spelling. Keep all formatting tags like {1}, , in place. Translate naturally while preserving the original meaning. ``` See [Creating Prompts](/workbench/ai-translation/prompts/) and [Prompt Manager](/workbench/ai-translation/prompt-library/) for more. ## Provider Selection ### In Settings 1. Go to **Settings** tab 2. Find **LLM Settings** 3. Choose your preferred **Provider** and **Model** 4. Save settings ### Per-Translation When batch translating, you can choose the provider in the dialog. ## Quality Tips ### Get Better Results 1. **Use specific prompts** - Include domain, style, and rules 2. **Provide context** - Enable “include context” for surrounding segments 3. **Add termbase terms** - Attach terminology for consistent translations (see [Sending Terms to the AI](/workbench/termbases/ai-injection/)) 4. **Post-edit** - AI is great but not perfect; always review ### Common Issues | Issue | Solution | | ------------------ | ---------------------------------------- | | Wrong terminology | Add terms to termbase, include in prompt | | Inconsistent style | Be more specific in your prompt | | Tags removed/moved | Explicitly tell AI to preserve tags | | Too literal | Ask for “natural, fluent” translation | ## Cost Management ### API costs Cloud providers typically charge by usage (tokens). Pricing and free tiers change over time, so treat each provider dashboard as the source of truth. ### Reducing Costs 1. **Use Ollama** (local) when appropriate 2. **Translate only what you need** (for example not-started segments) 3. **Pre-translate with TM** when you have good matches 4. **Use smaller/faster models** for drafts, larger models for final passes *** ## Learn More | | | | --------------------- | ---------------------------------------------- | | **Single Segment** | [Translate one at a time →](single-segment.md) | | **Batch Translation** | [Translate in bulk →](batch-translation.md) | | **Creating Prompts** | [Write effective prompts →](prompts.md) | | **Local AI (Ollama)** | [Free, private AI →](ollama.md) | # Prompt Manager Supervertaler includes a Prompt Manager so you can create, organise, and reuse prompts across projects. It lives in the **✨ AI** tab → **Prompt Manager** sub-tab.  ## Layout The left side of the Prompt Manager is organised into **five numbered sections**, each with a coloured title strip. Read top to bottom, they are the four context layers that go into every AI request, followed by the library you pick prompts from: | # | Section | What lives there | | - | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **System Prompt** | The built-in instructions for the AI. Auto-selected based on the current mode (Single Segment, Batch DOCX, Batch Bilingual). Click **View System Prompt** to see what it looks like and to jump to **Settings → 📝 System Prompts** if you want to edit it. | | 2 | **Custom Prompt** | Your project-specific instructions, in two columns: the active prompt on the left (with **Load External…** and **Clear**), and the **✨ AutoPrompt** button on the right. Set one from the library below, load an out-of-library file, or have the AI generate one. | | 3 | **Attached Prompts** | Optional extras stacked on top of the Custom Prompt. Right-click any prompt in the library and choose **📎 Attach to Active** to add it here. **Clear All Attachments** removes them all. | | 4 | **Image Context** | Visual references for the AI. Click the green **`Open ▸`** button to swap the right-hand panel from the Prompt Editor to the Image Context viewer, where you can extract images from a DOCX or load a pre-existing folder of figure images. Once loaded, images are sent as binary data alongside your prompt when figure references (Fig. 1, Figure 2A, …) are detected in a segment. The viewer’s **`← Back to Prompt Editor`** button (or simply clicking any prompt in Section 5) returns you to the Prompt Editor. | | 5 | **Prompt Library** | All your saved prompts. The button row below the heading lets you create new entries (**+ New**, **📁 New Folder**), refresh from disk, and collapse / expand every folder. | At the very bottom of the panel sits a single **👁 Preview Combined** button that opens a window showing exactly what will be sent to the AI for the current segment — the System Prompt, your Custom Prompt, every Attached Prompt, plus the segment text itself, all assembled in order. ## Setting the Custom Prompt Three ways to populate Section 2: * **From the library** — right-click any prompt in Section 5 and choose **⭐ Set as Custom Prompt**, or double-click it. The prompt name shows up next to the ⭐ icon in Section 2. * **From an external file** — click **Load External…** in Section 2 and pick any `.md` or `.txt` file from anywhere on your computer. The file stays where it is on disk; Supervertaler just references it. * **Have the AI generate one** — click **✨ AutoPrompt** in Section 2. The AI analyses your current document (domain, tone, terminology, confirmed translations) and produces a tailored prompt. See [AutoPrompt](/workbench/ai-translation/autoprompt/) for details. Whichever way you pick, the choice is saved into the `.svproj` immediately, so it survives a restart. ## Common uses * Maintain different prompts per client * Maintain different prompts per domain * Switch between “draft” and “final” translation styles * Pair a domain-specific Custom Prompt with one or two client-specific Attached Prompts (e.g. a “patents” Custom Prompt plus a “Client X house style” attachment) ## Tips * **Start simple** and evolve prompts as you learn what works for your language pair. * **AutoPrompt is a good starting point** for new projects, especially in unfamiliar domains — use the auto-generated prompt as a draft and edit it from there. * **Preview Combined is honest** — it shows you the actual final prompt that will be sent. If something looks wrong, it’s because something *is* wrong. * **External prompts can be edited in place** — if you load a prompt from an external file, Supervertaler can show it in the editor on the right and save changes back to the same file. ## See also * [AutoPrompt](/workbench/ai-translation/autoprompt/) — auto-generate a tailored translation prompt from the current document * [Creating Prompts](/workbench/ai-translation/prompts/) — what makes a good translation prompt when writing one by hand * [AI Translation Overview](/workbench/ai-translation/overview/) — how the assembled prompt is used during translation # Creating Prompts Prompts control how the AI translates (tone, domain, rules, formatting). ## What makes a good translation prompt * Target audience and tone (formal/informal) * Domain constraints (legal, medical, technical) * Rules for numbers, punctuation, terminology * Instructions to preserve tags and placeholders Caution If your text contains formatting or CAT tool tags, instruct the model to preserve them exactly. ## Quick checklist * Specify the language direction (source → target) * Specify style and audience (formal/informal, US/UK spelling, etc.) * Tell the model what to do with **tags/placeholders** (keep, don’t reorder, don’t delete) * Tell the model what to do with terminology (use termbase terms when provided) ## Next * [Prompt Manager](/workbench/ai-translation/prompt-library/) # Providers Supervertaler supports multiple AI providers so you can choose what fits your workflow and budget. You only need one to get started. ## Cloud providers ### OpenAI Models: **GPT-5.5**, **GPT-5.4 Mini** Get an API key at [platform.openai.com/api-keys](https://platform.openai.com/api-keys). GPT-5.4 Mini is a good starting point – fast, affordable, and high quality for most translation tasks. GPT-5.5 is the flagship for the most demanding work. ### Anthropic (Claude) Models: **Claude Sonnet 4.6**, **Claude Haiku 4.5**, **Claude Opus 4.8** Get an API key at [console.anthropic.com](https://console.anthropic.com). Claude Sonnet 4.6 is the recommended default. Haiku 4.5 is the fastest and cheapest option; Opus 4.8 is the most capable. ### Google (Gemini) Models: **Gemini 3.1 Flash-Lite**, **Gemini 2.5 Pro**, **Gemini 3.1 Pro (Preview)**, **Gemma 4 26B MoE** Get an API key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey). Gemini 3.1 Flash-Lite offers a generous free tier and is a strong choice for high-volume work. ### Mistral AI Models: **Mistral Large**, **Mistral Small** Get an API key at [console.mistral.ai](https://console.mistral.ai). Particularly strong on European languages. ### DeepSeek Models: **DeepSeek V4 Pro**, **DeepSeek V4 Flash** Get an API key at [platform.deepseek.com](https://platform.deepseek.com). DeepSeek offers competitive pricing and strong multilingual quality. V4 Flash is the fast, cost-effective option for high-volume work. ## Gateway providers ### OpenRouter [OpenRouter](https://openrouter.ai) is an API gateway that gives you access to 200+ models from OpenAI, Anthropic, Google, DeepSeek, Mistral, Meta, and many others – all through a **single API key**. The model dropdown includes a curated selection for translation, and you can also type any OpenRouter model ID directly. Browse all models at [openrouter.ai/models](https://openrouter.ai/models). Get an API key at [openrouter.ai/keys](https://openrouter.ai/keys). ## Local providers ### Ollama Run models entirely on your own machine – no API key and no internet required. See [Ollama Setup](/workbench/ai-translation/ollama/) for download and configuration instructions. ## Custom (OpenAI-compatible) For any provider that exposes an OpenAI-compatible API (Azure OpenAI, together.ai, local inference servers, etc.), select **Custom (OpenAI-compatible)** and enter the endpoint URL, model name, and API key. *** ## Related pages * [Setting Up API Keys](/workbench/get-started/api-keys/) * [Ollama Setup](/workbench/ai-translation/ollama/) * [AI Translation Overview](/workbench/ai-translation/overview/) # Single Segment Translation Use single-segment translation when you want maximum control: translate one segment, review, then confirm. ## Typical workflow 1. Select a segment 2. Run **Translate Segment** (shortcut: `Ctrl+T`) 3. Review the result 4. Edit if needed 5. Confirm the segment You can also trigger this from the menu: **Translate → Translate Current Segment**. ## Tips * Single-segment mode is great for tricky sentences and high-stakes text. * Use [SuperLookup](/workbench/superlookup/overview/) for research before confirming. # Token Usage & Costs Supervertaler Workbench keeps a persistent log of the AI tokens and cost of every operation, plus a built-in **Usage & Costs** report to total and export it. Use it to answer *“how much did this project cost?”*, *“how many tokens did we use this month?”*, or *“what should I bill this client for AI?”* — across every provider, including local and custom models. The log uses the **same format as the Supervertaler for Trados plugin**, so if you use both, their logs merge into a single analysis. ### The usage log file Every AI call appends one line to a monthly file: ```plaintext …\Supervertaler\workbench\usage\usage-2026-06.jsonl ``` It is **JSONL** (one JSON object per line) — open it in Excel, or parse it with a script. A line looks like: ```json {"ts":"2026-06-18T16:07:03Z","product":"workbench","task":"BatchTranslate", "provider":"claude","model":"claude-sonnet-4-6","project":"My Patent Job", "file":"","src_lang":"English","tgt_lang":"Dutch","in_regular":654, "in_cache_read":0,"in_cache_write":27843,"out":808,"source":"actual", "cost_usd":0.11849325,"cost_known":true,"duration_s":24.9,"ok":true} ``` It is **on by default**. Turn it off in **Settings → AI Settings → AI Cost Monitoring**. ### The Usage & Costs report Open **Tools → 💰 Token Usage & Costs…**. The window totals your usage and lets you slice it: * **Range** — This month, Last 3 months, This year, or All time. * **Group by** — Project, Client, Model, Provider, Task, Day or Month. Each row shows calls, input/output tokens, cost, and a **% actual** column (the share backed by provider-reported figures rather than estimates). The footer shows the range total and your month-to-date spend against your budget. ### Exporting **Export CSV…** and **Export Excel…** write the detailed ledger (one row per call) for the selected range — ready for invoicing or analysis. ### Settings & budget **Settings → AI Settings → AI Cost Monitoring** has: * **Keep a persistent token-usage log** — the on/off switch. * **Monthly budget (USD)** — a soft monthly limit (cents allowed; `0` disables). Once this month’s logged spend reaches it, starting a batch translation shows a warn-and-continue prompt. It is advisory and **never blocks**. ### Pricing custom / self-hosted models Costs come from a single price list, `pricing.json`, shared with the Trados plugin. To price a custom or self-hosted model — or override any rate for both products at once — copy the bundled `modules/pricing.json` to `…\Supervertaler\pricing.json` and add an entry keyed by the exact model id: ```json { "models": { "my-university-llama": { "input": 0.0, "output": 0.0 } } } ``` Until a rate is set, a custom model’s **tokens are still logged**, with the cost marked unknown rather than guessed. Local models ([Ollama](/workbench/ai-translation/ollama/)) are priced at `0`. ### How accurate are the figures? Every record is flagged **`actual`** or **`estimated`** in its `source` field — and the difference matters. * **`actual`** (the usual case): the token counts are the **exact numbers the provider’s API reported** for that call — the same numbers it bills you against. These are as accurate as it gets. This covers OpenAI, Claude, Gemini, Mistral, DeepSeek and OpenRouter, including the cached-token breakdown. * **`estimated`**: a fallback used only when the provider returned no usage data — currently **local models (Ollama)** and the occasional unparseable response. The estimate is a simple **characters ÷ 4** heuristic. It’s reasonable for English but can be well off for other content: scripts such as Chinese, Japanese, Korean, Arabic and Cyrillic pack a different number of characters per token, so the estimate often *under*-counts them. Ollama is free, so for local models only the token *count* is approximate — there is no cost involved. For **cost**, an `actual` record’s figure is the exact token count × the per-model rate from `pricing.json`, with **cached tokens priced at each provider’s cache discount** (e.g. Claude cache reads at 10% of the input rate and cache writes at 125%, OpenAI cache reads at 50%, Gemini 2.5+/3 at 25%). This matches how the Supervertaler for Trados plugin computes cost, so the two products agree. The one thing that can make it differ slightly from your provider’s bill: * The price list can **lag** a provider’s recent rate change. The model id and the token counts are still exact — only the unit price might be a little behind. For the definitive bill, your **provider’s own usage dashboard** is authoritative. The ledger is built for tracking trends, attributing usage to projects and clients, and capacity planning — where the exact, provider-reported token counts are precisely what you want. ### See also * [Batch Translation](/workbench/ai-translation/batch-translation/) — the main driver of token usage * [Supported LLM Providers](/workbench/ai-translation/providers/) — which providers report usage * [Using Local LLMs (Ollama)](/workbench/ai-translation/ollama/) — free, locally-run models * [General Settings](/workbench/settings/general/) — where AI Cost Monitoring lives # CafeTran Workflow Supervertaler supports CafeTran bilingual table DOCX workflows. ## Export from CafeTran 1. Open your project in CafeTran 2. Go to **Project → Export → Bilingual Table** 3. Choose **DOCX** format ## Import to Supervertaler 1. In Supervertaler: **Project → Import → CafeTran → Bilingual Table (DOCX)…** and select the exported DOCX 2. Translate and review in the grid 3. Confirm segments when ready (`Ctrl+Enter`) ## Export back to CafeTran 1. In Supervertaler: **Project → Export → CafeTran → Bilingual Table - Translated (DOCX)…** 2. Save the file ## Reimport to CafeTran 1. In CafeTran: **Project → Import** and select the bilingual table 2. Choose merge options as needed ## Notes * Preserve pipe-style markers and any CAT tags. * Don’t change the bilingual table structure in Word. # memoQ Workflow This guide covers working with memoQ bilingual files in Supervertaler. ## Export from memoQ ### Bilingual DOCX (Recommended) 1. In memoQ, open your project 2. Go to **Documents** view 3. Right-click your document → **Export Bilingual…** 4. Choose **Bilingual DOC/RTF/DOCX** 5. Select **Table format** (two columns) 6. Export the file ### XLIFF Export 1. In memoQ, go to **Documents** view 2. Right-click → **Export Bilingual…** 3. Choose **memoQ XLIFF bilingual** 4. Save the `.mqxliff` file ## Import to Supervertaler 1. Go to **Project → Import → memoQ → Bilingual Table (DOCX)…** * Or **Project → Import → memoQ → XLIFF (.mqxliff)…** 2. Select your exported file 3. The segments appear in the translation grid ### What Gets Imported * ✅ Source text * ✅ Target text (if any) * ✅ Inline formatting tags (`{1}`, `[2}`, etc.) * ✅ Segment status ### memoQ Tag Handling memoQ uses special tag formats: | Tag Style | Example | Purpose | | --------- | ----------------- | --------------- | | Curly | `{1}` | Inline tag | | Mixed | `[2}` or `{3]` | Start/end tags | | Named | `{MQ}`, `{tspan}` | Formatting tags | These tags are highlighted in dark red in the grid (matching memoQ’s color). ## Translate in Supervertaler 1. Navigate through segments 2. Use AI translation (`Ctrl+T`) or translate manually 3. Confirm each segment (`Ctrl+Enter`) 4. Save your project regularly (`Ctrl+S`) ### Tips for memoQ Projects * **Preserve tags**: Keep all `{1}`, `[2}` tags in your translation * **Use SuperLookup**: Press `Ctrl+K` for TM and termbase searches * **Batch translate**: Select multiple segments and press `Ctrl+Shift+T` ## Export from Supervertaler 1. Go to **Project → Export → memoQ → Bilingual Table - Translated (DOCX)…** 2. Choose a filename 3. The bilingual table is recreated with your translations ## Import Back to memoQ 1. In memoQ, go to **Documents** view 2. Right-click your original document 3. Select **Import/Update Translation…** 4. Choose **From bilingual DOC/RTF/DOCX file** 5. Select the file exported from Supervertaler 6. Click **Import** ### Verify the Import * Check that translations appear in memoQ * Confirm status shows as “Translated” or “Edited” * Run memoQ’s QA to check for issues ## Complete Workflow ```plaintext memoQ: Export Bilingual DOCX ↓ Supervertaler: Import memoQ Bilingual ↓ Supervertaler: Translate (AI + manual) ↓ Supervertaler: Export memoQ Bilingual ↓ memoQ: Import/Update Translation ↓ memoQ: QA + Delivery ``` ## Troubleshooting ### Tags appear as plain text Make sure you exported as **Bilingual DOCX** (not “Export without tags”). ### Formatting lost on re-import This can happen if: * Tags were deleted or modified during translation * The bilingual table structure was changed **Solution**: Always keep tags exactly as they appear. ### Status not updating in memoQ memoQ’s import may not change segment status. You can: * Use memoQ’s filtering to find imported segments * Manually confirm segments in memoQ if needed *** ## See Also * [CAT Tool Overview](/workbench/cat-tools/overview/) * [Voice (commands and dictation in memoQ)](/workbench/voice/overview/) # CAT Tool Integration Overview Supervertaler is designed to work alongside professional CAT (Computer-Assisted Translation) tools, not replace them. Use it as a **companion tool** for AI-powered translation within your existing workflow. ## Supported CAT Tools | CAT Tool | Import Format | Export Format | | ---------------------- | --------------------- | ---------------------- | | **memoQ** | Bilingual DOCX, XLIFF | Bilingual DOCX | | **Trados Studio** | SDLPPX packages | SDLRPX return packages | | **Phrase (Memsource)** | Bilingual DOCX | Bilingual DOCX | | **CafeTran Espresso** | Bilingual table DOCX | Bilingual table DOCX | ## Why Use Supervertaler with CAT Tools? ### AI Translation Power CAT tools have limited AI integration. Supervertaler lets you: * Use multiple LLM providers (GPT-4, Claude, Gemini) * Create custom translation prompts * Batch translate with context awareness ### Workflow Flexibility * Translate offline with Ollama * Work on files while others are locked in the CAT tool * Quick review and post-editing without heavy software ## Typical Workflow ```plaintext ┌─────────────────────────────────────────────────────────────┐ │ YOUR CAT TOOL │ │ (memoQ, Trados, Phrase, CafeTran) │ │ │ │ 1. Receive project from client │ │ 2. Set up TM, termbases in CAT tool │ │ 3. Export bilingual file or package │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ SUPERVERTALER │ │ │ │ 4. Import bilingual file │ │ 5. AI translate + post-edit │ │ 6. Use SuperLookup for research │ │ 7. Export bilingual file │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ YOUR CAT TOOL │ │ │ │ 8. Import translations back │ │ 9. Run QA checks │ │ 10. Deliver to client │ └─────────────────────────────────────────────────────────────┘ ``` ## Key Concepts ### Preserving Formatting Supervertaler preserves CAT tool formatting tags: * memoQ: `{1}`, `[2}`, `{MQ}` inline tags * Trados: `<1>`, `` numbered tags * Tags are highlighted in the grid for visibility ### Segment Status Segment statuses map between tools: * **Draft** → Trados *Draft* / memoQ *Edited* * **Confirmed** → Trados *Translated* ✓ / memoQ *Confirmed* * **Approved** → Trados *Sign-off Approved* / memoQ *Reviewer 2 confirmed* See [Segment Statuses](/workbench/editor/segment-statuses/) for the full reference. ### Round-Trip Compatibility Files exported from Supervertaler can be imported back into the CAT tool with: * All translations preserved * Status information maintained * Formatting intact ## Choosing the Right Workflow | Scenario | Recommended Workflow | | ---------------------------- | ----------------------------------------------------- | | **Full project in memoQ** | [memoQ Bilingual DOCX](/workbench/cat-tools/memoq/) | | **Trados Studio package** | [SDLPPX/SDLRPX](/workbench/cat-tools/trados/) | | **Phrase/Memsource project** | [Phrase Bilingual DOCX](/workbench/cat-tools/phrase/) | | **CafeTran external view** | [CafeTran DOCX](/workbench/cat-tools/cafetran/) | | **Standalone DOCX** | Direct import, no CAT tool needed | *** ## Tool-Specific Guides | | | | ----------------- | ---------------------------------------- | | **memoQ** | [memoQ workflow guide →](memoq.md) | | **Trados Studio** | [Trados workflow guide →](trados.md) | | **Phrase** | [Phrase workflow guide →](phrase.md) | | **CafeTran** | [CafeTran workflow guide →](cafetran.md) | # Phrase (Memsource) Workflow Supervertaler supports Phrase (Memsource) bilingual DOCX round-trips. ## Export from Phrase 1. In Phrase Editor, go to **Document → Export → Bilingual DOCX** 2. Save the file ## Import to Supervertaler 1. In Supervertaler: **Project → Import → Phrase (Memsource) → Bilingual (DOCX)…** and select the bilingual DOCX 2. Translate (AI or manual) and review in the grid 3. Confirm segments when ready (`Ctrl+Enter`) ## Export back to Phrase 1. In Supervertaler: **Project → Export → Phrase (Memsource) → Bilingual - Translated (DOCX)…** 2. Save the file ## Reimport to Phrase Import the bilingual DOCX back into Phrase to update the document. ## Notes * Keep any tags/placeholders exactly as-is. * Don’t change the table structure in Word. Caution Don’t merge or split segments if you plan to reimport. # Trados Studio Workflow This guide covers working with Trados Studio packages in Supervertaler. ## Recommended: SDLPPX Packages The best way to work with Trados Studio is using **project packages** (SDLPPX files). ### Export from Trados 1. In Trados Studio, open your project 2. Go to **Project** → **Package** → **Create Project Package** 3. Configure package options (include all files) 4. Save as `.sdlppx` file ### Import to Supervertaler 1. Go to **Project → Import → Trados Studio → Package (SDLPPX)…** 2. Select your `.sdlppx` file 3. Supervertaler extracts and loads all segments ## Translate in Supervertaler 1. Navigate through segments 2. Use AI translation (`Ctrl+T`) or translate manually 3. Confirm each segment (`Ctrl+Enter`) 4. Tags appear as `<1>`, `` - keep them in your translation ### Trados Tag Format Trados uses numbered XML-style tags: | Tag | Purpose | | ------ | -------------------- | | `<1>` | Opening tag | | `` | Closing tag | | `<2/>` | Standalone/empty tag | These are highlighted in the grid for visibility. ## Export as Return Package 1. Go to **Project → Export → Trados Studio → Return Package (SDLRPX)…** 2. The return package is created with your translations 3. Segment status is updated to “Translated” ## Import Back to Trados 1. In Trados Studio, go to **Project** → **Open Package** 2. Select the `.sdlrpx` file from Supervertaler 3. Trados imports the return package 4. Your translations appear in the target segments *** ## Alternative: Bilingual Review DOCX ⚠️ **Use SDLPPX instead if possible.** The Bilingual Review format has limitations. ### The Problem Trados Bilingual Review DOCX is designed for **review only**, not translation: * Empty target segments are not exported * You cannot translate from scratch using this format ### Workaround (if you must use it) 1. **In Trados**: Copy all source to target first * Edit → Task → Copy source to target (batch task) 2. **Export**: Project → Export → Trados Studio → Bilingual Review - Translated (DOCX) 3. **In Word**: Delete all target text (cells remain, but empty) 4. **Import to Supervertaler**: Project → Import → Trados Studio → Bilingual Review (DOCX) 5. **Translate** and export 6. **Re-import to Trados**: Merge into project Caution This workaround is tedious. Use SDLPPX packages whenever your client provides them. *** ## Complete SDLPPX Workflow ```plaintext Trados: Create Project Package (.sdlppx) ↓ Supervertaler: Import Trados Package ↓ Supervertaler: Translate (AI + manual) ↓ Supervertaler: Export Return Package (.sdlrpx) ↓ Trados: Open Return Package ↓ Trados: QA + Delivery ``` ## Troubleshooting ### ”Cannot find SDLXLIFF files” The SDLPPX might be corrupted or use an unsupported format. * Try re-exporting from Trados Studio * Ensure all files are included in the package ### Status shows “Draft” instead of “Translated” Fixed in **v1.10.259**. Earlier versions exported every segment as **Draft** regardless of its status in the grid, so even a fully-confirmed project arrived unconfirmed in Trados. Now a confirmed project exports with each segment marked **Translated** (Approved/Proofread map to *ApprovedTranslation*). Update to v1.10.259 or later and re-export the return package. ### Tags not matching Ensure you keep all `<1>`, `` tags in exactly the same positions. ### Source files not found on re-export If you moved your project, use **Project → Export → 🔗 Relocate Source Folder** to point to the new location of the SDLPPX. *** ## See Also * [CAT Tool Overview](/workbench/cat-tools/overview/) * [Import/Export Formats](/workbench/import-export/formats/) # Clipboard Manager The Clipboard Manager in Supervertaler Workbench captures everything you copy and keeps a persistent history that survives application restarts. Click any item to paste it; trigger a snippet or text conversion to paste the transformed result back to whichever app you came from. | How | Shortcut | | ------------------------------------------- | ------------------------------------------------------- | | Open Clipboard Manager from any application | **Ctrl+Alt+C** (⌘⌥C on macOS) | | Open Clipboard Manager tab manually | Click **📋 Clipboard Manager** in the Workbench tab bar | When you summon the Clipboard Manager via **Ctrl+Alt+C** from another app (e.g. Trados), Workbench automatically sends Ctrl+C in the source app *before* opening the tab. So you don’t need a separate “copy first” keystroke – the current selection lands at the top of the clipboard history the moment the tab opens.  *** ## Three columns The tab is split into three side-by-side panels: * **📝 Text (left)** – plain text, rich text, and any other text copied from any application * **🖼 Images (middle)** – raster images (screenshots, copied graphics, etc.) * **📑 Menu (right)** – a tree of actions to apply to whatever’s currently on the clipboard: Personal Snippets, Special Characters, Text Conversions, and your QuickLauncher Prompts Each column has its own count in its header (e.g. *Text (37)*, *Images (8)*). A draggable splitter lets you resize the three panels. The column header whose widget currently holds keyboard focus is **highlighted in blue with an underline**, so it’s always obvious which column the arrow keys are steering. *** ## How clips are captured The Clipboard Manager monitors the system clipboard in the background. Every time you copy something in any application – a word in Trados, a URL, a code snippet, a screenshot – it is added to the top of the relevant list automatically. Duplicate copies of identical content are deduplicated (the existing item moves to the top instead of a new entry appearing). **Capacity limits:** | Kind | Maximum items | | ------ | ------------- | | Text | 200 | | Images | 50 | When a list is full, the oldest item is removed to make room. *** ## Pasting a clip Click any item in the Text or Images list to paste it. What happens: 1. The item is placed on the system clipboard. 2. Workbench is hidden to the system tray. 3. `Ctrl+V` is sent to whichever window was active before the Clipboard tab opened. After pasting, the item is marked as used and appears greyed out. This makes it easy to track which clips you have already inserted in a session. ## The Menu column The third column gives you actions to apply to whatever’s on the clipboard. Expand a category by clicking its arrow or pressing **Right** with the category focused. ### 🔄 Refresh button The Menu column header has a small **🔄 Refresh** button on the right. Click it after editing any snippet `.md` file under `/snippet_library/` (rename a snippet, change a snippet body, add a new snippet, delete one) or any QuickLauncher prompt `.md` file in the shared prompt library. Refresh rebuilds the entire Menu tree from disk in one click – before v1.10.47 there was no way to pick up external file edits short of restarting Workbench. Refresh reloads three sources: the unified prompt library (via `UnifiedPromptLibrary.load_all_prompts()`), the snippet library (re-scans `/snippet_library/` with a fresh `SnippetLibrary` instance), and the Text Conversions table (in-code, but rebuilt for symmetry). ### 📌 Personal Snippets Your own text snippets (e.g. phone numbers, email signatures, boilerplate paragraphs). Snippets are loaded from `.md` files inside your user-data folder – see [Personal Snippets](/trados/text-transforms/) for the file format. Activating a snippet (click or Enter) copies its body to the clipboard and pastes it into the source app via the same hide-and-paste flow used for clipboard clips. ### ✨ Special Characters Quick-insert symbols, arrows, primes, dashes, quotes, currency signs, legal symbols, mathematical operators, and bullet characters. Activate one to paste the character into the source app. ### 🔁 Text Conversions Transform whatever text is on the clipboard. The conversions are computed against the *current* clipboard contents – so the typical flow is: select text in another app → **Ctrl+Alt+C** to open the Clipboard Manager (current selection auto-copies) → navigate to a conversion → Enter to paste the converted text back over your selection. #### The shipped defaults Eleven conversions ship out of the box: **Uppercase**, **Lowercase**, **Title Case**, **Sentence case**, **Single curly quotes**, **Double curly quotes**, **Round brackets**, **Square brackets**, **Remove soft hyphens (U+00AD)**, **Double quotes → single quotes**, **Make `bold`**. #### Adding your own Since v1.10.48, every text conversion is a `.md` file under `/text_conversion_library/`. The folder structure on disk is organisational – move files between folders to re-organise; the parent folder name becomes the conversion’s category. Drop a new `.md` file in the right folder, click **🔄 Refresh** on the Menu column, and the new conversion appears. Each file declares one conversion via YAML frontmatter at the top, with an optional human-readable notes section below: ```yaml --- type: wrap label: Mark as translator's comment ⟦TC: …⟧ prefix: " ⟦TC: " suffix: "⟧" --- Optional notes here. Workbench ignores everything below the closing ---. ``` The four supported `type` values cover most needs without arbitrary-code execution: | `type` | What it does | Required fields | Optional fields | | --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `case` | Change case of the whole text | `mode` (one of `upper`, `lower`, `title`, `sentence`, `swap`, `camel`, `snake`, `kebab`) | – | | `wrap` | Glue a prefix and suffix around the text | `prefix`, `suffix` | – | | `regex_replace` | Find/replace, literal or regex | `find`, `replace` | `regex` (default `true`), `case_sensitive` (default `true`) | | `strip_chars` | Remove every occurrence of any listed character | `chars` | – | Common optional metadata: * `label` – the display label shown in the Menu. Defaults to the filename stem if omitted (useful when the label contains characters that can’t be in filenames, like `:` or `"`). * `category` – overrides the folder-derived category. Set to an empty string to surface the conversion at the top level. * `enabled` – defaults to `true`. Set to `false` to hide without deleting (useful for project-specific conversions you might want back later). #### Concrete examples A wrap conversion for HTML emphasis: ```yaml --- type: wrap label: HTML prefix: suffix: --- ``` A strip-chars conversion that removes several invisible characters in one go (uses YAML’s `\u` escape inside double quotes): ```yaml --- type: strip_chars label: Strip invisible spaces (NBSP + figure space + narrow NBSP) chars: " " --- ``` A regex find/replace for em-dash-to-en-dash: ```yaml --- type: regex_replace label: "Em dash (—) → en dash (–)" find: "—" replace: "–" regex: false --- ``` A regex find/replace using capture groups for UK → US “-our” → “-or” endings: ```yaml --- type: regex_replace label: "UK → US: drop the 'u' from -our endings" find: "([Cc]olo|[Ff]avo|[Hh]ono|[Ll]abo|[Nn]eighbo|[Bb]ehavio|[Ff]lavo|[Oo]do|[Rr]umo)u(r)" replace: "\\1\\2" regex: true --- ``` (Note the doubled backslashes in `replace` – `\\1` in YAML is needed to produce `\1` in the actual regex replacement string.) #### Things that DON’T work (and why) The four `type` values are deliberately limited – no arbitrary Python execution from user-data files, no shell commands, no network calls. If you have a transformation that genuinely needs Python (multi-step pipelines that produce intermediate state, calls to an external library, etc.), open a GitHub issue describing the use case and we’ll consider adding a `python_file` type with appropriate safeguards. Broken conversions (invalid `type`, bad regex, missing required field) are silently skipped on load and logged to the Workbench log – the clipboard flow never breaks on a typo. Fix the file, click 🔄 Refresh, and the conversion comes back. ### 💬 QuickLauncher Prompts Your custom AI prompts from the Prompt Manager, grouped by folder. Activating a prompt copies its body to the clipboard. ## Deleting clips **Single item** – right-click any entry in the Text or Images list and choose **🗑 Delete**, or select it and press the **Delete** key. **All clips** – click **Clear all** in the top-right corner of the Clipboard tab, or right-click any entry and choose **Clear all**. This removes the entire history from both the Text and Images lists and cannot be undone. (The Menu column is unaffected – it’s not history.) *** ## Keyboard navigation | Key | Action | | ------------------------------------- | -------------------------------------------------------------------- | | **Up / Down** | Move through items in the focused column | | **Right** | Move focus rightwards (Text → Images → Menu) | | **Left** | Move focus leftwards (Menu → Images → Text) | | **Right** on a Menu category | Expand the category | | **Left** on an expanded Menu category | Collapse it | | **Enter** | Paste the selected item / activate the selected action | | **Delete** | Remove the selected clip from history (Text / Images lists only) | | **Esc** | Hide Workbench to the system tray (when focus isn’t in a text input) | *** ## Empty state When a column contains no clips, a centred placeholder message is shown: * Text column: *No text yet – copy any text to start* * Image column: *No images yet – copy any image to start* *** ## Persistence The full clip history is stored in your user data folder in a shared SQLite database. Items are available the next time you open Supervertaler Workbench. *** ## Related pages * [Voice Commands & Dictation](/workbench/voice/overview/) * [Chat (AI conversation panel)](/workbench/ai-translation/chat/) * [Keyboard Shortcuts](/workbench/settings/shortcuts/) # Comments The **💬 Comments** tab in Workbench’s right panel is where per-segment annotations live. There are two sub-tabs: * **📝 Segment** — comments you author while translating: context notes, queries for the client, reminders to yourself, anchored highlights on specific words. * **✅ Proofreading** — AI-generated proofreading feedback, listed across the whole project and colour-coded by the LLM that produced it (read-only text; delete individually or all at once). Both are stored on the segment itself and persist in the `.svproj` file. Segment comments are **exported to the final document as Word comments** (yellow comment bubbles in the right margin of the exported `.docx`), with the range highlight covering exactly the words you anchored the comment to. Proofreading comments are review-only and don’t export. ## Segment comments ### Two kinds: segment-level and range-anchored There are two kinds of segment comment: * **Segment-level (no anchor)** — a general note about the whole segment. In the exported `.docx` the Word comment anchors to the entire paragraph. * **Range-anchored** — attached to a specific word or phrase you selected. In the exported `.docx` the Word comment highlights exactly those characters, the same way Trados and memoQ comments do. Both kinds coexist and you can have many of each on the same segment. ### Adding a range-anchored comment (Ctrl+M) 1. Click into the source or target cell of a segment. 2. Select the text the comment is about (e.g. `schroef`, `aangebracht`, or a multi-word phrase). 3. Press **Ctrl+M**. 4. A dialog opens showing which segment + which field (source or target) you’re anchoring to, plus a snippet of your selection for confirmation. Type the comment, click **OK**. The anchored text immediately gets a soft amber background in the editor cell so you can see at a glance which words have comments attached. The new comment also appears in the all-comments list (see below). ### Adding a segment-level (unanchored) comment Place the cursor in the source or target cell **without selecting any text**, then press **Ctrl+M** (or right-click → **💬 Add segment comment**). The comment is attached to the whole segment rather than to a specific range. Useful for a general note, or for adding another comment to a segment without disturbing an existing one. ### The all-comments list The Segment sub-tab shows **one entry per Comment** — not per segment. A segment with three comments shows three entries, in document order. Each entry has: * A clickable **Segment #N** header. For anchored comments, the header reads `Segment #N ⚓ source` or `Segment #N ⚓ target` to tell you what kind of anchor it has. * For anchored comments: a quoted snippet of the anchored text, so you can see what the comment is *about* without jumping to the segment. * The full comment body. * A small footer line with the author and timestamp, plus a `(right-click for edit/delete)` hint. Clicking the **Segment #N** header jumps the grid to that segment (cross-page-aware — switches pagination first if needed). Conversely, **selecting a segment in the grid scrolls the list to — and highlights — that segment’s comment(s)**, so the active segment’s notes are always in view without hunting for them. **Right-click** on a Segment header (or anywhere on the entry) opens a context menu with **✏️ Edit comment…** and **🗑️ Delete comment**. Edit opens a small dialog pre-populated with the existing text; saving with an empty text field deletes the comment. Delete prompts for confirmation. The list rebuilds itself in real time as you add, edit, or remove comments. ### Editor visual cue: amber background Anchored comment ranges show a soft amber background in the source or target cell editors. This coexists with the existing syntax highlighting (tag pink, spellcheck underlines, etc.) — the amber is applied as a background colour on the anchored characters only. If you edit the target text after creating an anchored comment, the amber highlight stays at its original character offsets. If your edit shifts the anchor’s intended target, the highlight may end up on slightly-different wording. The simplest workaround is to edit the text first, then create the anchored comment. ### Reaching a comment from the grid You don’t have to open the Comments tab first to find a comment — you can get to it straight from the segment in the grid: * **Hover** the amber-highlighted range in a source or target cell to see the comment as a tooltip. * **Right-click** the highlighted range and choose **💬 Open comment**. Workbench switches the right panel to the **💬 Comments → 📝 Segment** sub-tab and briefly flashes the matching entry — handy when the Match Panel (or another tab) was showing. Segment-level comments have no highlighted range to aim at, so they’re reachable two other ways: * **Right-click anywhere** in a commented segment’s source or target cell → **💬 Open comment(s)** (opens the segment’s first comment). * **Hover or right-click the Status cell** of a commented segment: the tooltip lists the segment’s comments, and right-clicking offers **💬 Open comment(s)**. The Status cell is also **colour-coded** so you can tell comment types apart at a glance: a segment with a **segment comment** shows an **amber** background, one with a **proofreading comment** shows **purple**, and a segment that has **both** shows a **split amber|purple** background. ### Comments in exported documents When you export your project back to a Word document (**Project → Export → Export Translated Document…**), every segment comment becomes a Word comment in the output `.docx`. Behaviour per comment kind: * **Range-anchored to target text**: the Word comment’s range highlight covers exactly the anchored characters. If the anchor boundaries cut mid-run (e.g. inside a bold word), Workbench splits the run cleanly and preserves the formatting on both halves. Visually identical to a Trados or memoQ comment. * **Range-anchored to source text**: the source text isn’t in the exported (target-only) DOCX, so Workbench falls back to anchoring the comment to the whole paragraph, with the source snippet prefixed in the comment body. Example: `[Re: "schroef" (source)] translated as 'screw' based on context`. The reviewer reading the file sees the comment with the relevant source quote inline. * **Segment-level (unanchored)**: anchors to the whole paragraph, like a paragraph-wide annotation. The comment author defaults to the **Translator Name** field in **Settings → User Identity** — set that if you want comments attributed to your real name rather than your system username. Initials are derived automatically (multi-word names take the first letter of each word, e.g. `Michael Beijer` → `MB`; single-word names take the first two characters uppercased, e.g. `mbeijer` → `MB`). After export, Workbench logs how many comments were attached: ```plaintext ✓ Attached 4 segment comment(s) as Word comments (2 range-anchored) ``` If any comments couldn’t be matched to a paragraph (rare — usually because the target text was heavily reformatted by the Okapi merge step), the log says so and the export still completes — the comment-attach step is purely additive. ### Comments and bilingual table exports For bilingual-table export formats (Supervertaler Bilingual Table, memoQ, CafeTran, etc.), segment comments are written to a dedicated **Notes** column rather than as Word comments. Anchored and segment-level comments are concatenated into a single string in that column; the anchor metadata is **not** carried over (these formats don’t have a native concept of in-cell anchoring). Re-importing the bilingual table later preserves the comments as a single segment-level comment per segment. If you need range-anchored comments to survive a round-trip, export as DOCX rather than as a bilingual table. ## Proofreading comments The **✅ Proofreading** sub-tab lists AI-generated review feedback across the **whole project** — mirroring the Segment sub-tab’s all-comments list, so the two tabs now behave the same way. Generate the feedback with **QA ▸ Proofreading ▸ Proofread Translation…** (proofreading moved into the new [QA menu](#the-qa-menu) in v1.10.327). Each entry is one **(segment, model)** result: * A clickable **Segment #N · model** header that jumps the grid to that segment (cross-page-aware). * The proofreader’s findings, shown verbatim. The text is **read-only** — you read it and decide whether to act on it. * A **🗑️ delete** button that removes just that one comment. **Each LLM engine gets its own colour**, so if you ran the project through more than one model (e.g. GPT *and* Claude), you can tell at a glance which model flagged what. Selecting a segment in the grid scrolls the list to — and highlights — that segment’s proofreading comment(s), exactly like the Segment sub-tab. To clear everything at once, use **QA ▸ Proofreading ▸ Delete All Proofreading Comments**. Deletion is safe: re-running **Proofread Translation** regenerates the comments. Proofreading comments are **not** exported to the final document. They’re a translator-side review tool. ### The QA menu AI proofreading lives under the top-level **QA** menu (**QA ▸ Proofreading**), which also hosts **Delete All Proofreading Comments**. See **[AI Proofreading](/workbench/qa/proofreading/)** for how to run a pass. QA is Workbench’s home for quality-assurance features — see also [Spellcheck](/workbench/qa/spellcheck/), [Tag Validation](/workbench/qa/tag-validation/) and [Non-Translatables](/workbench/qa/non-translatables/). ## Quick reference | Action | Shortcut / How | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Add a range-anchored comment to selected text | **Ctrl+M** with text selected, or right-click → **💬 Add comment** | | Add a segment-level comment | **Ctrl+M** with no selection (cursor only), or right-click → **💬 Add segment comment** | | Jump to a commented segment | Click its **Segment #N** header in the all-comments list | | Open a comment from the grid | Hover the highlight for a tooltip; right-click the highlight, the cell, or the Status cell → **💬 Open comment(s)** | | Edit a specific comment | Right-click its header → **✏️ Edit comment…** | | Delete a specific comment | Right-click its header → **🗑️ Delete comment** | | Generate proofreading comments | **QA ▸ Proofreading ▸ Proofread Translation…** | | Delete one proofreading comment | **🗑️** button on its entry in the **✅ Proofreading** list | | Delete all proofreading comments | **QA ▸ Proofreading ▸ Delete All Proofreading Comments** | | Configure the author name for exported comments | **Settings → User Identity → Translator Name** | ## Related * [Editing & Confirming](/workbench/editor/editing-confirming/) * [Keyboard Shortcuts (Workbench)](/workbench/editor/keyboard-shortcuts/) * [Segment Statuses](/workbench/editor/segment-statuses/) # Editing & Confirming Translate by editing the **Target** column in the grid. ## Editing * Double-click a Target cell and type your translation. * Use standard editing shortcuts (undo/redo, copy/paste, find/replace). ### Multi-line target text * Use **Shift+Enter** to insert a line break inside the cell. ## Confirming segments Confirming matters for many workflows, especially when exporting back to a CAT tool. Typical workflow: 1. Translate (manual or AI) 2. Review the target text 3. Confirm the segment ### Confirm shortcuts * **Ctrl+Enter**: confirm the current segment (or all selected segments) and move to the next unconfirmed segment. * **Ctrl+Shift+Enter**: confirm all selected segments. You can also confirm by setting the segment **Status** dropdown to a confirmed status. ## Splitting and merging segments You can re-segment a document the way Trados Studio and memoQ allow — right from the grid: * **Split a segment:** click in the **Source** cell at the exact spot you want to divide, then right-click → **✂ Split segment here**. The existing translation stays with the first part; the second part starts empty, ready to translate. * **Merge two segments:** right-click in the **Source** cell → **🔗 Merge with next segment**. The two sources (and targets) are joined with sensible spacing, and the merged segment takes the less-complete of the two statuses. Both actions are fully **undoable** with **Ctrl+Z** (and redoable with **Ctrl+Y**). **When it’s available:** * Merge is only offered when the next segment is in the **same paragraph, table cell, file, and text unit** — so you can’t accidentally fuse separate paragraphs. If it isn’t allowed, the menu item is greyed out with the reason. * Split needs the cursor to land *inside* the source text, and is disabled while tags are shown in **compact** form or with **outer wrapping tags hidden** (switch to full tag view first, so the split lands in the right place). ## Related pages * [Segment Statuses](/workbench/editor/segment-statuses/) – full reference for workflow statuses, match origins, and how they map to Trados and memoQ * [The Translation Grid](/workbench/editor/translation-grid/) * [Find & Replace](/workbench/editor/find-replace/) * [Tag Validation](/workbench/qa/tag-validation/) # Filtering Segments Filtering helps you focus on the segments you need right now. ## Common uses * Show only segments that contain a specific term * Focus on segments that need review * Quickly find repeated strings and fix consistency ## Tip: filter on selection A fast workflow is to select a word/phrase in the grid and use **Filter on selection**. ### Shortcut * **Ctrl+Shift+F** toggles filtering: * If a filter is not active, it filters on the current selection. * If a filter is active, it clears the filter. # Find & Replace Supervertaler’s Find & Replace feature helps you quickly find text and make consistent changes across your translation. ## Opening Find & Replace * Press `Ctrl+F` or `Ctrl+H` * Or go to **Edit → Find & Replace** ## Dialog layout The action buttons are grouped to make destructive actions visually distinct from non-destructive ones. Reading left to right: * **Find next | Find all | Highlight all | Clear highlights** – non-destructive: searching and highlighting only, no edits made. * A vertical separator marks the boundary. * **Replace this | Replace all** – destructive: these modify your translation. They appear with an **amber background** as a visual cue that clicking them changes the document. The Close button sits at the far right. ### Keyboard shortcuts inside the dialog | Key | Where | Action | | ---------- | -------------------- | ------------------------------------------------------------------------------- | | **Enter** | in the Find field | Triggers **Find next** | | **Enter** | in the Replace field | Triggers **Replace all** (the existing confirmation prompt still appears first) | | **Escape** | anywhere | Closes the dialog | The Enter-in-Replace shortcut is intentional: the Replace all confirmation dialog catches accidental presses, so pressing Enter never silently overwrites your translation. ## Basic Usage ### Finding Text 1. Type your search term in the **Find** field 2. Click **Find all** to see all matches, or press **Enter** for Find next 3. Matches are highlighted in yellow in the grid 4. The results counter shows how many matches were found ### Replacing Text 1. Type your search term in the **Find** field 2. Type your replacement in the **Replace** field 3. Click the amber **Replace all** button, or press **Enter** while the Replace field has focus 4. Confirm the replacement count when the dialog asks 5. A confirmation shows how many replacements were made ## Search Options ### Match Three mutually exclusive modes (radio buttons): | Mode | Description | | ------------------ | ---------------------------------------------------------- | | **Anything** | Matches the search term anywhere in the text (the default) | | **Whole words** | Matches the search term only as a complete word | | **Entire segment** | Matches only when the whole segment equals the search term | ### Case sensitive * ✅ **On**: “Hello” won’t match “hello” * ❌ **Off** (default): “Hello” matches “hello”, “HELLO”, etc. ### Auto-adjust case When replacing, adjusts the replacement to match the case pattern of each match — ALL CAPS → uppercased, all lower → lowercased, Title Case → title-cased. It has no effect when **Case sensitive** is on, and is ignored in **Regex** mode. ### Search in | Scope | Description | | -------------------- | ------------------------------------------- | | **Source** | Search the source column | | **Target** (default) | Search the translations | | Both | Tick both boxes to search source and target | ### Reset edited to Draft When a replacement changes a target segment that was **Confirmed**, **Proofread** or **Approved**, that segment is reset to **Draft**, so the segments Find & Replace touched are easy to spot and re-check afterwards. * ✅ **On** (default): edited finished segments drop back to Draft. * ❌ **Off**: segments keep their existing status. This applies to **Replace this**, **Replace all** and **F\&R Sets** batch runs. Only segments whose text actually changes are affected, and replacing in the source column never changes a status. The setting is remembered between sessions, and `Ctrl+Z` restores the original text and status together. ## Regular expressions Tick **Regex** to treat the Find field as a regular expression (Python `re` syntax). * **Backreferences in Replace:** capture groups in the pattern can be reused in the Replace field as `\1`, `\2`, … (or `\g` for named groups). For example, Find `"([^"]+)"` and Replace `«\1»` turns `"events"` into `«events»`. * **Case sensitive** still applies (off = the whole pattern matches case-insensitively). * While Regex is on, the **Match** modes and **Auto-adjust case** don’t apply and are greyed out. * **Invalid patterns are caught:** an unbalanced pattern (e.g. `(`) or a bad backreference (e.g. `\9` with no matching group) shows a clear error and changes nothing — it never crashes or partially replaces. ## History Dropdowns Both the Find and Replace fields remember your recent searches: * Click the dropdown arrow to see your last 20 entries * Start typing to filter the history * History persists between sessions ## F\&R Sets (Batch Operations) Save and reuse multiple find/replace operations as a set. ### Creating a Set 1. Expand the **📁 F\&R Sets** panel 2. Click **➕ New Set** 3. Give your set a name (e.g., “Client Style Guide”) 4. The set appears in the dropdown ### Adding Operations to a Set 1. Enter your Find and Replace terms 2. Set your options (Match mode, Case sensitive, Regex, Search in) — these are all saved with the operation 3. Click **➕ Add Current to Set** 4. The operation is saved to the active set ### Managing Operations In the F\&R Sets panel: * **✓ (Enabled) column** – tick to include an operation when you click **Run All**; untick to skip it. (Hover for a reminder.) * **Edit** – double-click an operation to load it back into the Find/Replace fields. * **🗑 Delete Operation** – removes the selected operation from the set. * **🗑 Delete Set** – removes the selected set entirely. The **Match** column shows each operation’s mode, or **Regex** when the operation is a regular expression. ### Running a Batch 1. Select your set 2. Click **▶ Run All** 3. Each enabled operation runs in turn; regex operations (shown as “Regex” in the Match column) run with backreferences 4. See how many replacements were made Caution **An empty “Replace with” deletes matches.** An operation with a blank Replace field replaces every match with nothing — i.e. it deletes the matched text. If a set contains any such operation, Run All lists them and defaults the confirmation button to **No**, so you don’t wipe text by accident. ### Importing & exporting sets Share sets with colleagues: * **📤 Export** – save the selected set as a `.svfr` file * **📥 Import** – load a shared `.svfr` file ## Use Cases ### Terminology Consistency Create a set for client-specific terms: * “colour” → “color” (US spelling) * “organisation” → “organization” * “programme” → “program” ### Style Guide Rules Enforce style guidelines: * Double spaces → Single space * “e.g.” → “for example” * Straight quotes → Curly quotes ### Post-Translation Cleanup Clean up common MT artifacts: * Remove unwanted spaces before punctuation * Fix capitalization issues * Normalize formatting ## Tips # Keyboard Shortcuts Master these shortcuts to work faster in Supervertaler. The exact keys are configurable in **Settings → Keyboard Shortcuts**; the tables below list the defaults. ## Navigation | Shortcut | Action | | ----------------------------------- | ----------------------------------------------------------------------- | | `↑/↓` | Previous/next segment when cursor is at the first/last line of the cell | | `Ctrl+Up` | Previous segment (always) | | `Ctrl+Down` | Next segment (always) | | `Ctrl+G` | Go to segment number | | `Page Up` / `Page Down` | Previous / next page (when paginated) | | `Shift+Page Up` / `Shift+Page Down` | Extend selection up / down by a screenful | | `Ctrl+Home` | First segment | | `Ctrl+End` | Last segment | ## Editing | Shortcut | Action | | ------------------------------ | ---------------------------------------------------------------------------------------------------- | | `Ctrl+Enter` | Confirm current (or selected) segment(s) and go to the next | | `Ctrl+Shift+Enter` | Confirm selected segments | | `Ctrl+Z` | Undo | | `Ctrl+Y` | Redo | | `Ctrl+C` / `Ctrl+V` / `Ctrl+X` | Copy / paste / cut | | `Ctrl+A` | Select all (in cell) | | `Shift+Enter` | Insert line break inside a cell | | `Tab` | Cycle between the source and target cells | | `Ctrl+Tab` | Insert a literal tab character | | `Ctrl+,` | Insert next tag / wrap selection with a tag pair (when available) | | `Ctrl+Shift+S` | Copy source text to target | | `Ctrl+M` | Add a comment to the selected source/target text (or a segment-level comment if nothing is selected) | | `Alt+D` | Add the word at the cursor to the custom dictionary | ## Translation | Shortcut | Action | | -------------- | -------------------------------------------------------- | | `Ctrl+T` | Translate current segment with AI | | `Ctrl+Shift+T` | Translate multiple segments | | `Ctrl+Space` | Insert the currently selected match from the grid | | `Alt+1…9` | Insert TermLens term #1…#9 (double-tap for #11…#99) | | `Ctrl+Alt+Q` | QuickTrans instant-translation popup (works system-wide) | | `Ctrl+Q` | Open QuickLauncher (AI prompt actions) | ## Find & Replace | Shortcut | Action | | ------------------------- | -------------------------------------- | | `Ctrl+F` | Open Find & Replace dialog | | `Ctrl+H` | Open Find & Replace on the Replace tab | | `Enter` (in the Find box) | Find next match | ## Filtering | Shortcut | Action | | -------------- | -------------------------------- | | `Ctrl+Shift+F` | Filter on selected text (toggle) | ## Lookup | Shortcut | Action | | ------------ | ---------------------------------------------------------------- | | `Ctrl+K` | Open SuperLookup (concordance) for the selection | | `Ctrl+Alt+L` | SuperLookup as a system-wide hotkey (works from any application) | ## View | Shortcut | Action | | ------------------------------- | ---------------------------------------------------------------------------------------------- | | `Ctrl+Plus` | Increase grid font size | | `Ctrl+Minus` | Decrease grid font size | | `Ctrl+Shift+=` / `Ctrl+Shift+-` | Increase / decrease results-pane font size | | `Ctrl+Shift+H` | Toggle tag view | | `Ctrl+Alt+P` | Toggle the [Document Preview](/workbench/editor/preview/) panel (and back to the previous tab) | ## Resources & Tools | Shortcut | Action | | -------------- | ---------------------------------------- | | `Ctrl+Shift+M` | TM Manager (separate window) | | `F5` | Force-refresh matches (clear cache) | | `Ctrl+Alt+C` | Open the Clipboard manager (system-wide) | ## File Operations | Shortcut | Action | | -------- | -------------------- | | `Ctrl+S` | Save project | | `Ctrl+O` | Open project | | `Alt+F4` | Quit the application | ## Termbase / Glossary | Shortcut | Action | | ------------------------------ | ----------------------------------------------------------------- | | `Ctrl+Alt+T` | Add the selected term pair to a termbase (opens the entry dialog) | | `Alt+Up` (or `Ctrl+Shift+1`) | Quick-add the selected term pair to the project termbase | | `Alt+Down` (or `Ctrl+Shift+2`) | Quick-add the selected term pair to the background termbase | | `Ctrl+Alt+N` | Add the selection to Non-Translatables | ## Voice (if enabled) | Shortcut | Action | | ------------------ | ------------------------------------------------------- | | `Ctrl+Shift+Space` | Voice dictation / push-to-talk (default — configurable) | | `Ctrl+Alt+A` | Toggle Always-On listening | *** ## Customising shortcuts You can view and customise every shortcut in **Settings → Keyboard Shortcuts**, and export a printable cheatsheet (HTML) or the raw definitions (JSON) from there. ## Tips ### memoQ-style navigation The arrow keys work like memoQ: * Press `↓` at the **last line** of a cell to move to the next segment * Press `↑` at the **first line** of a cell to move to the previous segment * Cursor column position is preserved when moving between segments ### Quick filtering 1. Select text in any segment 2. Press `Ctrl+Shift+F` to filter 3. Only segments containing that text are shown 4. Press `Ctrl+Shift+F` again to clear the filter # Navigating Segments Supervertaler is designed for fast, memoQ-style navigation in the translation grid. ## Moving between segments * Use the arrow keys to move within a cell. * When your cursor is at the **top** or **bottom** line of a cell, **Up/Down** can jump to the previous/next segment. ### Always move up/down If you want to move between segments regardless of where the cursor is inside the cell: * **Ctrl+Up** → previous segment * **Ctrl+Down** → next segment ### Jump to a segment * **Ctrl+G** opens **Go to Segment**. * Type a segment number and press Enter. ### Jump to start/end * **Ctrl+Home** → first segment * **Ctrl+End** → last segment ### Tab between Source/Target * **Tab** cycles between the Source and Target cell on the same row. * **Ctrl+Tab** inserts a literal tab character inside the text. ## Pagination By default all segments are shown on one page. You can split the project into fixed-size pages with the **Per page** selector (very large projects open paginated automatically). * See: [Pagination](/workbench/editor/pagination/) ## Tips * Keep one hand on the keyboard for speed: navigate, edit, confirm, repeat. * If you work in a CAT tool daily, customize shortcuts to match your muscle memory. See also: [Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) # Pagination By default Workbench shows **all** segments on a single page. You can split a project into pages of a fixed size using the **Per page** selector above the grid (5, 10, 25, 50, 100, 200, 500, or All). ## The default: All New projects open with every segment shown. With recent performance work this is comfortable well into the thousands of segments. The one exception is very large projects: a document with **more than 2000 segments** opens paginated at **500 per page** so the initial layout stays snappy. You can switch it back to **All** (or any other size) at any time with the **Per page** selector — your choice sticks for the rest of the session. ## Why you might still page * Work through a long project in smaller review batches * Keep the grid light on a low-spec machine or an enormous file ## Navigation Use the pagination controls to move between pages. ### Shortcuts * **Page Up** → previous page * **Page Down** → next page # Document Preview The **Document Preview** is a reading view of your translation as a finished document, shown in the right-hand panel under the **📄 Preview** tab. As you translate, it rebuilds the document the way it will actually read — so you can sanity-check flow, paragraphing and formatting without exporting. ## What it shows * **Real document structure.** Sentences are reassembled into their original **paragraphs** (rather than one block per segment), and headings and lists are laid out accordingly — so the preview follows the source document’s structure, not the segmentation. * **Live translation.** Each segment shows its **target** text as soon as you translate it (falling back to the source until then), so the preview fills in as you work. * **Status at a glance.** Confirmed segments read clean; unconfirmed ones carry a faint amber tint. * **The current segment** is highlighted in light blue over its exact text, and the preview follows along as you move through the grid. ## Click to navigate Click any sentence in the preview to jump the grid straight to that segment — a quick way to move around a long document by reading rather than scrolling. ## Pop out into its own window Click **⧉ Pop out** at the top of the Preview tab to open the preview in a separate, resizable window — ideal for a second monitor. The pop-out window stays fully live: it tracks your edits, follows the current segment, and click-to-navigate still works. Close it to return to just the docked panel. ## Toggle with a keyboard shortcut Press **`Ctrl+Alt+P`** from the grid to switch the right panel to the Document Preview, then press it again to jump straight back to whatever tab you had open before (usually the Match Panel). See also: [Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) # Segment Statuses Every segment in Supervertaler carries two independent pieces of information: 1. **Match origin** – how the translation got there (TM match, machine translation, manual typing) 2. **Workflow status** – where the segment is in the review cycle (draft, confirmed, approved) These are two separate dimensions. A segment can be a 100% TM match *and* confirmed – the match tells you where the translation came from, and the workflow status tells you whether a human has signed off on it. *** ## Workflow Statuses These track a segment’s progress through the translation and review cycle. | Status | Icon | Meaning | | --------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Not started** | ❌ | No translation yet. The target is empty. | | **Draft** | ✏️ | Has a translation, but it has not been confirmed yet. This includes segments filled by AI, TM pre-translation, or manual typing that the translator has not yet explicitly confirmed. | | **Confirmed** | ✔ | The translator has explicitly confirmed the translation (Ctrl+Enter). The segment is saved to TM at this point. | | **Proofread** | 🟪 | A reviewer has checked and approved the translation. | | **Approved** | ⭐ | Final sign-off. The translation has passed all review stages. | | **Rejected** | 🚫 | A reviewer has rejected the translation. It needs to be revised. | | **Locked** | 🔒 | The segment cannot be edited. Typically used for non-translatable content or segments that must not be changed. | ### How confirmation works When you press **Ctrl+Enter**, the current segment is marked as **Confirmed** and the cursor moves to the next unconfirmed segment. Only confirmed segments are saved to Translation Memory. If you go back and edit a confirmed segment, it automatically drops back to **Draft** until you re-confirm it. This prevents accidental TM entries from half-finished edits. *** ## Match Origins Match origins tell you how the translation was initially obtained, before anyone reviewed it. They appear as the segment status when the segment has been pre-translated but not yet confirmed. | Status | Icon | Meaning | | ------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------ | | **PM (102%)** | PM | **Perfect Match.** The segment matches a TM entry with identical context (surrounding segments). The highest level of TM confidence. | | **CM (101%)** | CM | **Context Match.** A 100% TM match where the preceding segment context also matches. | | **TM 100%** | ✅ | **Exact Match.** The source text matches a TM entry exactly, without additional context confirmation. | | **TM Fuzzy** | 🔶 | **Fuzzy Match.** The source partially matches a TM entry (typically 75-99%). The translation will need editing. | | **MT** | 🤖 | **Machine Translation.** Generated by an MT engine or AI model. | | **Repetition** | 🔁 | **Internal Repetition.** The same source text appears elsewhere in the project and the translation was auto-propagated. | | **Pre-translated** | ⚡ | Generic pre-translation from an unspecified source. | Perfect Match and Context Match are shown as small coloured **PM** and **CM** text badges in the status column, mirroring the way Trados Studio labels them, rather than as emoji icons. ### What happens when you confirm a match When you confirm a segment, its status changes from its match origin (e.g. “CM 101%”) to **Confirmed**. The match percentage is preserved internally, but the status icon now reflects the workflow state rather than the match type. This is the same behavior as in Trados Studio and memoQ. *** ## Mapping to Other CAT Tools Supervertaler’s statuses map cleanly to Trados Studio and memoQ. When you import a file from either tool, both the match origin and the workflow status are preserved. When you export back, statuses are mapped to the correct values for each tool. ### Workflow statuses | Supervertaler | Trados Studio | memoQ | | ------------- | -------------------- | -------------------- | | Not started | *(no translation)* | Not started | | Draft | Draft | Edited | | Confirmed | Translated ✓ | Confirmed | | Proofread | Translation Approved | Reviewer 1 confirmed | | Approved | Sign-off Approved | Reviewer 2 confirmed | | Rejected | Translation Rejected | Rejected | | Locked | Locked | Locked | Caution **Trados naming quirk:** In Trados Studio, “Translated” (green checkmark) actually means *confirmed by the translator*. This is equivalent to Supervertaler’s **Confirmed**. Trados “Draft” is equivalent to Supervertaler’s **Draft**. ### Match origins | Supervertaler | Trados Studio | memoQ | | ------------- | ---------------------------- | --------------------- | | PM (102%) | Perfect Match | 102% (double context) | | CM (101%) | Context Match | 101% (context match) | | TM 100% | Exact Match (100%) | 100% | | TM Fuzzy | Fuzzy Match | Fuzzy (75-99%) | | MT | Machine Translation (NMT/AT) | MT | | Repetition | Repetition (auto-propagated) | Repetition | *** ## Related pages * [Editing & Confirming](/workbench/editor/editing-confirming/) * [The Translation Grid](/workbench/editor/translation-grid/) * [CAT Tool Integration](/workbench/cat-tools/overview/) * [Trados Studio Workflow](/workbench/cat-tools/trados/) * [memoQ Workflow](/workbench/cat-tools/memoq/) # The Translation Grid The translation grid is where you spend most of your time: each row is a **segment** (usually a sentence or paragraph) with source and target text. ## Columns The grid has five columns: | Column | What it is | | ---------- | -------------------------------------------------- | | **#** | Segment number (row index) | | **Type** | Segment type (depends on the file format/importer) | | **Source** | Original text (typically read-only) | | **Target** | Your translation (editable) | | **Status** | Segment status (dropdown) | ## Editing behavior * The grid is optimized for speed, but edits are intentionally lightweight. * **Double-click** a cell to edit. * Use **Shift+Enter** for a line break inside a cell (multi-line target). ## Confirming & status * Use the **Status** dropdown to set the segment state. * Keyboard confirm is supported (see [Editing & Confirming](/workbench/editor/editing-confirming/)). Common statuses include: * Not started * Translated * Confirmed * Proofread * Approved ## Visual cues * **Tags** (CAT tool placeholders and formatting markers) are highlighted to make them hard to miss. * **Spellcheck** (if enabled) underlines misspelled target words. * **Termbase matches** can be highlighted in the source. ## TermLens panel placement You can dock the TermLens panel directly above or below the grid from the **View** menu: * **Show TermLens above grid** –places the panel between the filter bar and the grid. * **Show TermLens below grid** –places it under the grid. The change applies immediately, no need to reopen the project. Clicking the option that is already active hides the panel again. ## Splitting and merging segments Right-click in a **Source** cell to **✂ Split segment here** (at the clicked position) or **🔗 Merge with next segment** — Trados/memoQ-style re-segmentation, fully undoable. See [Editing & Confirming](/workbench/editor/editing-confirming/#splitting-and-merging-segments) for details and when it’s available. ## See also * [Navigation](/workbench/editor/navigation/) * [Editing & Confirming](/workbench/editor/editing-confirming/) * [Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) * [Filtering](/workbench/editor/filtering/) # Api Keys To use AI translation you need an API key from at least one provider. Enter your key in **Settings → AI Settings**. ## Supported providers | Provider | Where to get a key | | ------------------------------------- | -------------------------------------------------------------------- | | **OpenAI** | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | | **Anthropic (Claude)** | [console.anthropic.com](https://console.anthropic.com) | | **Google (Gemini)** | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | | **Grok (xAI)** | [console.x.ai](https://console.x.ai) | | **Mistral AI** | [console.mistral.ai](https://console.mistral.ai) | | **DeepSeek** | [platform.deepseek.com](https://platform.deepseek.com) | | **OpenRouter** (200+ models, one key) | [openrouter.ai/keys](https://openrouter.ai/keys) | | **Ollama** | No key needed – runs locally | ## Entering a key 1. Open **Settings → AI Settings** 2. Select your provider from the **Provider** dropdown 3. Paste your API key into the **API Key** field 4. Click **Test Connection** to verify 5. Save settings Keys are stored locally and are only sent to the provider’s own API endpoint. ## Switching providers You can configure keys for multiple providers in the same settings panel. Switch between them without re-entering credentials – the key for each provider is remembered independently. ## Using Ollama (no key required) Ollama runs models entirely on your machine. No API key or internet connection is needed. See [Ollama Setup](/workbench/ai-translation/ollama/) for download and configuration instructions. ## Using OpenRouter (one key for everything) If you prefer not to manage multiple accounts, OpenRouter lets you access 200+ models from all major providers with a single API key. Create an account at [openrouter.ai](https://openrouter.ai) and paste your key into the **OpenRouter** provider slot. ## Troubleshooting | Problem | Solution | | --------------------- | -------------------------------------------------------------------- | | ”Invalid API key” | Double-check the key; ensure no leading or trailing spaces | | ”Rate limit exceeded” | Wait a moment, or upgrade your API plan | | ”Model not found” | Check the model name in settings; it may have been updated | | No response | Check your internet connection and that the provider’s service is up | *** ## Next steps * [Create your first project](/workbench/get-started/first-project/) * [Supported LLM Providers](/workbench/ai-translation/providers/) * [AI Translation Overview](/workbench/ai-translation/overview/) # Your First Translation Project Let’s walk through creating a complete translation project from start to finish. ## Creating a New Project ### Option 1: Import a Document 1. Go to **Project → Import → Import Document…** (`Ctrl+O`) 2. Select your Word document 3. Choose the source language (e.g., “English”) 4. Choose the target language (e.g., “Dutch”) 5. Click **Import** Your document is now segmented and ready for translation. ### Option 2: Import a Text File 1. Go to **Project → Import → Text / Markdown File (TXT, MD)…** 2. Select your `.txt` file 3. Each line becomes a separate segment ### Option 3: Multi-File Project 1. Go to **Project → Import → Folder (Multiple Files)…** 2. Select a folder containing DOCX or TXT files 3. Choose which files to include 4. All files are imported as one project ## Understanding the Interface After import, you’ll see the main window. Along the top are the workspace tabs (**Editor**, **TMs**, **Termbases**, **AI**, **SuperLookup**, **Clipboard Manager**, **Voice**, **Settings**). The **Editor** tab holds the translation grid: ```plaintext ┌──────────────────────────────────────────────────────────────────────┐ │ Editor │ TMs │ Termbases │ AI │ SuperLookup │ Clipboard │ Voice │ ⚙ │ ├──────────────────────────────────────────────────────────────────────┤ │ # │ Type │ Source │ Target │ Status │ ├────┼──────┼───────────────────────┼───────────────────────┼───────────┤ │ 1 │ ¶ │ Hello, world! │ │ ❌ │ │ 2 │ ¶ │ This is a test. │ │ ❌ │ │ 3 │ ¶ │ Translate me! │ │ ❌ │ └────┴──────┴───────────────────────┴───────────────────────┴───────────┘ ``` **TMs** and **Termbases** are their own top tabs for managing translation memories and terminology. ### Status Icons | Icon | Meaning | | ---- | -------------------------------- | | ❌ | Not started | | ⚡ | Pre-translated | | ✏️ | Draft (edited but not confirmed) | | ✔ | Confirmed | | 🔒 | Locked | See [Segment Statuses](/workbench/editor/segment-statuses/) for the full list. ## Translating Your First Segment 1. Click on segment 1’s Target cell 2. Type your translation 3. Press `Ctrl+Enter` to confirm 4. The status changes to ✅ ### Using AI Translation 1. Click on segment 2 2. Press `Ctrl+T` to translate it with AI 3. The AI translation appears in the Target cell 4. Review, edit if needed, and confirm with `Ctrl+Enter` ## Setting Up Resources ### Add a Translation Memory 1. Go to the **TMs** tab 2. Click **+ Create TM** or **Import TMX** 3. Your TM will automatically provide matches ### Add a Termbase 1. Go to the **Termbases** tab 2. Click **+ Create Termbase** 3. Add terms manually or import from TSV ## Saving Your Project 1. Press `Ctrl+S` 2. Choose a name and location 3. Your project is saved as a folder containing the `.svproj` file, a `source/` folder (your original document), and — once you export — a `target/` folder. See [The Project Folder](/workbench/import-export/project-folder/). ## Exporting the Translation When you’re finished: 1. Go to **Project → Export** 2. Choose your format: * **DOCX** - Standard Word document with translations * **Bilingual Table** - Source and target side by side * **Text File** - Plain text output 3. Select destination and click **Export** ## Project Workflow Summary ```plaintext Import Document ↓ Set Up TMs & Termbases (optional) ↓ Translate Segments (manual or AI) ↓ Review & Confirm (Ctrl+Enter) ↓ Save Project (.svproj) ↓ Export Translation ``` *** ## What’s Next? Now that you’ve completed your first project: * [Learn keyboard shortcuts](/workbench/editor/keyboard-shortcuts/) for faster work * [Set up batch translation](/workbench/ai-translation/batch-translation/) for larger documents * [Explore CAT tool workflows](/workbench/cat-tools/overview/) if you use professional tools # Installation ## Windows (Recommended) ### Option 1: Download Release (Easiest) 1. Go to [GitHub Releases](https://github.com/Supervertaler/Supervertaler-Workbench/releases) 2. Download the latest `.zip` file 3. Extract to a folder of your choice 4. Run `Supervertaler.exe` 5. *Optional:* double-click **`Add Supervertaler to Start Menu.cmd`** once to add a Start Menu shortcut, so you can launch the app from the Start Menu (or pin it to the taskbar) like any installed program. This is just a friendly wrapper around `create_start_menu_shortcut.ps1` that bypasses Windows’ default PowerShell ExecutionPolicy without changing any system-wide settings. ### Option 2: Run from Source If you want the latest development version or want to contribute: ```bash # Clone the repository git clone https://github.com/Supervertaler/Supervertaler-Workbench.git cd Supervertaler # Create virtual environment python -m venv venv venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Run the application python Supervertaler.py ``` ## macOS The macOS install method depends on your Mac’s processor. ### Apple Silicon (M1, M2, M3, M4) — Download Release 1. Go to [GitHub Releases](https://github.com/Supervertaler/Supervertaler-Workbench/releases) 2. Download the latest `.dmg` file 3. Open the `.dmg` and drag **Supervertaler** to your Applications folder 4. Launch from Spotlight or Launchpad ### Intel Macs — Install via pip The published macOS `.dmg` is built for Apple Silicon only and will not run on Intel hardware. Intel Mac users need to install via pip and provide a system Java for the Okapi sidecar (which handles Word, Excel, HTML and other office-document imports). ```bash # 1. Install Homebrew (skip if already installed) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 2. Install Python 3 (skip if already installed) brew install python@3.12 # 3. Install Java 17 (Eclipse Temurin, free, no Oracle account required) brew install --cask temurin@17 # 4. Install Supervertaler pip3 install supervertaler # 5. Run it supervertaler ``` If you skip the Java step, Supervertaler shows a friendly dialog at startup with the install command. Plain-text translation, TMX, termbases, etc. all work without Java – only office-document import/export needs it. On first DOCX import, Supervertaler downloads the Okapi sidecar JAR (\~28 MB) into `~/Library/Application Support/Supervertaler/okapi-sidecar/`. After that, everything runs locally and offline. ### Run from Source (any Mac) Follow the [Linux source instructions](#linux) below – the commands are identical except for the spellcheck step, where you’d use `brew install hunspell` instead of `apt install hunspell-*`. ## Linux Supervertaler is compatible with Linux, though Windows is the primary development platform. ```bash # Clone the repository git clone https://github.com/Supervertaler/Supervertaler-Workbench.git cd Supervertaler # Create virtual environment python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt # Install Hunspell dictionaries (for spellcheck) sudo apt install hunspell-en-us hunspell-nl # Add your languages # Run the application python Supervertaler.py ``` ## Dependencies The main dependencies are automatically installed via `requirements.txt`: | Package | Purpose | | ------------------- | ---------------------------- | | PyQt6 | User interface | | openai | OpenAI GPT integration | | anthropic | Anthropic Claude integration | | google-generativeai | Google Gemini integration | | python-docx | DOCX file handling | | pyspellchecker | Spellcheck | ## Next Steps After installation: 1. [Set up your API keys](/workbench/get-started/api-keys/) for AI translation 2. Follow the [Quick Start Guide](/workbench/get-started/quick-start/) 3. Create your [first translation project](/workbench/get-started/first-project/) # Quick Start Guide This guide will get you translating in under 5 minutes. If you’re not sure where to begin: import a file, translate a few segments, then export back to your CAT tool. ## Step 1: Start Supervertaler Launch the application by running `Supervertaler.exe` (Windows) or `python Supervertaler.py` (from source). ## Step 2: Import a Document 1. Go to **Project → Import** 2. Choose your file type: * **DOCX** - Standard Word documents * **Text File** - Plain text (one segment per line) * **memoQ Bilingual** - memoQ XLIFF or bilingual DOCX * **Trados Package** - SDLPPX files * **Phrase Bilingual** - Memsource bilingual DOCX * **CafeTran Bilingual** - CafeTran external view 3. Select source and target languages when prompted 4. Your document appears in the translation grid ## Step 3: Navigate the Grid The translation grid has 5 columns: | Column | Description | | ---------- | --------------------------------------- | | **#** | Segment number | | **Type** | Segment type (¶, heading, list item, …) | | **Source** | Original text (read-only) | | **Target** | Your translation (editable) | | **Status** | Translation status indicator | ### Basic Navigation | Action | Shortcut | | ---------------- | ------------------------------- | | Next segment | `Enter` or `↓` (at end of cell) | | Previous segment | `↑` (at start of cell) | | Go to segment | `Ctrl+G` | Most navigation is designed to feel memoQ-like: arrow keys move within a cell, and at the top/bottom line they can jump between segments. ## Step 4: Translate a Segment ### Manual Translation 1. Click in the **Target** cell 2. Type your translation 3. Confirm the segment (confirmed statuses matter when exporting back to CAT tools) ### AI Translation 1. Select a segment 2. Use the **Translate action** (single segment; **Ctrl+T**) or **Batch Translate** (multiple segments) 3. Review and edit if needed 4. Confirm the segment when you’re happy ## Step 5: Save Your Project 1. Press `Ctrl+S` or go to **Project → Save Project** 2. Choose a location and filename 3. Projects are saved as `.svproj` files ## Step 6: Export Your Translation 1. Go to **Project → Export** 2. Choose the appropriate format: * **DOCX** - Translated Word document * **Bilingual Table** - Side-by-side source/target * **Return Package** - For CAT tool workflows Caution For CAT tool workflows, always export the matching return format (for example, SDLRPX for Trados return packages) to preserve tags and statuses. *** ## What’s Next? ### Recommended next steps * [Setting Up API Keys](/workbench/get-started/api-keys/) – enable AI translation * [Installation](/workbench/get-started/installation/) – verify dependencies and optional components * [CAT Tool Integration](/workbench/cat-tools/overview/) – memoQ/Trados/Phrase/CafeTran workflows * [Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) – faster editing and navigation | | | | ---------------------------- | ------------------------------------------------------- | | **Set up AI Translation** | [Configure API keys →](api-keys.md) | | **Learn Keyboard Shortcuts** | [View all shortcuts →](../editor/keyboard-shortcuts.md) | | **Work with CAT Tools** | [CAT tool integration →](../cat-tools/overview.md) | # Supervertaler Re-importable Table (DOCX) The **Supervertaler Re-importable Table** is a branded Word (DOCX) export that lays your project out as a side-by-side table — handy for reviewing, proofreading, or handing off to someone who doesn’t use a CAT tool. Its defining feature: it can be edited and **re-imported** to pull the changes straight back into your project. (Its plain-text sibling, [Re-importable Text](/workbench/import-export/bilingual-text/), does the same round-trip in an AI-friendly text format.) ## When to use it * A proofreading round-trip in Word: export, edit the targets, re-import. * Sharing with a reviewer who doesn’t use your CAT tool. ## Columns | Column | Description | | ------------ | ----------------------------------------------------------------------- | | **#** | Segment number | | **Source** | Source text | | **Target** | Target text (edit this when proofreading) | | **Status** | Segment status | | **Comments** | Segment comments — edit, add, or clear; changes round-trip on re-import | A header above the table shows the project name, language pair, segment count, and export date. ## Where to find it **Project → Export → 🔁 Supervertaler Re-importable → Bilingual Table (DOCX)**. Formatting tags stay visible as markup; edit the Target/Comments cells, save, and bring the changes back in (see below). Don’t change the segment numbers (#) or the source text. The document is titled *Supervertaler Re-importable Table*.  The re-importable Bilingual Table: formatting shown as visible markup, with a notice that segment numbers and source text must stay unchanged so the file can be re-imported after proofreading. ## Round-trip (proofread and re-import) 1. Export the **re-importable** Bilingual Table. 2. Edit in Word — leave the **#** and **Source** columns untouched: * The **Target** column for translation edits. * The **Comments** column to edit, add, or clear segment comments. New comments added to segments that had none in Workbench are also round-tripped. 3. Back in Workbench: **Project → Import → 🔁 Supervertaler Re-importable → Bilingual Table (DOCX) – Update Project**. 4. Supervertaler diffs the file against your project and shows a preview before applying. Target changes set the segment back to “Not Started” so you can re-confirm; comment changes replace the segment’s existing comments verbatim with the proofreader’s text (no `[Review: …]` wrapping or appending — round-trip in, round-trip out). ## Other bilingual tables To round-trip back into a **CAT tool**, use that tool’s own bilingual format (memoQ, CafeTran, Phrase, Trados Bilingual Review) rather than the Supervertaler table — see [CAT Tool Overview](/workbench/cat-tools/overview/). ## Related * [Supported File Formats](/workbench/import-export/formats/) * [Exporting Translations](/workbench/import-export/exporting/) # Supervertaler Re-importable Text (AI-friendly) The **Re-importable Text** round-trip lets you send a whole translation out as a plain-text file — for a proofreader or an LLM to edit — and then pull the edits straight back into the same project. It’s the plain-text sibling of the [Re-importable Table (DOCX)](/workbench/import-export/bilingual-tables/), ported from the Supervertaler for Trados plugin. Added in v1.10.231. ## Exporting **Project → Export → 🔁 Supervertaler Re-importable → Bilingual Text (AI-friendly)…** You’ll get a small options dialog (include locked segments; which statuses to include), then a save dialog. Two files are written side by side: * `MyProject_bilingual.txt` — the editable text file. * `MyProject_bilingual.txt.svexport.json` — a **sidecar** that records, per segment, a stable id, a source hash, and the status. Keep the two files together; the sidecar is what makes a safe re-import possible. The file opens with a short header that lists exactly which statuses you may set. Each segment is one block: ```plaintext [SEGMENT 0001] EN: The quick brown fox {1} NL: De snelle bruine vos {1} Status: Confirmed Comment: Verify the shade of "brown" ``` * The `EN:` line is the **source** — leave it alone. It stays on **one line**, and a `[newline]` in it marks where the original source broke across two lines (e.g. a subtitle cue). The source is read-only and never written back to your project, so these tokens are just there to show its structure — handy for spotting a target that’s missing a break the source has. * The `NL:` line is the **target** — edit it freely, but **keep it on one line**. Where the target needs a hard line break — for example to split a subtitle across two lines — write the literal token `[newline]`: ```plaintext NL: Welkom bij dit webinar[newline]over de waardeketenanalyse ``` On re-import `[newline]` is turned back into a real line break, so the two-line layout is preserved on export. *(Introduced in v1.10.255; files exported before that — with the target genuinely wrapped over several lines — still re-import unchanged.)* * The `Comment:` line is always present (blank when the segment has no comment) so you can see the field exists. **Edit it, fill the blank one, or clear it** — the change re-imports into the segment’s comments. It too may span several lines. * `…`, `…`, `…` are **cosmetic formatting** — add or remove them as you like. * `{1}`, `[1}`, `<92>` and similar are **structural tags** — keep them; dropping one will flag the segment on re-import (see below). A real file looks like this — note the single-line sources and the `[newline]` token marking where each target splits across two lines: ![A Supervertaler Re-importable Text file: the header lists the project details and the editing rules, the NL: source lines each sit on one line, and two EN: targets show the \[newline\] token highlighted where a subtitle is split across two lines.](/.gitbook/assets/SUPERVERTALER-RE-IMPORTABLE-TEXT-newlines.png) ## Editing with an LLM Hand the `.txt` to ChatGPT, Claude, Gemini, etc. with an instruction such as *“edit only the `NL:` lines; keep each one on a single line, using the literal token `[newline]` for any line break; leave the `[SEGMENT …]` markers, the `EN:` lines, and the `{…}` tags untouched.”* Because each field is one labelled line (not a table column), it survives pipe characters and long inputs without the source/target roles getting confused, and keeping targets to one line stops an agent from accidentally reflowing them. ## Re-importing **Project → Import → 🔁 Supervertaler Re-importable → Bilingual Text (AI-friendly) - Update Project…** Pick the edited `.txt` (its sidecar is found automatically). A preview dialog shows how many segments will be updated, how many are unchanged, and how many are skipped — and why. Nothing is applied until you click **Apply changes**. ### Safety guards * **Source-tamper detection** — if a segment’s source line was changed, that segment is skipped (its hash no longer matches the sidecar). * **Structural-tag integrity** — if the edited target dropped a required tag, the segment is flagged. With **“Refuse to apply edits that drop required tags”** ticked (the default), such segments are skipped; untick it to apply them anyway. Cosmetic ``/``/`` changes never trip this. * **Locked segments** are never modified. ### Status * If you (or the AI) deliberately change a `Status:` line to a different value, that status is applied. * Otherwise, any segment whose target you edited is marked **Draft** — a translated-but-unconfirmed state, ready for you to review and confirm. ### Comments * Existing segment comments are written out as a `Comment:` line. Edit it, add a new one to a segment that had none, or delete it — the change re-imports into the segment’s comments. A comment-only edit (target left alone) is applied on its own and shows up in the import preview. ## Tips * Export reads **live grid state**, so in-progress edits are included even if the segment isn’t confirmed. * If the sidecar is missing, you can still re-import — segments are then matched by position only, and source-tamper detection is unavailable. You’ll be warned first. ## Related * [Supervertaler Re-importable Table (DOCX)](/workbench/import-export/bilingual-tables/) * [Exporting Translations](/workbench/import-export/exporting/) # Importing DOCX Files Use DOCX import for normal Word documents (not CAT tool bilingual formats). DOCX import is handled by the bundled **Okapi sidecar** – an industry-standard localisation library that runs as a small background service. This gives you SRX-based segmentation, proper paragraph and table detection, and a faithful round-trip on export. ## Import steps 1. Go to **Project → Import → Import Document…** (`Ctrl+O`) 2. Select your `.docx` file 3. Choose the **source** and **target** languages when prompted 4. The document is segmented into rows in the translation grid – formatting tags (``, ``, ``, hyperlinks, runs) appear inline so you can preserve them in the translation A progress dialogue shows extraction progress for large documents – on a 2,500-segment file expect a few seconds. ## What is preserved on round-trip When you later export back to DOCX, Supervertaler reconstructs the original document via the same Okapi sidecar: * **Layout**: paragraphs, tables, headers, footers, page breaks * **Inline formatting**: bold, italic, underline, sub/superscript, colour * **Hyperlinks**: anchor text and links round-trip identically – broken or working * **Images and other non-translatable content**: passed through untouched ## Tips * If you are working with memoQ/Trados/Phrase/CafeTran, prefer the specific CAT workflow import instead of generic DOCX. * Keep formatting tags balanced when editing translations (e.g. `text`, not `text`). * Placeholder tags like `` and `` represent structural elements (hyperlinks, run boundaries). Leave them in the same position as the source so the export reconstructs the document correctly. ## When DOCX import is unavailable The Okapi sidecar requires Java – Supervertaler ships a bundled JRE, so this is normally invisible. If the sidecar fails to start (Java missing, port 8090 blocked by another process, …) you’ll see an “Okapi sidecar required” dialogue with troubleshooting steps. DOCX import won’t fall back silently to a degraded engine. # Export Verification (Word-Count Check) Whenever you export a translated **DOCX**, Supervertaler runs an automatic safeguard that checks whether any text was lost on the way out of the document. It is a safety net against the rare case where the round-trip drops content that is present and confirmed in the grid. ## What it does After writing the file, Supervertaler: 1. Counts the words it **expected** to write – the target text of every segment, falling back to the source text for any untranslated segment. 2. Counts the words **actually present** in the exported DOCX (document body, headers, footers, and foot/endnotes). 3. Compares the two. If the exported file contains noticeably fewer words than expected, it shows a warning. Tags, numbers, and punctuation are counted the same way on both sides, so a genuine loss of text shows up as a clear shortfall while incidental formatting differences stay within tolerance. ## When it runs * Automatically, on **every DOCX export** – single-file and multi-file, whether the file is built through the Okapi merge or the standard exporter. * Multi-file projects produce a **single combined warning** listing each affected file, rather than one dialog per file. ## The warning If a file falls short, you’ll see a **Possible Missing Text in Export** dialog naming the file(s) and roughly how many words appear to be missing. The same result is written to the log, for example: ```plaintext 🔢 Export word-count check [Manual.docx]: 4065/4060 words (100%; threshold 95%) ``` or, when text looks lost: ```plaintext ⚠️ Possible dropped text in export: Manual.docx has only 85% of the expected words — review before delivery. ``` When you see the warning, open the file and check it before delivering. ## Adjusting or turning it off The check is configured in your `settings.json` file, under an `"export"` section: | Key | Default | Meaning | | ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `word_count_check_enabled` | `true` | Set to `false` to turn the check off entirely. | | `word_count_check_threshold` | `0.95` | Warn when the exported file has fewer than this fraction of the expected words. Raise it (e.g. `0.99`) for more sensitivity, lower it to tolerate larger differences. | ```json { "export": { "word_count_check_enabled": true, "word_count_check_threshold": 0.95 } } ``` If your documents legitimately differ a lot from the segment word count – for example they contain many numbers, or comments that aren’t part of the translation – you may prefer to lower the threshold slightly to avoid false alarms. Caution The check currently applies to **DOCX exports only**. Other Okapi formats (IDML, HTML, XLIFF, PPTX, XLSX, PO) are not yet verified this way. ## Related pages * [Exporting Translations](/workbench/import-export/exporting/) * [Multi-File Projects](/workbench/import-export/multi-file/) * [Supported File Formats](/workbench/import-export/formats/) # Exporting Translations When you’re done translating, export in a format that matches your workflow. ## Export steps 1. Go to **Project → Export** 2. Choose an export type (for example DOCX, bilingual table, or a CAT return format) 3. Pick a destination and save ## CAT tool round-trips If you started from a CAT exchange format (memoQ/Trados/Phrase/CafeTran), export the matching return format. ### Important rules for round-trips * **Segment count must match**: don’t merge or split segments. * **Keep tags balanced**: for example `text` (not `text`). * **Don’t “pretty edit” bilingual tables**: changing the table structure in Word can break reimport. * Run your CAT tool’s QA after reimport. Caution Don’t merge or split segments in Supervertaler when you plan to reimport into a CAT tool. ## Choosing the right export * For CAT tool workflows, use the matching CAT export: * memoQ bilingual DOCX * Trados return package (SDLRPX) when you imported SDLPPX * Phrase bilingual DOCX * CafeTran bilingual table DOCX * For review-only delivery, consider [Bilingual Tables](/workbench/import-export/bilingual-tables/). ## Checking the export After every DOCX export, Supervertaler automatically compares the word count of the exported file against your translated segments and warns you if text looks like it was dropped. See [Export Verification (Word-Count Check)](/workbench/import-export/export-verification/). ## Related pages * [Supported File Formats](/workbench/import-export/formats/) * [Export Verification (Word-Count Check)](/workbench/import-export/export-verification/) * [Bilingual Tables](/workbench/import-export/bilingual-tables/) * [CAT Tool Overview](/workbench/cat-tools/overview/) # Supported File Formats Supervertaler can import and export several formats depending on your workflow. ## Standard documents * **DOCX** (Microsoft Word): import a document, translate in the grid, export a translated DOCX. * **TXT** (plain text): each line becomes a segment. ## Other formats via Okapi The bundled **Okapi sidecar** lets Supervertaler round-trip a wider set of formats. Pick a file in any of the following types via **Project → Import → Import Document…**, translate in the grid, then **Project → Export → Export Translated Document…** to write a translated file back in the same format: | Format | Extension(s) | Notes | | ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Adobe InDesign Markup** | `.idml` | Drop in, translate, drop out – no need to round-trip via Trados/memoQ first. Inline tags appear as `...` markers in the grid; preserve them in the translation. | | **HTML** | `.html`, `.htm` | Anchors, images, buttons, and other inline elements are exposed as `...` / `` tags. The translated HTML reconstructs the original markup byte-perfectly. | | **XLIFF 1.2** | `.xliff`, `.xlf` | The industry-standard bilingual interchange format. Useful for files exported from any CAT tool that doesn’t have its own dedicated entry. | | **gettext PO** | `.po` | Source strings are translated; `msgctxt` and plural forms are preserved. | | **Microsoft Excel** | `.xlsx` | Cells, formulas, and styling round-trip via the Office Open XML filter. | | **Microsoft PowerPoint** | `.pptx` | Slides and slide notes are extracted; layout and master slides round-trip. | ### How it works Okapi extracts the translatable content from the source file plus a *skeleton* file that preserves the original structure. You translate the extracted content; the merge step combines your translation with the skeleton to reconstruct the original format with the new text in place. ## CAT tool exchange formats Use these formats when you need to round-trip back into a CAT tool. * **memoQ** * Bilingual DOCX * XLIFF (memoQ export) * **Trados Studio** * Packages: `.sdlppx` import → `.sdlrpx` return (recommended) * Bilingual Review DOCX (special workflow) * **Phrase (Memsource)** * Bilingual DOCX * **CafeTran Espresso** * Bilingual DOCX table ## Multi-file projects * **Folder import (Multiple Files)**: import a folder containing DOCX/TXT files into a single multi-file project. Caution For CAT tool round-trips, always import and export the matching CAT format. Mixing formats can break tags/statuses on reimport. ## Related pages * [Importing DOCX Files](/workbench/import-export/docx-import/) * [Importing Text Files](/workbench/import-export/txt-import/) * [Multi-File Projects](/workbench/import-export/multi-file/) * [Exporting Translations](/workbench/import-export/exporting/) * [Bilingual Tables](/workbench/import-export/bilingual-tables/) # Import Options (File Types) When you import an Office document (Word, Excel or PowerPoint), Supervertaler uses the bundled **Okapi sidecar** to decide which parts of the file become translatable segments. The **File Types** options let you control that – so you can pull in (or leave out) things like comments, hidden text, headers and footers, and speaker notes. ## Where to set them There are two places, and they work together: * **Settings → 📄 File Types** – your **defaults**, applied to every import. Tick a box, and it’s saved straight away. Use **Restore defaults** to go back to the recommended set. * **The import dialog** – when you import a single document or a folder, the same options appear there, pre-filled from your defaults. Any change you make applies to **that import only**, overriding the default without changing it. ## Word (DOCX) | Option | What it does | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Comments** | How to handle Word review comments. **Skip** (default) leaves them out. **Import as comments** brings them in as real comments – anchored to the relevant segment where possible (otherwise to the top of the document), tagged with the original reviewer’s name so they’re easy to tell from your own. These are shown for context and are *not* re-exported (the originals stay in the file). **Import as translatable text** brings each comment in as a segment to translate (labelled “Cmt” in the Type column); those *are* written back on export. | | **Import hidden text** | Include text formatted as hidden. Off by default. | | **Import headers & footers** | Include page headers and footers. On by default. | | **Import document properties** | Include title, author, keywords and similar metadata. Off by default. | | **Skip drawing/shape names** | Leave out the auto-generated object names Word gives every shape and group (for example *Shape 16*, *Group 574248*). On by default – these are not real content and would otherwise clutter the grid. | | **Accept tracked changes** | Use the final, accepted text of any tracked changes. On by default. | ## Excel (XLSX) | Option | What it does | | ------------------------------------- | --------------------------------------------------------------- | | **Import hidden rows/columns/sheets** | Include content that is hidden in the workbook. Off by default. | | **Import sheet (tab) names** | Include the worksheet tab names. Off by default. | | **Import text in shapes/text boxes** | Include text drawn on the sheet. On by default. | ## PowerPoint (PPTX) | Option | What it does | | ---------------------------------- | ----------------------------------------------------- | | **Import speaker notes** | Include the notes beneath each slide. Off by default. | | **Import comments** | Include review comments. Off by default. | | **Import hidden slides** | Include slides marked hidden. Off by default. | | **Import slide masters / layouts** | Include text on masters and layouts. On by default. | ## How imported parts are labelled Anything that isn’t ordinary body text is tagged in the grid’s **Type** column so you can tell at a glance where it came from: * **Cmt** – a comment * **Hdr** / **Ftr** – a header or footer * **Prop** – a document property * **Note** – a PowerPoint speaker note ## Round-trip on export The options you import with are remembered with the project and reused when you export. That keeps the document structure aligned, so the translated file comes back out cleanly – there’s nothing extra to set at export time. # Multi-File Projects Multi-file projects let you import a whole folder of files as a single Supervertaler project. ## Import a folder 1. Go to **Project → Import → Folder (Multiple Files)…** 2. Choose a folder containing supported files (DOCX/TXT/MD) 3. Select which files to include 4. Choose the **source** and **target** languages ## How it behaves * All segments live in one grid, but each segment is associated with a source file. * You can jump between files and track progress per file. * Each DOCX file is imported via the **Okapi sidecar** (the same engine that handles single-file DOCX import) – you get SRX segmentation, faithful round-trip, and hyperlinks/structural tags preserved per file. * TXT and MD files use the simple per-line import. * Original files are backed up to a `_source_files/` folder inside the project folder so the export can reconstruct each document faithfully. ## Export When you export a multi-file project: * Each DOCX file is reconstructed via the Okapi sidecar’s `/merge` endpoint, using the original from `_source_files/` as the template. Layout, formatting, hyperlinks, and tables round-trip identically. * TXT/MD files are written with the same per-line structure as the source. * Output files land in the destination folder you choose, named `_translated.`. ## Tips * Use this when you receive a set of related files (e.g. claim documents, manual chapters split into separate files, UI strings split across documents). * Export is done in one operation – pick the destination folder and Supervertaler writes all the translated files at once. ## Requirements * The Okapi sidecar must be running before you import any folder containing DOCX files. Supervertaler checks this up-front and shows an “Okapi sidecar required” dialogue if it can’t reach the sidecar – better than failing halfway through importing twenty files. # The Project Folder A Supervertaler project isn’t just the `.svproj` file — it’s a **folder** that holds the project file together with the documents it works on. Keeping everything in one folder means a project is self-contained: you can move, rename, zip or email the folder and it still opens and exports correctly. ## What’s in a project folder ```plaintext My Project/ ├─ My Project.svproj ← the project file ├─ source/ ← the original documents you're translating └─ target/ ← the translated documents you export ``` * **`source/`** — when you **save** a project, its original document is copied here, and the project remembers it by a path *relative* to the folder. That’s what makes the project portable: it no longer depends on the document staying at the exact location you first imported it from. Move or rename the original afterwards and your export still works. * **`target/`** — when you run **Project → Export → Export Translated Document** (or Simple Text), the Save dialog opens here by default, so your finished translations land next to their sources. You can still browse somewhere else; this is only the default. ## Why this matters * **Portability** — hand the whole folder to a colleague, or move it between machines, and the structure-preserving export keeps working. Nothing points at a file that only exists on your computer. * **No accidental cross-wiring** — because the source is stored relative to the project folder, a project can never end up bound to an unrelated document. ## Existing projects Projects created before this layout existed still work — they reference their source by an absolute path, and Supervertaler resolves it as before. The next time you **save** such a project, its source is copied into `source/` and the reference switches to the portable relative form automatically. ## Related pages * [Exporting Translations](/workbench/import-export/exporting/) * [Your First Translation Project](/workbench/get-started/first-project/) * [Multi-File Projects](/workbench/import-export/multi-file/) # Pseudo-translation (Export Test) **Pseudo-translation** fills your targets with deliberately stress-tested placeholder text so you can export the document and check that it comes out with correct formatting, layout, fonts and tags — **before** you invest any time in real translation. It’s a pre-flight check borrowed from desktop CAT tools. Find it under **Bulk Operations → 🧪 Pseudo-translate (Export Test)…**. ## Why not just copy source to target? Copying source into target and exporting tests the *plumbing* — does the file merge and export, do the inline tags survive — but it misses the problems that actually bite at the end of a job: * **Length stays identical**, so overflowing text boxes, clipped table cells, fixed-width fields, reflow and truncation never show up. Real translations change length. * **Characters are never exercised** — the source already renders fine in the document’s fonts and encoding, so copying it tells you nothing about whether the *target* language’s characters will. * **Dropped or merged segments stay invisible**, because target text that equals the source still looks correct. Pseudo-translation addresses all three at once. ## What it does For every segment in the chosen scope it rewrites the target so that: 1. **Inline tags are preserved exactly.** Formatting tags (``, ``, …), Trados/SDLXLIFF numeric tags (`<410>`) and memoQ tags are kept verbatim and in order — only the words between them are changed. This is what makes the test trustworthy: the tag round-trip you’re checking isn’t disturbed. 2. **The text is length-expanded** by a ratio you choose, to surface overflow and layout breaks. 3. **Characters are optionally accented** (`werkwijze` → `wéřkwíjžé`) to test diacritics, encoding and font coverage. 4. **Each segment is wrapped in `⟦ ⟧` markers** so a dropped, merged or misplaced segment is obvious in the exported file. A segment like ```plaintext De uitvinding betreft een werkwijze voor het sorteren. ``` becomes something like ```plaintext ⟦Dé úítvíñdíñğ bétřéft ééñ lorem wéřkwíjžé lorem vóóř hét šóřtéřéñ. lorem⟧ ``` ## Options | Option | What it controls | | -------------------- | --------------------------------------------------------------------------- | | **Apply to** | All segments (default), the filtered/visible set, or just your selection. | | **Length expansion** | 0% (structure only), +30% (typical), up to +200% (max stress). | | **Characters** | *Accented* (tests encoding/fonts) or *Plain words* (length + markers only). | | **Boundary markers** | Wrap each segment in `⟦ ⟧`. On by default. | ## Workflow 1. Open the project and run **Bulk Operations → 🧪 Pseudo-translate (Export Test)…**. 2. Pick your options and confirm. 3. Export the document the way you normally would (**Project → Export → Export Translated Document**, or any bilingual/CAT export) and open the result. 4. Check for clipped text, broken tables, missing glyphs, reordered or missing `⟦ ⟧`-marked segments, or tag errors. 5. **Edit → Undo** restores your real (usually empty) targets — the whole operation is recorded as a single reversible step. ## Related * [Export Verification (Word-Count Check)](/workbench/import-export/export-verification/) * [Exporting Translations](/workbench/import-export/exporting/) * [Re-importable Table (DOCX)](/workbench/import-export/bilingual-tables/) # Importing Text Files Text import is the simplest workflow: **each line becomes one segment**. ## Import steps 1. Go to **Project → Import → Text / Markdown File (TXT, MD)…** 2. Select your `.txt` file 3. Choose the **source** and **target** languages ## Tips * Keep one sentence (or one logical unit) per line for best results. * If your file has encoding issues (weird characters), try saving it as UTF-8. ## Export Text projects can be exported as: * Translated TXT * DOCX * Bilingual table # Non-Translatables Non-translatables are terms you want to keep unchanged (product names, IDs, codes, etc.). ## What you can do * Maintain a list of non-translatable terms * Highlight them in the grid * Reduce accidental changes during editing ## Tips * Add non-translatables before batch translation for best results. * Use them for brand names, UI strings, and technical identifiers. # AI Proofreading **AI Proofreading** asks an LLM to review your finished translation for accuracy, completeness, terminology and style, and records what it finds as **proofreading comments** on each segment. It’s a translator-side review pass — nothing is changed automatically; you read the feedback and decide what to act on. Proofreading lives under the top-level **QA** menu: * **QA ▸ Proofreading ▸ Proofread Translation…** — run a proofreading pass. * **QA ▸ Proofreading ▸ Delete All Proofreading Comments** — clear every proofreading comment in the project. ## Running a proofreading pass Open **QA ▸ Proofreading ▸ Proofread Translation…**. The dialog has three things to set: ### 1. Which segments | Scope | What it checks | | -------------------------------- | ------------------------------------------------------------------------ | | **✅ Confirmed only** *(default)* | Only segments you’ve confirmed. | | **📝 Translated + Confirmed** | Draft *and* confirmed segments. | | **🔹 Selected** | The rows you’ve selected in the grid (select rows first to enable this). | | **🌐 All segments** | Every segment, regardless of status. | ### 2. Which model Proofreading uses your **currently-active AI provider and model** (set in **AI Settings**) — the dialog shows which one, e.g. `📊 Using: Openai (gpt-5.5)`. To proofread with a *different* model, switch the active provider in AI Settings and run the pass again (see [Multiple models](#multiple-models) below). ### 3. Which prompt * **Default (built-in)** runs the standard four-point check: 1. **Accuracy** — does the target correctly convey the source meaning? 2. **Completeness** — is anything missing or added? 3. **Terminology** — are technical terms correct and consistent? 4. **Grammar & Style** — is the text natural and error-free? * Or pick a **custom proofreading prompt** from the dropdown — any prompt you’ve saved under the **Bulk Operations/** folder of your [Prompt Library](/workbench/ai-translation/prompt-library/) appears here. * Or **type a one-off prompt** straight into the box. Click **Proofread** to start. A progress dialog shows how many segments have been checked, how many issues were found, and how many came back clean; you can cancel partway through. ## Where the results appear Findings land in the **✅ Proofreading** sub-tab of the **💬 Comments** panel — an all-project list of every proofreading comment, one entry per (segment, model). See [Comments → Proofreading comments](/workbench/editor/comments/#proofreading-comments) for the full rundown. In short: * Each entry has a clickable **Segment #N · model** header that jumps to the segment. * Selecting a segment in the grid **scrolls and highlights** the list to that segment’s comments. * A **🗑️** button deletes a single comment; **QA ▸ Proofreading ▸ Delete All Proofreading Comments** clears them all. * In the grid, a segment with a proofreading comment shows a **purple** Status-cell background (versus **amber** for a segment comment, and a **split** when it has both). ## Multiple models Results are stored **keyed by model**, so passes with different models *accumulate* rather than overwrite: proofread once with GPT and once with Claude, and each segment keeps both sets of findings. In the Proofreading list **each engine gets its own colour**, so you can compare at a glance what each model flagged. Running the same model again replaces only that model’s note. ## Good to know * **Proofreading comments are ephemeral review notes.** They’re stored in the `.svproj` project file but are **not exported** to your final document or bilingual tables — unlike [segment comments](/workbench/editor/comments/), which do export as Word comments. Deleting them is safe: another proofreading pass regenerates them. * Proofreading is **read-only feedback** — it never edits your target text for you. * Cost scales with scope and model. Proofreading every segment with a premium model on a large project is a real API spend; the **Confirmed only** default keeps a first pass focused. See [Usage & Costs](/workbench/ai-translation/usage-costs/). ## Related * [Comments](/workbench/editor/comments/) — where proofreading comments are listed and managed * [Spellcheck](/workbench/qa/spellcheck/) · [Tag Validation](/workbench/qa/tag-validation/) · [Non-Translatables](/workbench/qa/non-translatables/) * [Prompt Library](/workbench/ai-translation/prompt-library/) — save custom proofreading prompts * [Usage & Costs](/workbench/ai-translation/usage-costs/) # Spellcheck Supervertaler includes a powerful spellcheck system that highlights misspellings while you translate, with support for regional language variants. ## How It Works Supervertaler uses a **three-tier spellcheck system** that automatically selects the best available backend: | Backend | Description | Languages | | ------------------------- | ---------------------------------------------- | ------------------------------------------------- | | **Hunspell (cyhunspell)** | Native C library, best accuracy | Any language with .dic/.aff files | | **Spylls** | Pure Python Hunspell (recommended for Windows) | Bundled: EN, RU, SV + any .dic/.aff files you add | | **pyspellchecker** | Built-in fallback | EN, NL, DE, FR, ES, PT, IT, RU | The system automatically falls back through backends: Hunspell → Spylls → pyspellchecker. ## Features * **Red wavy underlines** for misspelled words in the translation grid * **Right-click context menu** with spelling suggestions * **Add to Dictionary** – Save a word permanently * **Ignore** – Skip a word for the current session only * **Regional variants** – Distinguish between en\_US “color” and en\_GB “colour” ## Language Variants Supervertaler supports regional language variants. The spellcheck dropdown shows variants like: * English (US), English (GB), English (AU), English (CA), English (ZA) * Portuguese (PT), Portuguese (BR) * Spanish (ES), Spanish (MX), Spanish (AR) * French (FR), French (CA), French (BE) * German (DE), German (AT), German (CH) * Dutch (NL), Dutch (BE) ## Spellcheck Info Dialog Access detailed information about your spellcheck setup: 1. Click the **🔤 Spellcheck** button in the grid toolbar 2. Or go to **View → Spellcheck Info** The dialog shows: * Current language and backend * Available languages * Diagnostic information (which backends are available/initialized) * Links to download additional dictionaries * Custom dictionary word count ## Adding More Dictionaries To add spellcheck support for additional languages or variants: 1. **Download Hunspell dictionaries** (.dic and .aff files) from: * [hunspell.memoq.com](https://hunspell.memoq.com/) – 70+ languages * [GitHub: wooorm/dictionaries](https://github.com/wooorm/dictionaries/tree/main/dictionaries) – 92+ languages * [LibreOffice Extensions](https://extensions.libreoffice.org/?Tags%5B%5D=50) – Rename .oxt to .zip 2. **Extract the files** – You need both `.dic` and `.aff` files (e.g., `nl_NL.dic` and `nl_NL.aff`) 3. **Place them in the dictionaries folder:** * Open Supervertaler * Go to Spellcheck Info dialog * Click ”📁 Open Dictionaries Folder” * Copy your .dic and .aff files there * You can also organize in subfolders (e.g., `dictionaries/en/en_GB.dic`) 4. **Restart Supervertaler** – The new language will appear in the dropdown ## Custom Dictionary You can add words that Supervertaler should always accept: * **Right-click a “misspelled” word** → **Add to Dictionary** * Or manually edit `user_data/dictionaries/custom_words.txt` Custom words are stored permanently and apply to all languages. ## Troubleshooting ### Spellcheck not working? 1. **Check the language** – Make sure the correct language variant is selected 2. **Check the backend** – Open Spellcheck Info to see which backend is active 3. **Missing dictionaries** – Some languages require manual dictionary installation ### Wrong language variant? If you need British English but only have US English: 1. Download `en_GB.dic` and `en_GB.aff` from one of the dictionary sources 2. Place them in your dictionaries folder 3. Select “English (GB)” from the dropdown ### Linux crashes? On Linux, some Hunspell configurations can cause crashes. Try: * Installing proper Hunspell dictionaries: `sudo apt install hunspell-` (e.g., `hunspell-pl` for Polish) * Temporarily disabling spellcheck in Settings → View Settings * See [Linux-Specific Issues](/workbench/troubleshooting/linux/) for more details ## Technical Details For developers and advanced users: | Project | Description | | ----------------------------------------------------------- | ----------------------------------- | | [pyspellchecker](https://github.com/barrust/pyspellchecker) | Built-in word frequency spellcheck | | [spylls](https://github.com/zverok/spylls) | Pure Python Hunspell implementation | | [Hunspell](http://hunspell.github.io/) | Original C/C++ spellcheck library | The spellcheck manager is located in `modules/spellcheck_manager.py` and provides: * Automatic backend selection * Dictionary file detection (including subdirectories) * Word caching for performance * Custom dictionary management # Tag Validation When working with formatted documents or CAT tool files, **tags must be preserved**. ## Why tags matter Tags represent formatting or placeholders. If tags are missing or unbalanced, reimporting into your CAT tool can fail or formatting may be lost. ## Tag display modes Supervertaler supports two ways of viewing formatting: * **WYSIWYG mode**: shows *bold/italic/underline* as formatting * **Tag view**: shows the raw markup (for example `...`) Use **Tag view** when you are preparing to export/reimport and you want to verify the raw tags. ## Supported formatting tags These tags are commonly used in Supervertaler projects: | Tag | Meaning | | ---------------- | ------------- | | `...` | Bold | | `...` | Italic | | `...` | Underline | | `...` | Bold + Italic | | `<sub>...</sub>` | Subscript | | `<sup>...</sup>` | Superscript | ## CAT tool placeholder tags CAT tools use placeholders/tags that must be preserved exactly: | CAT tool | Examples | | ------------------ | ------------------------------------- | | memoQ | `{1}`, `[2}...{2]`, `{MQ}`, `{tspan}` | | Trados Studio | `<1>`, ``, `<2/>` | | Phrase (Memsource) | `{1}`, `{2}` | ## Tips * Keep tags balanced (for example `text`, not `text`). * If you’re unsure, switch to Tag View and verify the raw tags. * Don’t change tag numbers or names (for example `{1}` → `{2}`), even if the translation “looks fine”. * If you insert a TM match, double-check that tags/placeholders still match the source. Caution For CAT tool workflows, don’t delete or edit placeholder tags unless you know exactly what they represent. # Custom MT endpoint A **Custom MT endpoint** lets you add your own OpenAI-compatible machine-translation service to QuickTrans, alongside the built-in engines (Google, DeepL, Microsoft, …). It is most useful for a **local MT proxy** – a small server that exposes several free MT engines behind a single OpenAI-compatible API – so you can query them all from Workbench without per-engine API keys. It is deliberately separate from the **AI custom endpoint** used for the AI Assistant chat, so you can run an MT proxy for quick lookups *and* point the AI chat at a different custom LLM at the same time. ## When to use it * You run (or have access to) an OpenAI-compatible endpoint that returns translations, e.g. a local MT proxy that maps a `model` name to a specific engine (`google`, `sogou`, `cnpat`, …). * You want fast, free MT in QuickTrans without configuring each engine’s official API key. * You want more than one such endpoint – for example a general proxy and a patent-specific one – each appearing as its own QuickTrans result. ## Set it up 1. Open **Workbench Settings → ⚡ QuickTrans**. 2. Under **MT engines**, tick **Custom MT endpoint (OpenAI-compatible)**. 3. Click **+** next to *Profile* and give the profile a name (e.g. `Local proxy`). 4. Fill in: * **Endpoint URL** – the OpenAI-compatible base URL, e.g. `http://127.0.0.1:1234/v1` * **Model / engine** – the model (or, for a multi-engine proxy, the engine name, e.g. `google`) * **API key** – only if your endpoint requires one; leave blank otherwise * **Show this profile in QuickTrans** – tick to include this profile as a QuickTrans result; untick to keep it configured but hidden 5. Click **💾 Save QuickTrans Settings**. Each profile that is enabled (**Show this profile in QuickTrans** ticked) and has an endpoint appears as its own result in the QuickTrans popup (summoned with **Ctrl+Alt+Q**). Add more profiles with **+** to expose several engines at once; remove one with **−**. ## Example: a local multi-engine MT proxy A common pattern is a small Python proxy that wraps free web MT engines and presents them as OpenAI “models”. Run it locally (e.g. on `http://127.0.0.1:1234`), then add a Custom MT profile per engine you want, setting **Model / engine** to the engine name the proxy expects. ## Free Dutch ↔ English engines (via a multi-engine proxy) If your proxy exposes several engines as “models”, set **Model / engine** to the engine’s key. For Dutch ↔ English, these work well: | Model / engine | Notes | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `google` | Reliable, fast. | | `microsoft_builtin` | Reliable; good Dutch. | | `modernmt_builtin` | Reliable. | | `lingvanex_builtin` | Works; quality varies. | | `deepl_builtin` | Free DeepL — excellent quality **when available**, but the free endpoint rate-limits aggressively (HTTP 429), so it may intermittently fall back to another engine. | China-focused engines (`sogou`, `transmart`, `niutrans`) and the patent engine `cnpat` are not recommended for Dutch ↔ English. ## Custom MT vs the AI custom endpoint | | Custom MT endpoint | AI custom endpoint | | ------------ | ---------------------------------- | ---------------------------------- | | Lives in | QuickTrans ▸ MT engines | AI Settings ▸ AI/LLM Providers | | Used for | Fast MT results in QuickTrans | AI Assistant chat & AI translation | | Independent? | Yes – configure both at once | Yes | | Profiles | Multiple, each a QuickTrans result | Multiple, one active at a time | # Machine Translation Machine translation is delivered by **QuickTrans** – an always-on-top popup (and dockable panel) with translations from every enabled provider. See [QuickTrans](/workbench/quicktrans/overview/) for the full reference. ## Opening QuickTrans | How | Notes | | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ctrl+Alt+Q** (⌘⌥Q on macOS) | Opens the QuickTrans always-on-top popup and starts the MT fan-out immediately on the selected text. Auto-copies the current selection so you don’t need a separate Ctrl+C first. | | Editor right-click → ⚡ QuickTrans | Right-click menu in the editor. | | **🔍 Run in SuperLookup** button in the popup header | After you’ve seen the QuickTrans results, click 🔍 to hand the same query off to Workbench’s SuperLookup tab for a richer concordance / termbase / web look-up. | ## Providers QuickTrans supports these MT providers (subject to your API keys and per-provider on/off flags): * DeepL * Google Translate * Microsoft Translator * Amazon Translate * ModernMT * MyMemory (free) Plus optional LLM-based “translation as suggestion” from Claude, OpenAI, Gemini, Mistral, DeepSeek, and a custom OpenAI-compatible endpoint or local Ollama model. ## Configure providers QuickTrans’s provider list and LLM model selectors live in **Workbench Settings → ⚡ QuickTrans**. Click the ⚙ cog icon in the QuickTrans popup header to jump there in one click. Per-provider on/off + LLM model choices persist in `general_settings.json` under `mt_quick_lookup`. ## Language behaviour * QuickTrans uses the active project’s language pair by default. * The popup has its own From / To dropdowns – override per-query without affecting your project settings. ## Performance Provider calls run in parallel (each with a 5 s timeout, overall batch capped at 6 s) so total wall-clock is roughly the slowest single provider, not the sum. Results appear in the popup as they arrive – the first to finish is auto-selected so you can hit Enter without waiting for the slow providers. ## Copying results * Successful results show a **📋 copy button**. * You can also **double-click** a result row to copy the translation. * Number keys **1**–**9** select the corresponding result (1 = first, 2 = second, etc.). # QuickTrans **QuickTrans** shows fast machine translations of the selected text from every enabled provider at once. It runs in two ways: * a **global always-on-top popup**, summoned with **Ctrl+Alt+Q** anywhere on your computer; and * a **docked panel** inside the Workbench grid – it can sit below, above, or to the right of the grid (beside TermLens), showing the same results inline as you move between segments. The rest of this page describes the popup. It’s a single-purpose surface – just translations, no chat – and it stays on top of every other window until you press 1–9 / Enter / click to pick a result, or Esc to dismiss.  ## Opening QuickTrans | Method | Shortcut | Notes | | ---------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Global, from any application | **Ctrl+Alt+Q** (⌘⌥Q on macOS) | Auto-copies the current selection; popup appears with translations | | In-app, from a Workbench grid cell | **Ctrl+Alt+Q** | Same chord – Ctrl+Alt+Q is registered both as a system-wide global hotkey *and* as an in-app QShortcut, so it works wherever you are | | Editor right-click → ⚡ QuickTrans | Right-click menu | Uses the selected text in the cell (or the full cell text if no selection) | After selecting a translation from the global path (Ctrl+Alt+Q from another app), the popup hides itself, returns focus to the source application, and pastes the result over your selection. When invoked in-app, selecting a translation inserts it at the cursor position in the focused grid cell. ## The popup header A row of three controls runs along the top of the popup: * **⚡ Supervertaler QuickTrans** – title * **🔍 Run in SuperLookup** – closes the popup and opens Workbench’s SuperLookup tab with the same query pre-filled and the search auto-fired. Useful when you’ve translated a phrase via QuickTrans and then think “actually, I want to look this up in my TMs / termbases / web resources too” – one click instead of dismissing the popup and pasting the query again * **⚙ Settings** – opens Workbench Settings → ⚡ QuickTrans so you can enable / disable providers and pick LLM models ## Translation results Results arrive as they complete from each provider and are displayed in a numbered list. The first result to arrive is automatically selected, so for the typical “fast provider → press Enter” flow you don’t need to wait for the slow ones. | Method | Action | | ---------------------- | ------------------------------------------- | | **Press 1–9** | Insert the numbered translation immediately | | **Arrow keys + Enter** | Navigate and select | | **Click** | Insert the translation | | **Esc** | Dismiss the popup without inserting | Each translation row shows the provider name on the left and the translated text on the right. ## Supported providers QuickTrans queries up to eleven providers in parallel. Each one is independently enabled / disabled in **Workbench Settings → ⚡ QuickTrans**. **Machine translation engines** (each row needs an API key for that service, except MyMemory): | Engine | API key required? | | -------------------- | ----------------------- | | Google Translate | Yes | | DeepL | Yes | | Microsoft Translator | Yes | | Amazon Translate | Yes | | ModernMT | Yes | | MyMemory | No (free, rate-limited) | **LLM providers** (each row needs an API key for that service; reuses the keys configured in Settings → AI Settings): | Provider | Notes | | -------- | -------------------------------------------------------------------------------------- | | Claude | Pick the model in Settings → ⚡ QuickTrans (e.g. claude-haiku-4-5 vs claude-sonnet-4-6) | | OpenAI | Pick the model (e.g. gpt-5.4-mini vs gpt-5.5) | | Gemini | Pick the model | | Ollama | Local-only; uses the active Ollama model | | Custom | One configurable OpenAI-compatible endpoint (URL + model) | The LLM providers are **disabled by default** – tick them in Settings → ⚡ QuickTrans if you want LLM-based “translation as suggestion” alongside the MT engines. (Ticking all eleven makes for a slow popup; most users keep three or four MT engines plus one LLM.) ## Language pair QuickTrans uses **the active project’s source and target language**. There’s no per-query language override in the popup itself – set the language pair at the project level and QuickTrans inherits it. If no project is open, QuickTrans falls back to English → Dutch (the default for unconfigured installs). ## Configuring providers Open **Workbench → Settings → ⚡ QuickTrans** (or click the ⚙ cog in the popup header) to enable / disable individual providers and pick LLM models. The settings live in `general_settings.json` under the `mt_quick_lookup` key and persist across restarts. Tick a provider, save, then trigger Ctrl+Alt+Q again – the popup picks up the new provider list the next time it opens. ## Tips * **Ctrl+Alt+Q is the fastest way to translate** – select text anywhere, press the shortcut, results appear instantly. The synthetic Ctrl+C happens internally, so you don’t need to copy first. * **Use the 🔍 Run in SuperLookup hand-off** for terminology questions. QuickTrans is great for “how does this phrase translate?”, SuperLookup is great for “have I translated this term before? what does it mean? is it in a termbase?”. * **The popup lives on top of every other window**, so you can summon it from a browser, a PDF reader, your CAT tool, or anywhere – it overlays whatever’s foreground. * **Different from Chat.** QuickTrans gives you N parallel translations from N providers; the Chat tab in Workbench’s right panel is a conversational AI assistant. Use QuickTrans when you want options, Chat when you want a conversation. ## Customising the hotkey The QuickTrans chord can be rebound in **Settings → Keyboard Shortcuts**. The action is called *QuickTrans (instant translation popup)*, default **Ctrl+Alt+Q**. The same chord registers as both an in-app QShortcut and an OS-level global hotkey, so changing it once changes both. ## Related pages * [Machine Translation engines](/workbench/quicktrans/machine-translation/) * [Custom MT endpoint](/workbench/quicktrans/custom-mt-endpoint/) * [SuperLookup Overview](/workbench/superlookup/overview/) * [Keyboard Shortcuts](/workbench/settings/shortcuts/) # Changelog This page shows you where to find **what changed between versions** of Supervertaler. ## ✅ View the full changelog The complete changelog is maintained on GitHub: * [Open CHANGELOG.md on GitHub](https://github.com/Supervertaler/Supervertaler-Workbench/blob/main/CHANGELOG.md) ## What you’ll find there * New features and improvements (what was added) * Bug fixes (what was corrected) * Version numbers and release dates ## Tip If you’re troubleshooting, start by checking whether your issue was already fixed in a newer version. # Contributing Contributions are welcome – bug reports, documentation improvements, and code changes. ## Where to start * Report issues: * Questions / discussion: ## Documentation edits Supervertaler Help is synced from the repository. If you spot missing or unclear documentation, open an issue or submit a pull request. ## Tip When reporting a bug, include: * Your OS * Your Supervertaler version * Steps to reproduce * Any error message text # User Data Folder Supervertaler Workbench keeps your termbases, translation memories, prompt library, settings, and projects in a single user data folder. This folder is **shared with [Supervertaler for Trados](https://docs.supervertaler.com/trados/data-folder/)**, so both programs read and write the same terminology, TMs, and prompts without duplicating files. ## Folder location By default the folder lives in your home directory: ```plaintext Windows: C:\Users\\Supervertaler\ macOS / Linux: ~/Supervertaler/ ``` You can choose a different location during first-run setup. The chosen path is recorded in a small pointer file in your user configuration directory (on Windows, `%APPDATA%\Supervertaler\config.json`), which both programs read so they always agree on where the data lives. ## Folder structure ```plaintext Supervertaler/ │ ├── prompt_library/ Shared │ ├── domain_expertise/ │ ├── project_prompts/ │ └── style_guides/ │ ├── resources/ Shared │ ├── supervertaler.db │ ├── termbases/ │ ├── tms/ │ ├── non_translatables/ │ └── segmentation_rules/ │ ├── workbench/ Supervertaler Workbench only │ ├── settings/ │ │ ├── settings.json │ │ ├── themes.json │ │ ├── shortcuts.json │ │ └── ... │ ├── dictionaries/ │ ├── projects/ │ ├── ai_assistant/ │ ├── voice_scripts/ │ └── web_cache/ │ └── trados/ Supervertaler for Trados only ├── settings/ ├── projects/ └── batch_backups/ ``` ### Shared resources The **prompt library** and **resources** folders are shared between both programs. A prompt you create or edit in Workbench is immediately available in the Trados plugin, and vice versa. The SQLite database (`supervertaler.db`) holds your termbases and translation memories — Workbench has full read-write access to it. ### Program-specific folders Each program stores its own settings, projects, and runtime data in a dedicated subfolder (`workbench/` or `trados/`), so the two never interfere with each other. Workbench’s `workbench/` subfolder holds your `settings/` (including `shortcuts.json` and `themes.json`), custom spellcheck `dictionaries/`, saved `projects/`, AI assistant data, voice scripts, and a web cache. ## Automatic migration If you’re updating from an older version, Workbench reorganises the folder automatically on its next startup. No manual action is required — your settings and data are preserved. ## Related * [Supervertaler for Trados — User Data Folder](https://docs.supervertaler.com/trados/data-folder/) * [General Settings](/workbench/settings/general/) # AutoCorrect while typing Supervertaler can automatically convert straight quotes, three-dot ellipses, and double-hyphen dashes to the correct typographic forms **as you type in the target field**. Quote shapes follow the **target language** — German targets get `„…"`, French targets get `« … »`, Russian targets get `«…»`, English targets get `"…"`, and so on. This feature was requested in [discussion #211](https://github.com/orgs/Supervertaler/discussions/211) and ships from **v1.10.230**. ## Where to find it **Settings → ✍️ AutoCorrect** (its own tab in the Settings sidebar, just below General). The master switch enables or disables all rules at once. Each rule below it can also be toggled individually. This tab **saves automatically** — there is no Save button. Every toggle is written to your settings the moment you click it and takes effect on the **very next keystroke** — no app restart, no grid reload. ## Rules | Rule | Behaviour | Default | | --------------------------------- | --------------------------------------------------------- | ------------------------------------ | | Smart double quotes | `"foo"` → language-correct typographic pair | on | | Smart single quotes / apostrophes | `'foo'` → typographic single pair · `don't` → `don't` | on | | Ellipsis | `...` → `…` | on | | En-dash | `word-- word` → `word– word` | on | | Em-dash | `word--- word` → `word— word` | **off** (the project uses en-dashes) | | French typographic spacing | Insert a narrow non-breaking space before `:` `;` `!` `?` | on for `fr-*` targets | ## Quote shapes by target language The smart-quote rule reads your project’s target language and picks the appropriate shape: | Languages | Open | Close | | -------------------------------------------------------------------------------- | ---------------- | ---------------- | | English, Dutch, Portuguese, Turkish, Romanian, Danish | `"` | `"` | | German, Czech, Slovak, Slovenian, Croatian, Hungarian, Polish *(close uses `"`)* | `„` | `"` / `"` | | French | `« `(with NNBSP) | `»` (with NNBSP) | | Spanish, Italian, Russian, Ukrainian, Norwegian | `«` | `»` | | Swedish, Finnish | `"` | `"` | The engine decides between “open” and “close” shape from what immediately precedes the typed quote — whitespace or an opening bracket → open shape; a letter, digit or closing bracket → close shape. Tag markers (`{1}`, ``, `[2}`) are treated as transparent, so a quote opened straight after an inline tag still gets the opening shape. ## Backspace cancels the last conversion If AutoCorrect converts something you actually wanted to leave alone, press **Backspace immediately**. One Backspace restores your literal typing (the straight quote, the three dots, the double hyphen, etc.) — exactly as it works in Word and memoQ. The next keystroke clears that one-shot undo memory, so the safety net is only available for the conversion you just made. ## What AutoCorrect does *not* touch * **Inside tag markers** (`{1}`, `[2}`, ``). Auto-correcting inside a tag would corrupt the boundaries and break the round-trip back to your source format, so the engine skips these. * **Paste**. Pasting a block of text never triggers any rule — only single typed characters do. If you want the engine to clean up pasted text, do it explicitly with Find & Replace. * **Programmatic content** (loaded translations, MT/TM insertions, Copy Source → Target). Same reason — these aren’t user keystrokes. * **Dictation**. Voice-typed content arrives via a different input path and is not auto-corrected. * **The source column**. AutoCorrect is target-only. ## Turning a single rule off temporarily Use the per-rule toggles on the **Settings → ✍️ AutoCorrect** tab. Because the tab saves automatically, both the master switch and the per-rule checkboxes are honoured on the next keystroke without clicking anything else. There’s no per-segment override yet — if you want one in a future version, please open an issue. ## See also * [Settings → General](/workbench/settings/general/) * Tracking issue: [#213 — Typographic auto-convert / AutoCorrect-while-typing system](https://github.com/Supervertaler/Supervertaler-Workbench/issues/213) * Original request: [Discussion #211](https://github.com/orgs/Supervertaler/discussions/211) # Backup Supervertaler protects your work with two independent backup mechanisms, both on the **Settings → 💾 Backup** tab. Use the **?** button on that tab (or press **F1**) to return to this page. ## Auto Backup (time-based) Automatically saves the current project at a regular interval to guard against crashes and forgotten saves. * **Enable automatic backups** – turn the timer on or off. * **Backup interval** – how often to save, in minutes (default **5**, range 1–60). Each run saves the project file and exports a `_backup.tmx` alongside it. This **overwrites** the working files in place — it keeps the latest state current, but it is not a history you can step back through. For that, use timestamped backups below. ## Timestamped project backups (every N saves) Keeps **immutable, dated snapshots** of the project file (`.svproj`) so you can roll back to an earlier state — like a lightweight version history. * **Keep timestamped project backups** – enable or disable the feature. * **Back up every N saves** – how often a snapshot is taken, counted in save operations (default **1** = every save). Both manual saves (Ctrl+S) and the timed auto-backup above count toward N. * **Keep the last K backups** – how many snapshots to retain per project (default **100**). Older ones are pruned automatically. Snapshots are written to a dedicated folder under your user-data location: ```plaintext \workbench\backups\\_YYYYMMDD-HHMMSS.svproj ``` Use the **Open folder…** button on the Backup tab to jump straight there. ### Restoring a backup 1. Click **Open folder…** on the Backup tab (or browse to the path above). 2. Find the snapshot with the timestamp you want (filenames sort chronologically). 3. Copy it somewhere safe and rename it (e.g. drop the timestamp), then open it from **Project → Open**, or replace your current `.svproj` with it while Supervertaler is closed. ## Related * [General Settings](/workbench/settings/general/) # Fonts Font settings control the typeface and size used in the translation grid and the companion tabs. ## What you can change * **Font family** – any font installed on your system; the dropdown shows available fonts * **Font size** – point size for the grid; companion tabs use the same family at their own size * **Global UI font scale** – a single slider that scales every UI element (menus, tabs, settings, Chat panel, Clipboard history, SuperLookup, status bar) at once ## Choosing a font * For general translation work, a clear humanist sans-serif (Segoe UI, Inter, Calibri) keeps long sessions comfortable * For technical or code translation, a monospaced font (Consolas, JetBrains Mono) can help align numbers and symbols * For right-to-left languages (Arabic, Hebrew), choose a font with good RTL glyph coverage ## Global UI font scale (Retina / high-DPI displays) Settings → AI Settings → **🖥️ Global UI Font Scale** holds a single slider (50%–200%, default 100%) that scales the entire application UI – not just the grid. Useful when you find Qt’s defaults uncomfortably small on a MacBook Retina screen, a 4K monitor, or any high-DPI display. The slider covers: * The grid (segment numbers, type column, source and target text) * Companion tabs (Clipboard 3-column tree, SuperLookup web resources, Voice command table, Chat panel) * QuickTrans always-on-top popup * Tabs, settings panels, AI tools, status bar, menus * Termbase and TM panes Apply the change with the **Apply** button next to the slider; most areas update immediately. Lazy-constructed widgets (Clipboard, SuperLookup, Voice) pick up the new size when they are next opened, so switch away from a companion tab and back once after changing the slider. If you’ve also customised the grid font size (above), that value still applies on top of the scale – so a 12 pt grid font at 150% renders at 18 pt. Grid zoom (Ctrl+= / Ctrl+-) continues to work at any scale. ## Tips * Font changes apply immediately in the grid – no restart needed * If glyphs for a specific language appear as boxes, install a font with full Unicode coverage for that script (Noto Sans is a good all-rounder) * On a 4K or Retina display, try 125% or 150% UI scale before reaching for individual font-size sliders – it keeps every panel proportional * The QuickTrans popup’s header controls (🔍 Run in SuperLookup, ⚙ Settings) deliberately don’t scale with the slider, because they live in fixed-size buttons and scaling the glyph alone would overflow them ## Related pages * [View Settings](/workbench/settings/view/) * [Theme (Light/Dark Mode)](/workbench/settings/theme/) # General ## Where to find settings Open **Settings** from the main toolbar or the **View** menu. Settings are organised into tabs across the top of the settings panel. ## AI Settings * **Provider** – select OpenAI, Anthropic (Claude), Google Gemini, Mistral, or a custom OpenAI-compatible endpoint * **API key** – enter and save your key for the selected provider; keys are stored locally in your user data folder * **Model** – choose which model to use for AI translation and the Chat assistant * **Temperature** – controls how creative vs. literal the AI output is (lower = more consistent) * **Max tokens** – upper limit on response length See [Setting Up API Keys](/workbench/get-started/api-keys/) for step-by-step instructions. ## Project settings * **Default source language / target language** – pre-filled when creating new projects * **Autosave interval** – how often the current segment is saved automatically (in seconds); set to 0 to disable ## Voice settings The [🎤 Voice top tab](/workbench/voice/overview/) contains all voice command and dictation settings (engine, model, sensitivity, push-to-talk mode). They are not duplicated here – open the Voice tab directly to configure them. ## Related pages * [Setting Up API Keys](/workbench/get-started/api-keys/) * [AI Translation Overview](/workbench/ai-translation/overview/) * [Theme (Light/Dark Mode)](/workbench/settings/theme/) * [Keyboard Shortcuts](/workbench/settings/shortcuts/) # Language (UI Translation) Supervertaler Workbench can display its menus and settings labels in languages other than English. Translations are contributed by the community as **XLIFF 1.2** files – the industry-standard interchange format that every CAT tool reads natively. This page covers: * How to pick your display language * Which languages are currently available * How the translation files work (file location, format) * How to contribute a translation ## Picking your display language 1. Open **Settings → General → 🌐 Language**. 2. Use the **Display language** dropdown to choose a locale. 3. Click **OK** to close Settings. 4. **Restart Supervertaler** for the new language to take effect.  Settings → General → Language dropdown  The Workbench interface after picking a locale – here localised to Dutch ### Locale options | Entry | Meaning | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **System default** | Use whatever language your operating system reports. Falls back to English if no translation file exists for that locale. | | **English** | Source language – no translation file needed. | | Locales with a `.xlf` file | Use that translation. | | `[no translation yet]` | Locale code is recognised but no `.xlf` has been contributed yet. Picking it falls back to English. | If a locale is partially translated, the strings that *have* been translated are used; the rest fall through to English. Partial coverage is fine. ### Why a restart is required Most Supervertaler dialogs are hand-coded rather than built with Qt Designer, which means they don’t automatically refresh their text when the language changes mid-session. A restart is the simpler approach for v1; live language switching may come in a future version. ## Where the translation files live Each locale’s translation lives in a single `.xlf` file in the **`translations/`** folder: * **Installed Windows build:** alongside `Supervertaler.exe` (open the install folder, find `translations\`) * **From source:** in the repository root, `translations/` * **macOS:** inside the `.app` bundle at `Supervertaler.app/Contents/Resources/translations/` File names follow the pattern `supervertaler_.xlf`: ```plaintext translations/ ├── supervertaler_template.xlf <- source-only English template (auto-generated) ├── supervertaler_zh_CN.xlf <- Simplified Chinese ├── supervertaler_zh_TW.xlf <- Traditional Chinese ├── supervertaler_pl.xlf <- Polish └── ... ``` **You can drop a new locale’s `.xlf` into this folder manually** – the next launch will pick it up and the Language dropdown will offer it. No reinstall, no rebuild. ## What’s inside an XLIFF file? The format is standard **XLIFF 1.2** – the same format Workbench imports through **Project → Import → Import Document…** (using the XLIFF filter). Every CAT tool in regular use reads it natively. A `.xlf` file has one entry per translatable string. Each entry looks like this: ```xml &Project 项目(&P) SupervertalerQt Supervertaler.py 9698 ``` What each piece means: * **``** — the original English string. Never edit this. * **``** — your translation. Set the `state` attribute to `translated` (or `signed-off` / `final`) when you’re happy with it. Targets left as `state="needs-translation"` are skipped at runtime – Workbench shows the English source instead. * **``** — where the string appears in the UI. The `x-qt-context` value tells you the dialog/class; the `sourcefile` and `linenumber` are pointers into the source code (rarely needed for translation, but handy for troubleshooting). * **`&`** — XML-escaped `&`. The character marks the **next letter as a keyboard mnemonic** – `&Edit` becomes underlined **E**dit, activated by **Alt+E**. Translations should preserve mnemonics, often by putting them in parentheses (`编辑(&E)` for Chinese). ## How to contribute a translation The whole flow is designed so you can use whichever CAT tool you already work in. No new tooling required. ### Quick version 1. Grab `translations/supervertaler_template.xlf` from the [GitHub repo](https://github.com/Supervertaler/Supervertaler-Workbench/tree/main/translations). 2. Save a copy as `supervertaler_.xlf` (for example `supervertaler_de.xlf` for German). 3. Open it in your CAT tool (Trados, memoQ, Phrase, OmegaT, or Workbench itself). 4. Set the target language on the `` element (`target-language="de"` for German). Most CAT tools do this for you when they ask which target language you’re translating into. 5. Translate the strings. Mark each as **confirmed/translated/approved** in your tool – this sets the `state="translated"` attribute behind the scenes. 6. Save / export back to XLIFF. 7. Open a PR on the [Supervertaler-Workbench repo](https://github.com/Supervertaler/Supervertaler-Workbench/pulls) adding your `.xlf` file under `translations/`. ### CAT-tool specifics **Workbench itself:** Project → Import → **Import Document…** and choose the generic XLIFF filter (not SDLXLIFF or MQXLIFF). Translate in the editor, then export back via Project → Export → **Export Translated Document…**. **Trados Studio:** File → Open → Translate Single Document → select the `.xlf`. Studio recognises XLIFF 1.2 out of the box. Save Target As to export. **memoQ:** Project → Import documents → select the `.xlf`. Use the standard XLIFF filter. **Phrase TMS:** Upload as a regular bilingual file. **OmegaT:** Drop into the project’s `source/` folder. OmegaT outputs the completed file to `target/`. **Poedit:** Although Poedit is best-known for `.po` files, recent versions also handle `.xlf` natively. ### Notes for translators * **Mnemonics (`&letter`)** mark keyboard accelerators. Preserve them in the translation. Place them where the underlined letter feels natural in your language. For Chinese / Japanese / Korean, the convention is to put the mnemonic in parentheses after the term: `编辑(&E)`. * **Avoid mnemonic collisions** within the same menu. Two items both using `&S` will cause one to silently lose the shortcut. * **Emoji** (📁 🔍 ⚙️ etc.) stay in the translation – they’re part of the visual identity. * **Newlines (`\n`)** in source strings should be preserved. * **Placeholders** like `{0}` or `%1` are not in this MVP’s strings, but if you see one, leave it verbatim. ## How translations are picked up Each launch, Supervertaler: 1. Reads `general.ui_locale` from the unified `settings.json`. 2. Resolves `"system"` to the operating system’s locale via Qt’s `QLocale.system()`. 3. Looks for `translations/supervertaler_.xlf` next to the executable. 4. Parses the XLIFF, collects all `` entries whose `` is in a “done” state (`translated`, `signed-off`, `final`, or stateless). 5. Installs a `QTranslator` on the QApplication so every `tr()` call resolves through that dictionary. 6. If the file is missing, the locale has zero finished translations, or the locale is `en` / unknown – English is used silently. Total cost at startup: about 10 ms. Negligible against the rest of the cold-start. ## Troubleshooting **The dropdown shows my locale as `[no translation yet]` even though I added the file.** Make sure the file: * Lives in `translations/` (next to `Supervertaler.exe`, or in the source-tree root) * Is named `supervertaler_.xlf` exactly – matching the locale code in the dropdown (case-sensitive) * Is valid XML (a single missing `` will fail the load silently) **The dropdown picks the right locale, but the menu still shows English.** Check that: * Each `` element has `state="translated"` (or `signed-off` / `final`), not `state="needs-translation"` * The `` actually contains text, not just whitespace * The `` text matches the codebase exactly (case, punctuation, spaces, emoji) * You’ve actually restarted Supervertaler **XML parse errors at startup.** Open the `.xlf` in a text editor. Common causes: * Unescaped `&` in a translation – use `&` instead * Mismatched `<` / `>` in a translation – use `<` and `>` * A CAT tool reordered elements in a way Workbench doesn’t expect Open an issue with the `i18n` label on the [Workbench tracker](https://github.com/Supervertaler/Supervertaler-Workbench/issues) and attach the failing `.xlf`. ## See also * [`translations/TRANSLATING.md`](https://github.com/Supervertaler/Supervertaler-Workbench/blob/main/translations/TRANSLATING.md) – the in-repo contributor guide with extra detail * [General Settings](/workbench/settings/general/) – the parent Settings tab * Tracker issues [#178](https://github.com/Supervertaler/Supervertaler-Workbench/issues/178) and [#190](https://github.com/Supervertaler/Supervertaler-Workbench/issues/190) – the original i18n requests # Customising Shortcuts Supervertaler has one keyboard shortcut per action. The same combination works whether Supervertaler is the focused application or whether you trigger it from another app – there’s no longer a separate “Global” entry to keep in sync with the in-app one. ## Managing shortcuts Open **Settings → Keyboard Shortcuts**. Each row is one action. Click a row to edit, press the new combination, hit OK. Changes apply immediately – no restart needed. Rows whose action label starts with 🌍 also register as an OS-level global hotkey, so they fire from any application. The rest are in-app only (e.g. segment navigation, match insertion). ## Default shortcuts that work everywhere The 🌍 actions and their out-of-the-box bindings: | Action | Default | Notes | | ------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Open Clipboard | **Ctrl+Alt+C** (Win/Linux) / **⌘⌥C** (macOS) | Auto-copies the current selection, then opens Workbench’s Clipboard tab | | Open SuperLookup | **Ctrl+Alt+L** / **⌘⌥L** | Auto-copies the current selection, then opens Workbench’s SuperLookup tab with the text pre-filled and the search auto-fired | | QuickTrans | **Ctrl+Alt+Q** / **⌘⌥Q** | Instant translation popup; auto-copies the selection | | Voice dictation / push-to-talk | **Ctrl+Shift+Space** / **⌘⇧Space** | Toggles recording; a ”🎤 Listening…” toast confirms the mic is live | | Voice Always-On (toggle) | **Ctrl+Alt+A** / **⌘⌥A** | Continuous listening on/off | Rebind any of these in **Settings → Keyboard Shortcuts** by clicking the row and pressing a new combination. ## macOS vs Windows: symbols and modifier names The two platforms use different conventions for naming and drawing modifier keys. Supervertaler shows the platform-native symbols in the UI, but it’s useful to know what each one means: | Symbol | macOS name | Windows / Linux name | Physical key | | ------ | -------------- | -------------------- | ------------------------------------------ | | **⌘** | Command (Cmd) | – | The key with the Apple/Command glyph | | **⌃** | Control (Ctrl) | Ctrl | The Control key | | **⌥** | Option (Opt) | Alt | The Alt key (top of the Option key on Mac) | | **⇧** | Shift | Shift | The Shift key | So a shortcut shown as **⌃⌘L** on macOS is read “Control + Command + L”. See the next section for how Supervertaler stores that internally and why the stored name doesn’t always match the Mac symbol. ## What “Ctrl” means inside Supervertaler Internally, shortcuts are stored in Qt’s cross-platform format, which uses **Ctrl**, **Alt**, **Shift**, and **Meta** as labels. Qt swaps **Ctrl** and **Meta** on macOS so that the same shortcut string works on every platform. The mapping: | Stored as… | …means on Windows / Linux | …means on macOS | | ---------- | ------------------------- | --------------- | | `Ctrl` | Ctrl | **Cmd** (⌘) | | `Alt` | Alt | **Option** (⌥) | | `Shift` | Shift | **Shift** (⇧) | | `Meta` | Windows key | **Control** (⌃) | You only ever see this if you export shortcuts to JSON or look at the cheatsheet HTML – the UI itself always shows you platform-native symbols on macOS and plain names on Windows. The default for SuperLookup is therefore stored as `Ctrl+Alt+L` and displayed as **Ctrl+Alt+L** on Windows and **⌘⌥L** on macOS, both of which fire the same physical chord on each platform. ## Per-platform notes **macOS** Global hotkeys require Accessibility permission on whichever binary launched Python: * Bundled `Supervertaler.app` → add **Supervertaler** in System Settings → Privacy & Security → Accessibility * Launched from `Terminal.app` → add **Terminal.app** instead * Launched from iTerm2 → add **iTerm2.app** instead Also requires the `pyobjc-framework-Cocoa` Python package (`pip install pyobjc-framework-Cocoa`); the bundled `.app` ships with it. The Status indicator on the right-hand side of Settings → Keyboard Shortcuts shows **Active (via NSEvent)** when global hotkeys are working on macOS. **Windows** Global hotkeys are registered via the native `RegisterHotKey` API, which consumes the keystroke at the OS level. The combination is reserved for Supervertaler whenever it’s running. If another app has already claimed the same combination, Supervertaler logs a `failed_hotkeys` warning and that one combination won’t fire – re-bind to something free in Settings → Keyboard Shortcuts. **Linux** Global hotkeys go through `pynput`, which uses XGrabKey under X11. If hotkeys silently don’t fire, your user may need to be in the `input` group (`sudo usermod -aG input $USER`, then log out and back in). ## Quick-lookup tab keyboard navigation When you’ve summoned the Clipboard, SuperLookup, or Voice tab via a global hotkey, these shortcuts work straight away – no clicking around to land your focus first: | Shortcut | Action | | --------- | ---------------------------------------------------------------------------------------------------------- | | **Esc** | Hide Workbench to the system tray (quick-lookup tabs only – Editor / Settings / etc. keep the natural Esc) | | **↑ / ↓** | Navigate within the focused column (e.g. clipboard text history, snippet list) | | **← / →** | Move focus between columns in the Clipboard tab (Text → Images → Menu) | | **Enter** | Activate the selected item (paste clip, run snippet, fire conversion) | ### Pressing Esc dismisses Workbench to the tray On the surfaces you summon with a global hotkey – SuperLookup, Clipboard, and Voice – pressing **Esc** hides Workbench back to the system tray. Handy when you’re using Workbench as a popup utility from another app: hotkey to summon, Esc to dismiss. * **On SuperLookup**: Esc unconditionally hides Workbench, even when the cursor is in the search box. SuperLookup is mostly a one-shot query, so there’s nothing worth keeping if you change your mind. * **On Clipboard and Voice**: Esc hides Workbench *unless* the focused widget is a text input (search field, command editor, etc.) – in those cases Esc behaves the way it does in any other app (clears the field, closes a dropdown, etc.). * **On Editor, TMs, Termbases, AI, Settings**: Esc keeps its natural editor / dialog / combo-box behaviour. Workbench is never hidden by accident from the surfaces where you actually do work. ### Tray quick-jump menu Right-click the Workbench tray icon (the orange **Sv**) for a menu with **Show Workbench**, **Open SuperLookup**, **Open Clipboard**, **Open Voice**, **Open Settings**, plus toggles for **Close to tray** and **Start with computer**. ## Editor shortcuts The editor (translation grid) has its own set of shortcuts for navigation, match insertion, term operations, and so on. See [Editor Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) for the full list. ## Exporting a printable cheatsheet The settings page has an **Export Cheatsheet (HTML)** button on the right-hand panel. It writes a self-contained HTML file showing every shortcut grouped by category, with the platform-native symbols already substituted in. Print it or save it as PDF. ## Related pages * [Editor Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) * [Voice Commands & Dictation](/workbench/voice/overview/) * [Clipboard Manager](/workbench/clipboard/overview/) # Termbase Settings The **Termbase settings** box (Settings → General) controls how termbase matches are displayed while you translate. ## Highlight termbase matches in source cells When enabled, termbase matches are highlighted with coloured backgrounds directly in the source column of the grid. Higher-priority terms are shown in darker blue, lower-priority terms in lighter blue – similar to memoQ’s termbase highlighting. This gives you instant visual feedback about which words in the source are covered by your termbases. ## Hide shorter termbase matches included in longer ones When enabled, shorter terms that are fully contained within a longer matched term are hidden from the results. For example, if both *cooling* and *cooling system* match, only *cooling system* is shown. This reduces clutter in the translation results panel when overlapping terms are present. # Theme Supervertaler supports light and dark themes. Switch between them in **Settings → Theme** or via the toolbar theme toggle. ## Why use Dark Mode * Better comfort in low-light environments * Reduced eye strain during long evening sessions * Lower screen brightness without sacrificing readability ## Switching themes The change takes effect immediately – no restart needed. All panels (grid, companion tabs, dialogs, popups) switch at once. ## Tips * If any UI element looks visually wrong after switching (rare Qt repaint quirk), try switching to a different tab and back, or restarting the app * Dark mode does not affect PDF Rescue’s OCR output or exported DOCX files — those are document colours, not UI colours ## Related pages * [View Settings](/workbench/settings/view/) * [Font Customisation](/workbench/settings/fonts/) # TM Settings The **TM settings** box (Settings → General) controls how translation memory matches are inserted and propagated as you work. ## Auto-fill empty segments with 100% TM matches When you select an empty segment that has a 100% TM match, its translation is filled in automatically. This saves time on repetitive content – exact matches appear without any manual action. * **↳ Mark auto-filled segments as confirmed** – when enabled, an auto-filled segment lands as **confirmed**. Otherwise the auto-filled translation is inserted as a **draft** for you to review. ## Auto-propagate confirmed translations to identical segments When you confirm a segment, its translation is copied to every other segment whose source text is identical. This is the memoQ/Trados-style propagate-on-confirm behaviour – translate a repeated sentence once, confirm it, and the rest of the document catches up automatically. By default, only **empty** identical segments are filled, and they are inserted as drafts. * **↳ Mark propagated segments as confirmed** – propagated segments land as **confirmed** instead of **draft**. * **↳ Overwrite existing translations when propagating** – propagation also replaces existing target content in identical segments. When disabled, only empty segments are filled. ## Auto-confirm 100% TM matches when navigating (Ctrl+Enter) When enabled, pressing **Ctrl+Enter** automatically inserts, confirms, and skips past any segment that has a 100% TM match, so you can move quickly through perfect matches. * **↳ Also overwrite existing translations with 100% TM matches** – auto-confirm also replaces existing target content (including pre-translations or machine translations) with the 100% match. ## TM Save Mode Controls what happens when the same source segment is saved to the TM more than once. * **Save all translations (with timestamps)** – keeps every version of a translation for a given source, with timestamps. The most recent translation is preferred when showing matches. * **Save only latest translation (overwrite)** – keeps only the most recent translation, overwriting older ones. This prevents the TM from growing with obsolete entries. *(Default.)* # View View settings control how the translation grid and the side panels look while you translate. ## Grid display * **Show invisibles** – reveals spaces, tabs, and line breaks as visible markers; useful for catching trailing whitespace * **Tag colour** – the highlight colour used for inline formatting tags (``, ``, etc.) * **Row height** – compact, normal, or spacious; affects how many segments you see at once without scrolling ## Right panel (Chat, matches) * **Right panel default width** – default width of the right-hand panel that hosts the Match Panel and the 💬 Chat tab. Can also be dragged at runtime; the width is remembered across sessions. ## Tips * If tags are hard to see, increase tag colour saturation or switch to **Tag View** (shows placeholder boxes instead of raw tag text). * For long sessions, try a slightly larger row height — it reduces eye strain when scanning for specific segments. * Dark mode is set in [Theme](/workbench/settings/theme/), not here. ## Related pages * [Theme (Light/Dark Mode)](/workbench/settings/theme/) * [Font Customisation](/workbench/settings/fonts/) * [Keyboard Shortcuts](/workbench/settings/shortcuts/) # Overview SuperLookup is your unified concordance and research hub, bringing together all lookup resources in one place. If you’ve used **LogiTerm Pro**, the idea will feel familiar: one search box across your termbases, translation memories, and web resources. It’s a top tab in Workbench (🔍 SuperLookup), alongside Editor, TMs, Termbases, Clipboard, Voice, and Settings. ## Opening SuperLookup | How | Shortcut | Notes | | ---------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | From the translation grid | **Ctrl+K** | Selects the 🔍 SuperLookup top tab; selected text is used as the search query automatically | | From any application (system-wide) | **Ctrl+Alt+L** | Select any text in any app, press the shortcut, and Workbench opens with the SuperLookup tab forward, text pre-filled, and the search auto-fired. The sub-tab it lands on is configurable – see **Configurable landing tab** below. | | From any application (system-wide) | **Ctrl+Alt+Q** | Opens the [QuickTrans always-on-top popup](/workbench/quicktrans/overview/) with parallel translations from every enabled provider. Different from SuperLookup – use SuperLookup for terminology lookup, QuickTrans for fast MT options. | | Via the system tray | Right-click the orange Sv icon → **Open SuperLookup** | Useful when the global hotkey is taken by another app | ## Configurable landing tab By default, Ctrl+Alt+L lands on the **Termbases** sub-tab. You can change this in **SuperLookup Settings → “Ctrl+Alt+L lands on”** – pick from QuickTrans, TMs, Termbases, or Web Resources. The choice persists across restarts. Whichever sub-tab you choose is fired immediately on the hotkey; the others are deferred until you actually navigate to them, so you don’t pay the cost of work you may not look at. ## Tabs ### TM Matches Search your Translation Memories for similar text: * Fuzzy matching with percentage scores * Horizontal (table) or vertical (list) view toggle * Source TM column shows which TM the match came from * Search direction: Both, Source only, or Target only ### Termbase Matches Search your termbases: * Shows Source, Target, Domain, Notes columns * Right-click to “Edit in Termbase” * Direction and language filters (Both / Source / Target + From/To) ### Machine Translation Get instant MT from multiple providers: * Google Translate, DeepL, Microsoft Translator * Amazon Translate, MyMemory, ModernMT Configure providers in **Settings → MT Settings**. ### Web Resources Quick access to online reference sites: IATE, Linguee, ProZ.com, Reverso Context, Wikipedia, Wiktionary, Google, Google Patents, Juremy, AcronymFinder, BabelNet, and more. Web resource tabs maintain login sessions between searches, so you stay logged in to sites like ProZ.com. ## Search controls **Language filters** – use the **From** and **To** dropdowns to filter by language pair. Auto-populated from your TMs and termbases. **Search direction** – **Both** searches source and target columns; **Source** and **Target** restrict to one side. **Search box** – type a query and press Enter (or click 🔍). When Ctrl+K or Ctrl+Alt+L opens SuperLookup, the selected text is placed in the search box and the search runs immediately. ## Tips * Double-click a result to copy it to the clipboard. * Right-click a result for additional options. * Press **Esc** to hide Workbench back to the system tray once you’ve grabbed what you needed – Esc unconditionally dismisses from SuperLookup, regardless of whether you were typing in the search box. *** ## Related pages * [QuickTrans](/workbench/quicktrans/overview/) * [TM Concordance Search](/workbench/superlookup/tm-search/) * [Termbase Search](/workbench/superlookup/termbase-search/) * [Web Resources](/workbench/superlookup/web-resources/) # Termbase Search SuperLookup’s **Termbases** tab searches your Supervertaler termbases for preferred terminology. ## Open it * **In Supervertaler:** press `Ctrl+K` (or open the **SuperLookup** tab, or **Tools → SuperLookup**). * **From any application:** press `Ctrl+Alt+L` (system-wide hotkey). ## How to search 1. Type (or paste) a term into the search box. 2. Press `Enter` (or click **Search**). 3. Optional filters: * **Direction:** Both / Source / Target * **From / To:** filter by termbase language pair (leave as **Any** to search across languages) ## What you’ll see Results are shown in a table with: * **Source** * **Target** * **Termbase** (termbase name) * **Domain** * **Notes** The current search term is highlighted in the results. ## Actions * **Double-click** a row to copy the translation. * **Copy Translation** copies the selected target term. * **Add to Termbase** opens a dialog to add a new term pair (you’ll be prompted to pick a writable termbase). ## Edit in Termbase (jump to the entry) Right-click a result to open a context menu with: * **Edit in Termbase: …** This navigates to the **Termbases** tab, selects the termbase, and filters the terms list to the source term. ## Termbase selection In **SuperLookup → Settings → Termbases**, you can pick which termbases SuperLookup searches. # TM Search (Concordance) SuperLookup’s **TMs** tab lets you do fast concordance searches in your Translation Memories (“find where I translated this before”). ## Open it * **In Supervertaler:** press `Ctrl+K` (opens SuperLookup with the current selection, if any). * **From any application:** press `Ctrl+Alt+L` — a true system-wide hotkey (registered natively on Windows; no AutoHotkey required). ## How to search 1. Type (or paste) text into the search box. 2. Press `Enter` (or click **Search**). 3. Optional filters: * **Direction:** Both / Source / Target * **From / To:** language pair filter (leave as **Any** to use all languages) ## Views At the top of the tab you can switch between: * **Horizontal (Table):** match % + Source/Target side-by-side. * **Vertical (List):** stacked Source/Target entries (classic concordance layout). ## Actions * **Double-click** a result to copy the target text. * **Copy Target** copies the selected target. * **Insert Target** copies the target and prompts you to paste with `Ctrl+V` in your active application. ## TM selection In **SuperLookup → Settings → Translation Memories**, you can choose which TMs to search. # Web Resources SuperLookup’s **Web Resources** tab gives you a one-click sidebar of reference sites for terminology and research. ## How it works * You use the **main SuperLookup search box** (top of the window) and click **Search**. * The Web Resources tab uses your **From → To** language direction when building URLs. ## Browser modes In the left sidebar you can choose a mode: * **Embedded:** opens sites inside Supervertaler (requires `QtWebEngine`). * Uses a persistent browser profile so logins/cookies are kept between sessions. * **External:** opens your default browser. ## Search options * Select a single resource (e.g. IATE) and click **Search**. * Click **Search All** to load results for all resources (Embedded mode). * Use **Open in Browser** to open the last search URL in your default browser. ## Included resources The sidebar includes (by default): * IATE * Linguee * ProZ.com * Reverso Context * Google Search * Google Patents * Wikipedia (Source) * Wikipedia (Target) * Juremy * beijer.uk * AcronymFinder * BabelNet * Wiktionary (Source) * Wiktionary (Target) ## Show/hide resources In **SuperLookup → Settings → Web Resources**, you can toggle which sites appear in the sidebar. # Sending Terms to the AI Supervertaler can send your termbase entries to the AI as reference during translation, so the model uses your approved terminology instead of guessing. This is on a per-termbase basis and takes one click to enable. ## How to enable it Each termbase in the **Termbase Manager** has an **AI** checkbox (the orange/purple tick), separate from the Read/Write activation checkboxes. 1. Open the **Termbases** tab. 2. Find the termbase whose terms you want the AI to use. 3. Tick its **AI** checkbox. That’s the only setup step. From then on, matching terms are automatically included in every translation prompt for the current project. ## What happens during translation When you translate a segment, Supervertaler: 1. Scans the source text of that segment. 2. Finds any terms from your AI-enabled termbases that actually appear in it. 3. Adds them to the prompt sent to the AI under a **TERMBASE** heading, instructing the model to use those approved terms. The section added to the prompt looks like this: ```plaintext # TERMBASE Use these approved terms in your translation: - machine learning → machinaal leren - click → klikken - widget → ⚠️ DO NOT USE: widget ``` ### Only relevant terms are sent Supervertaler sends **only the terms that appear in the current segment**, not your entire termbase. Matching is whole-word for spaced languages and substring-based for CJK/Thai. This keeps each prompt focused, avoids diluting the AI with irrelevant terminology, and saves tokens. ### Forbidden terms If you mark a term as **forbidden** in the termbase, the AI is explicitly told **DO NOT USE** that translation. This is useful for steering the model away from a wrong-but-tempting rendering, or away from an old term a client has since replaced. ## Tips * **Keep AI-enabled termbases focused.** Very large termbases trigger a warning, because sending a lot of terminology can dilute translation quality. Thanks to per-segment filtering this rarely bites in practice, but a tight, curated glossary gives the best results. * **Works everywhere.** Term injection applies to single-segment translation, batch translation, and keyboard-shortcut translation alike. * **Combine with TM.** Fuzzy TM matches are injected alongside termbase terms, so the AI gets both your approved terminology and your existing translations as reference. ## See Also * [Termbase Basics](/workbench/termbases/basics/) * [Importing Terms](/workbench/termbases/importing/) * [AI Translation Overview](/workbench/ai-translation/overview/) * [Prompts](/workbench/ai-translation/prompts/) # Termbase Basics Termbases help ensure consistent terminology across your translations. ## What is a Termbase? A termbase is a database of terms with their translations: | Source (EN) | Target (NL) | Domain | Notes | | ---------------- | --------------- | ------ | --------------- | | software | software | IT | Don’t translate | | click | klikken | IT | Verb | | machine learning | machinaal leren | AI | Official term | ## Why Use Termbases? 1. **Consistency**: Same term = same translation every time 2. **Efficiency**: Don’t look up the same term twice 3. **Quality**: Use approved terminology 4. **Client requirements**: Follow style guides ## Termbase Features in Supervertaler ### Automatic Highlighting Terms from active termbases are highlighted in the source text: * Green background by default * Hover to see the translation * Higher priority = darker shade ### Multiple Termbases Maintain separate termbases for: * Different clients * Different domains (legal, medical, IT) * Different projects ### Priority Levels Assign priority (1-10) to terms: * Priority 1 (highest): Must be used * Priority 5: Standard terms * Priority 10: Optional/suggestions ### Forbidden Terms Mark terms as “forbidden” to flag text that should NOT be translated or should be avoided. ## Creating Your First Termbase 1. Go to the **Termbases** tab 2. Click **+ Create Termbase** 3. Enter a name (e.g., “Client ABC Terminology”) 4. Choose source and target languages 5. Click **Create** ## Adding Terms ### Manually 1. Click on your termbase 2. Click **+ Add Term** 3. Enter source term, target term 4. Optionally add domain, notes, priority 5. Click **Save** ### From Selection 1. Select text in the source column 2. Right-click → **Add to Termbase** 3. Enter the target translation 4. Choose which termbase to add to ### Import from File 1. Go to the **Termbases** tab 2. Click **Import** 3. Select a TSV file (tab-separated: source, target, domain, notes) 4. Watch the progress dialog ## Termbase Settings ### Activation Termbases must be activated to show matches: * ✅ **Read**: Terms are highlighted and shown in lookups * ✅ **Write**: New terms can be added during translation ### Highlight Style Choose how terms appear in the grid: * **Background**: Green background shading * **Dotted Underline**: Subtle underline * **Semibold**: Bold text Go to **Settings → View Settings → Termbase Highlight Style**. *** ## See Also * [Creating Termbases](/workbench/termbases/creating/) * [Importing Terms](/workbench/termbases/importing/) * [Term Highlighting](/workbench/termbases/highlighting/) * [Sending Terms to the AI](/workbench/termbases/ai-injection/) * [TermLens (Inline Terminology)](/workbench/termbases/termlens/) * [Term Extraction](/workbench/termbases/extraction/) # Creating Termbases Termbases help you enforce terminology consistently. ## Create a termbase 1. Open the **Termbases** tab 2. Click **Create Termbase** 3. Give it a name and select languages ## Add terms while translating You can build terminology as you work: * Select text in both Source and Target * Use **Add to Termbase** from the context menu The right-click menu offers several routes: **Add to Termbase** (`Ctrl+Alt+T`, opens the entry dialog), and the quick-adds **Quick Add to Project Termbase** (`Alt+Up`) and **Quick Add to Background Termbase** (`Alt+Down`). ## Similar Term Found — merge as a synonym If the term you are adding shares its source with an existing entry (but has a different target), or shares its target (but a different source), Workbench shows a **Similar Term Found** prompt instead of silently creating a near-duplicate. You can: * **Add as Synonym** — fold the new term into the existing entry as a synonym * **Add & Edit…** — do that, then open the entry editor to review it * **Keep Both** — create a separate entry anyway * **Cancel** — abandon the add The prompt only appears when there is an actual overlap, so the quick-adds stay instant otherwise. Exact duplicates (same source *and* target) are skipped as before. This matches the behaviour of the Supervertaler for Trados plugin. ## Tips * Use a separate termbase per client when terminology differs. * Add high-priority terms first (product names, UI strings). # Term Extraction **Term extraction** sends your project’s source text to your configured AI model and returns a proposed **bilingual project glossary** – source terms paired with translations – which you review, edit, and turn into a project termbase in one step. ### Opening the extraction dialogue Go to the **Termbases** tab and click **🔍 Extract Terms** in the button bar beneath the termbase list, next to **+ Create New**. Extraction reads the source segments of the open project, so open a project first – clicking with none open just tells you to. ### Choosing the source text The dialogue offers two sources: * **Use project segments** (default) – extracts from all source segments in the loaded project. * **Paste text manually** – enables the text box below, so you can extract from arbitrary text. Useful for a reference document or a client’s style guide. ### Extraction settings | Setting | Default | What it does | | -------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Source Language** | the project’s source language | Tells the model what language the text is in. Free text – any language works. | | **Target Language** | the project’s target language | The language the model translates each term into. | | **Domain / Subject** | blank | Optional hint, e.g. `mechanical engineering` or `sewing machines`. Leave blank and the model infers the domain from the text itself. | Click **🤖 Extract Terms with AI**. Small texts return in seconds; a full-length document (e.g. a complete patent application) takes a minute or so. The dialogue stays responsive while it runs. ### Reviewing the results Results fill a table of term pairs: | Column | Meaning | | ---------- | -------------------------------------------------------------------------------------------------------------- | | **Select** | Tick box controlling whether the pair is added. Every row starts ticked. | | **Source** | The term, in its canonical (dictionary) form. **Editable** – click to correct. | | **Target** | The model’s translation. **Editable.** May be empty where the model was unsure – fill it in or untick the row. | | **Note** | Optional context from the model, such as a domain label or a caveat. | Edit cells directly to fix anything before committing – your edits are what gets saved, not the model’s original answer. To tick or untick many rows at once, select them (Shift/Ctrl+click) and **right-click** → *Untick selected* / *Tick selected*. On very large projects only the first portion of the text (roughly 8–9k words) is analysed, and the results label says so explicitly – nothing is truncated silently. ### Creating the project termbase Click **Create Project Termbase**, then give it a name. The default is ` Terminology`. Supervertaler creates a project-scoped **bilingual** termbase containing every ticked pair and makes it the **Project termbase** – it appears in the Termbases tab with the pink **Project** tick and **Read** enabled, so terms with targets immediately produce [TermLens](/workbench/termbases/termlens/) suggestions. Empty-target entries can be completed later – see [Creating termbases](/workbench/termbases/creating/). ### Tips * The model’s output is a proposal, not a verdict – review it as you would any AI suggestion, especially target translations of ambiguous terms. * A one-word domain hint noticeably improves precision on specialised texts. * If you build prompts with **AutoPrompt**, note that it already performs glossary extraction as part of prompt generation – the two are complementary: this feature produces a *termbase* you can edit, share, and reuse across sessions. *** ### See Also * [Termbase Basics](/workbench/termbases/basics/) * [Creating termbases](/workbench/termbases/creating/) * [Importing termbases](/workbench/termbases/importing/) * [AI injection](/workbench/termbases/ai-injection/) * [TermLens overview](/workbench/termbases/termlens/) # Term Highlighting When a termbase is active, Supervertaler highlights matching terms in the grid. ## Why it helps * Prevents terminology drift * Speeds up review * Makes it obvious when a preferred term exists ## Tips * If the highlight is too strong or too subtle, adjust it in [View Settings](/workbench/settings/view/). * Tag highlighting and termbase highlighting are separate: tags are for placeholders/formatting, termbases are for terminology. * For a word-by-word terminology view with translations underneath each term, see [TermLens](/workbench/termbases/termlens/). # Importing Terms You can import terminology from common formats such as TSV/CSV (and other supported termbase exports). ## Import steps 1. Open the **Termbases** tab 2. Choose **Import** 3. Select your file ## Tips * Clean your source file (consistent columns) before importing. * Import before batch translation so AI can follow your terminology. # TermLens TermLens is Supervertaler’s inline terminology display. It shows the source text of the current segment word by word, with termbase translations directly underneath each matched term. ## How it works When you select a segment, TermLens analyses the source text against all active termbases and displays the result in a visual layout: * **Matched words** appear with their termbase translation underneath * **Unmatched words** are shown in light text so you can read the full source sentence in context * **Project termbase** matches appear in pink; **Background termbase** matches appear in blue * **Non-translatable** terms (if configured) are shown in a distinct style This gives you an at-a-glance overview of every term in the segment that has a termbase entry – without having to hover or click anything. ## Where to find it TermLens appears in two places: 1. **Below the grid** – the “TermLens” tab in the bottom panel (toggle with **View → TermLens Under Grid**) 2. **In the Match Panel** – the right-side panel that also shows TM matches Both instances update simultaneously when you navigate to a new segment. ## Inserting terms You can insert a termbase translation from TermLens into your target text in three ways: ### Click to insert Click any translation shown under a source word. The translation is inserted at the cursor position in the target field. ### Keyboard shortcuts (Alt+1 through Alt+9) Each matched term in TermLens is assigned a numbered badge. Press **Alt+1** to insert the first match, **Alt+2** for the second, and so on. **Double-tap** for terms 10 and above: press **Alt+1, Alt+1** quickly to insert term 11, **Alt+2, Alt+2** for term 22, etc. > **Note:** Alt+0 is reserved for the Compare Panel. TermLens numbering starts at 1. ### Right-click menu Right-click a term in TermLens to: * **Insert** the translation * **Edit** the termbase entry * **Delete** the termbase entry ## On-demand views (popup & picker) In addition to the always-visible panels, two on-demand views show the same matches in a more focused layout. Use them when the docked panel is hidden, on small screens, or when you want a keyboard-only insertion flow. | View | Trigger | Best for | | ---------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- | | [**TermLens popup**](/workbench/termbases/termlens-popup/) | **Ctrl** tap | Floating mirror of the docked panel; cycle chips with arrow keys, insert with Enter or 1–9. | | [**TermPicker**](/workbench/termbases/termpicker/) | **Ctrl+Shift+P** | Modal tabular grid with #/Source/Target/Termbase columns and expandable synonym sub-rows. | Both pull from the same data the docked panel uses, so the chips / rows you see are identical – just laid out differently. ## Font settings You can customise the TermLens font independently from the grid font: 1. Go to **Settings → View Settings → TermLens Font Settings** 2. Choose font family, size (6–16 pt), and bold/normal weight 3. Changes apply immediately to both TermLens instances ## Tips * Press **F5** to force a refresh if matches appear to be missing. * TermLens respects termbase activation – only terms from activated termbases are shown. * If you have many termbases, designate one as the **Project termbase** (shown in pink) to make its terms stand out. ## TermLens for Trados A standalone version of TermLens is also available as a plugin for **Trados Studio 2024+**. It reads the same SQLite termbase format used by Supervertaler and displays terminology matches directly inside the Trados editor. → [TermLens for Trados on GitHub](https://github.com/michaelbeijer/TermLens) *** ## See Also * [TermLens popup](/workbench/termbases/termlens-popup/) – on-demand floating mirror of the panel (Ctrl tap) * [TermPicker](/workbench/termbases/termpicker/) – tabular grid view of the same matches (Ctrl+Shift+P) * [Termbase Basics](/workbench/termbases/basics/) * [Term Highlighting](/workbench/termbases/highlighting/) * [Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) # TermLens popup The **TermLens popup** is a borderless floating version of the docked TermLens panel for the active segment. It mirrors the panel’s chips, colours, and metadata indicators exactly, but appears at the cursor on demand – designed for keyboard-only term selection on small screens, and for translators who want to insert terms without ever reaching for the mouse.  The TermLens popup floating at the cursor over the active segment, with the current match highlighted (blue ring around the chip). The docked TermLens panel on the right shows the same matches – the popup is its on-demand mirror. ### When to use it * **Small screens / laptops** – keeping the docked TermLens panel always-visible can cost too much vertical space, especially for longer source sentences. The popup gives you the same view on demand and disappears when you’re done. * **Pure-keyboard workflows** – Ctrl tap, cycle, Enter, back to typing. No mouse, no menu hunting. ### Opening and closing | Key | Action | | ----------------------- | ------------------------------------------------ | | **Ctrl** (tap) | Toggle the popup (open if closed, close if open) | | **Esc** | Close without inserting | | Click outside the popup | Close without inserting | | Move the mouse > 4 px | Close (the popup is meant to be transient) | A “Ctrl tap” is a press-and-release of the Ctrl key on its own – no other key in between. Same memoQ-style trigger you might already use for the docked panel’s Insert-by-number flow. ### Cycling between matches When the popup opens, the first chip has a thin blue ring around it – that is the **current chip** that Enter will insert. The cycle skips bare source words; only chips you can actually insert get the highlight. | Key | Action | | ------------------------------ | ------------------------------------------------ | | **Right** / **Down** / **Tab** | Move the current-chip highlight to the next chip | | **Left** / **Up** | Move it to the previous chip | Cycling wraps: from the last chip, Right takes you back to the first. ### Inserting | Key / action | Result | | ------------------ | ------------------------------------------------------------------------------------------------- | | **Enter** | Insert the current chip into the target segment, close the popup, return focus to the target cell | | **1–9** | Insert that-numbered chip directly (same numbering as the docked panel’s Alt+N shortcut) | | **Click any chip** | Insert that chip into the target segment, close the popup, return focus to the target cell | All paths share the same insertion logic – there is no difference between picking by keyboard and picking by mouse. ### Editing a match Press **E** while a chip is highlighted to open the term-entry editor for that entry. The popup closes first so the editor opens with clean focus. The editor is the same dialogue the docked panel’s right-click “Edit Termbase Entry…” menu uses, including the multi-termbase “Editing:” dropdown that lets you switch between sibling entries from other active termbases. ### Showing metadata Press **I** while a chip is highlighted to toggle the sticky metadata popup for that entry – the same hover popup the docked panel shows, with the entry’s synonyms, abbreviations, definition, domain, notes, and URL fields. Press **I** again to dismiss it. ### Visuals The popup uses the same chip rendering, colour scheme, and metadata indicators as the docked TermLens panel: | Chip style | Meaning | | ---------------------------------- | ------------------------------------------------ | | **Pink** background | Project termbase term | | **Blue** background | Background termbase term | | **Amber / yellow** background | Non-translatable term | | **Red** background + strikethrough | Forbidden term | | **Purple** background | Match via abbreviation (shows abbreviation pair) | | **ℹ** corner indicator | Entry has metadata (definition / domain / etc.) | | **≡** corner indicator | Entry has synonyms | | **+N** badge on chip | N more cross-termbase entries available | See the [TermLens overview](/workbench/termbases/termlens/) for the full colour key. ### TermLens popup vs TermPicker Both show the same matches for the active segment. Pick whichever fits your style: | | TermLens popup (Ctrl tap) | [TermPicker](/workbench/termbases/termpicker/) (Ctrl+Shift+P) | | -------- | ------------------------------------------------------ | ------------------------------------------------------------- | | Layout | Source segment with chips underneath each matched word | Sortable, scrollable table | | Best for | Skimming matches in segment context | Many matches that benefit from sorting / typing-to-jump | | Keyboard | Arrow / Tab cycles a highlighted chip | 0–9 jumps directly; Up / Down navigate | | Modality | Modeless – Esc / mouse move / click outside to dismiss | Modal – Esc or Cancel to close | *** ### See Also * [TermLens overview](/workbench/termbases/termlens/) * [TermPicker](/workbench/termbases/termpicker/) * [Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) # TermPicker **TermPicker** is a modal dialogue that lists all matched termbase terms and non-translatables for the current segment in a tabular, keyboard-navigable grid. It is useful when [TermLens](/workbench/termbases/termlens/) shows many matches and you want a quick overview without the chip layout – or when you want to compare alternative translations side-by-side before committing.  The TermPicker dialogue floating over the editor for the active segment, listing every termbase + NT match in a sortable grid. Row 3 is expanded (▾) to show a synonym sub-row underneath. The docked TermLens panel on the right shows the same matches as chips. ### Opening TermPicker Press **Ctrl+Shift+P** to open TermPicker. It appears as a modal window above the editor. (P = **P**icker — matches the Trados plugin and follows the VS Code-style command-palette convention.) The shortcut is fully remappable via **Settings → Keyboard Shortcuts** under the `term_picker` action. > Looking for the lone-Ctrl-tap behaviour? That opens the [TermLens popup](/workbench/termbases/termlens-popup/) – a more compact in-context view of the same matches. TermPicker described on this page is the table-based alternative for users who prefer a tabular UI. ### Colour-coded rows Each row is colour-coded by its source: | Colour | Meaning | | ------------------- | -------------------------------- | | **Pink** | Project termbase term | | **Blue** | Background termbase term | | **Yellow / amber** | Non-translatable term | | **Grey** (indented) | Synonym sub-row of the row above | This lets you instantly see where each term comes from and how it should be handled. ### Expandable synonyms Terms with multiple translations (either target synonyms recorded on a single entry, or multiple termbase entries hitting the same source word) display a right-arrow indicator (**▸**) next to the row number. To expand and see all alternative sub-rows: * Select the row and press the **Right arrow** key * The sub-rows appear underneath, indented with a `└` and shown in grey, one per available translation * The indicator switches to **▾** to show the row is expanded Press **Left arrow** to collapse the synonyms again. ### Keyboard navigation TermPicker is designed for fast keyboard use: | Key | Action | | ------------- | -------------------------------------------------------------- | | **0–9** | Jump to that-numbered row; auto-inserts when ≤ 9 total matches | | **Enter** | Insert the selected term and close the picker | | **Esc** | Close the picker without inserting | | **Up / Down** | Navigate between rows (wraps around) | | **Right** | Expand synonyms for the selected row | | **Left** | Collapse synonyms (jumps to parent row when on a sub-row) | **Number-key behaviour:** when the segment has 9 or fewer matches, pressing a digit selects *and* inserts the corresponding row in one keystroke. When there are 10 or more matches, the digit only selects the row – press **Enter** to insert. This guards against unintended auto-inserts when a digit was the first character of a two-digit number you were typing. ### Inserting a term You can insert a term in three ways: * **Double-click** any row to insert that term at the cursor position in the target field * **Press Enter** on the selected row to insert and close * **Click “Insert”** in the dialog footer The selected translation lands at the current cursor position in the target segment. ### Persisted layout TermPicker remembers your preferred size and column widths between sessions, so once you resize it to fit your screen the layout sticks. > TermPicker shows the same matches as TermLens, but in a flat sortable list format that scales better when there are many results. *** ### See Also * [TermLens overview](/workbench/termbases/termlens/) * [TermLens popup](/workbench/termbases/termlens-popup/) * [Termbase Basics](/workbench/termbases/basics/) * [Keyboard Shortcuts](/workbench/editor/keyboard-shortcuts/) # Pdf Rescue ## Overview **PDF Rescue** is a specialised AI-powered OCR tool designed to extract clean, editable text from poorly formatted PDFs. Built into Supervertaler, it uses vision-capable LLM OCR to intelligently recognise text, formatting, redactions, stamps, and signatures–producing professional, translator-ready documents. ### 🎯 The Problem It Solves Have you ever received a PDF translation job where: * The text won’t copy-paste cleanly? * Line breaks are all over the place? * Formatting is completely broken? * Traditional OCR produces gibberish? * Redacted sections show as black boxes? * Stamps and signatures clutter the text? **PDF Rescue fixes all of this.** ### Real-World Success Story > *“I had a client reach out for a rush job–a 4-page legal document that had clearly been scanned badly. Traditional OCR couldn’t handle it, and manual retyping would have taken hours.* > > *I used PDF Rescue’s one-click PDF import, processed all 4 pages with AI OCR, and it produced a flawless Word document that I could immediately start working with. What would have been a multi-day nightmare became a straightforward job I could deliver on time.* > > *I was able to tell my client that I could handle the job–and delivered professional quality. PDF Rescue literally saved a client relationship.”* > > – Michael Beijer, Professional Translator *** ## ✨ Key Features ### 1. 📄 **One-Click PDF Import** * **No external tools needed** - Import PDFs directly * **Automatic page extraction** - Each page saved as high-quality PNG (2x resolution) * **Persistent storage** - Images saved next to source PDF in `{filename}_images/` folder * **Client-ready** - Images can be delivered to end clients if needed ### 2. 🧠 **Smart AI-Powered OCR** * **Vision-capable LLM OCR** - High accuracy OCR * **Context-aware** - Understands document structure and formatting * **Intelligent cleanup** - Fixes line breaks, spacing, and formatting issues * **Redaction handling** - Inserts descriptive placeholders like `[naam]`, `[bedrag]` in document language * **Stamps & signatures** - Detects and describes non-text elements: `[stempel]`, `[handtekening]` ### 3. 🎨 **Optional Formatting Preservation** * **Markdown-based** - Uses `**bold**`, `*italic*`, `__underline__` * **Toggle on/off** - User-controlled via checkbox * **Clean output** - Markdown converted to proper formatting in DOCX export * **Visual preview** - See formatting markers before export ### 4. 📊 **Batch Processing** * **Process selected** - Work on individual images * **Process all** - Batch process entire document * **Progress tracking** - Visual progress bar and status updates * **Skip processed** - Already-processed images are skipped (unless re-selected) ### 5. 📝 **Comprehensive Logging** * **Activity log integration** - All operations logged with timestamps * **PDF import progress** - Each page extraction logged * **OCR processing** - Per-image processing logged * **DOCX export** - Export operations tracked ### 6. 👁️ **Full Transparency** * **“Show Prompt” button** - View exact instructions sent to AI * **Configuration display** - See model, formatting settings, max tokens * **No black boxes** - Complete visibility into AI processing ### 7. 📊 **Professional Session Reports** * **Markdown format** - Clean, readable documentation * **Complete configuration** - All settings recorded * **Processing summary** - Table of all images and status * **Full extracted text** - All OCR results included * **Statistics** - Character/word counts and averages * **Supervertaler branding** - Professional client-ready reports ### 8. 💾 **Flexible Export Options** * **DOCX export** - Formatted Word documents with optional bold/italic/underline * **Copy to clipboard** - Quick text extraction * **Session reports** - Professional MD documentation ### 9. 🚀 **Standalone Mode** Can run independently outside Supervertaler: ```bash python modules/pdf_rescue.py ``` Full-featured standalone application with all capabilities. *** ## 🎯 Workflow ### Quick Start (5 Steps) 1. **Open PDF Rescue** - Open the **Tools menu** at the top of the window → **🔍 PDF Rescue**. The tool opens in its own window. 2. **Import PDF** - Click ”📄 PDF” button, select your badly-formatted PDF 3. **Check formatting option** - Leave “Preserve formatting” checked (default) 4. **Process** - Click ”⚡ Process ALL” to OCR all pages 5. **Export** - Click ”💾 Save DOCX” to create Word document **That’s it!** You now have a clean, editable Word document ready for translation. *** ### Detailed Workflow #### Step 1: Import Your PDF **Method 1: Direct PDF Import** (Recommended) ```plaintext Click: 📄 PDF button → Select PDF file → Automatic page extraction to {filename}_images/ folder → All pages added to processing queue ``` **Method 2: Manual Image Import** ```plaintext Click: 📁 Add Files → Select individual images OR Click: 📂 Folder → Select folder with images ``` **Result**: All images listed in left panel with ✓ status indicators *** #### Step 2: Configure Settings **Model Selection** (vision-capable models, grouped by provider): * **OpenAI**: `gpt-5.5` (Recommended - flagship), `gpt-5.4-mini` (budget option) * **Claude**: `claude-sonnet-4-6`, `claude-haiku-4-5-20251001`, `claude-opus-4-8` * **Gemini**: `gemini-3.1-flash-lite`, `gemini-2.5-pro`, `gemini-3.1-pro-preview` **Formatting Option**: * ✓ **Preserve formatting (bold/italic/underline)** - Enabled by default * Unchecked = Plain text output only **Extraction Instructions**: * Default instructions optimized for badly formatted PDFs * Handles redactions, stamps, signatures automatically * Can customize if needed (advanced) * Click **“👁️ Show Prompt”** to see exact AI instructions *** #### Step 3: Process Images **Option A: Process Selected** ```plaintext 1. Select image(s) in list 2. Click: 🔍 Process Selected 3. View result in preview pane ``` **Option B: Process All** (Recommended) ```plaintext 1. Click: ⚡ Process ALL 2. Confirm batch processing dialog 3. Watch progress bar 4. All pages processed automatically ``` **Processing Details**: * Each image sent to the OCR model * Text extracted with context awareness * Formatting detected (if enabled) * Redactions/stamps/signatures handled * Results stored in memory * ✓ indicator appears when processed *** #### Step 4: Review & Export **Review Extracted Text**: * Click any processed image in list * Preview pane shows extracted text * Formatting shown as markdown (`**bold**`, `*italic*`, etc.) * Verify quality before export **Export Options**: 1. **💾 Save DOCX** (Primary export) * Formatted Word document * Markdown converted to proper formatting * One page per document page * Page headers with filenames * Ready for translation work 2. **📋 Copy All** * All text to clipboard * Includes page separators * Quick paste into any application 3. **📊 Session Report** * Professional markdown documentation * Complete configuration record * All extracted text included * Statistics and metadata * Client-ready deliverable # Statistics (Analyse Against TM) The **Statistics** tool analyses the document you have open against one or more of your translation memories and produces a match breakdown — the same kind of report you get from the “Analyze Files” step in Trados Studio or memoQ. It tells you, before you start, how much of the job is already covered by your TMs and how much is genuinely new, so you can scope the work and quote accurately. ## Where to find it * Open the **Tools menu** → **📊 Statistics (Analyse Against TM)…** You need a project open with segments. Press **F1** (or the **?** in the top-right of the dialog) to return to this page at any time. ## ⚡ Quick Count (no project needed) When you just want a fast count and don’t want to set up a project, use **Tools → ⚡ Quick Count…** instead: 1. Browse to **one or more files**. Supported: **DOCX** (plus IDML, HTML, XLIFF, PO, XLSX, PPTX via Okapi) and the CAT bilingual formats **Trados `.sdlxliff`** and **memoQ `.mqxliff`**. 2. The same Statistics dialog opens — pick your TMs and matching depth, then **Analyse**. DOCX files are sentence-segmented through Okapi exactly like a normal import, so the numbers match the project-based tool. If a file can’t be read it’s reported on its own and the rest are still counted. The language pair used for segmentation/matching is the open project’s, or your last-used import pair if no project is open. ### Per-file breakdown When you analyse **more than one file** (Quick Count with several files, or a multi-file project), each translation memory’s result shows a combined **All files** total followed by a **per-file** table, so you can see how each file contributes. The breakdown also appears in the HTML/Excel/CSV exports. Single-file analyses just show the one total. ## How to use it 1. Tick one or more translation memories to analyse against. The TMs already activated for the current project are ticked for you. * **Leave every TM unticked** to get a plain word count plus internal repetitions only (no TM lookup). 2. Choose a **Matching depth** (see below). 3. Click **Analyse**. The analysis runs in the background — you can cancel it at any time. Results appear per TM as each one finishes. 4. Optionally click **Export…** to save the report as **HTML**, **Excel (.xlsx)**, or **CSV**. ## Matching depth The fuzzy-match pass is the slow part on a large TM, so you can trade thoroughness for speed: | Depth | What it does | | ---------------------- | --------------------------------------------------------------------------------------------------------- | | **Standard** | Exact matches plus fuzzy matches down to 75%. The default — fast and covers almost all reusable material. | | **Thorough** | Exact plus fuzzy down to 50%. Fills the lower fuzzy bands; a little slower. | | **Exact matches only** | Skips the fuzzy pass entirely. Near-instant, even on a TM with hundreds of thousands of entries. | Behind the scenes the fuzzy search uses the TM’s full-text index to look only at the most relevant candidates (no sub-segment/fragment search), which is conceptually the same as Trados Studio’s “Optimized Performance” option. ## What the match types mean | Type | Meaning | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Repetitions** | Source text that repeats earlier in the document. The first occurrence is counted under a match band; the repeats land here (translate once, reuse). | | **101% (Context Match)** | An exact match whose surrounding context also matches the TM — the safest reuse, normally needs no editing. | | **100%** | An exact match of the source text in the TM (context not checked). | | **95%–99%** | Very high fuzzy match — usually a tiny edit. | | **85%–94%** | High fuzzy match — minor editing expected. | | **75%–84%** | Medium fuzzy match — noticeable editing expected. | | **50%–74%** | Low fuzzy match — often faster to retranslate than to fix. | | **No match** | No usable TM match — translate from scratch. | Each row reports the number of **segments**, **words**, **characters** (tags excluded), **tags**, and the **percentage** of total words. The exported report includes this legend and the project name. ## Related * [Translation memory](/workbench/translation-memory/basics/) * [Fuzzy matching](/workbench/translation-memory/fuzzy-matching/) * [Managing TMs](/workbench/translation-memory/managing-tms/) # TMX Editor Supervertaler includes a built-in TMX editor for inspecting and editing TMX translation memories. ## Where to find it * Open the **Tools menu** at the top of the window → **✏️ TMX Editor**. The editor opens in its own window. ## What you can do * Open, edit, and save TMX files. * Search and filter by source/target text. * Edit TMX header metadata. * Run basic validation and view statistics. * Perform bulk operations (for example: delete entries, copy source → target). ## Common workflows ### Clean up a TMX before importing 1. Open the TMX in **✏️ TMX Editor**. 2. Fix any obvious formatting issues (wrong language, empty segments, etc.). 3. Save the TMX. 4. Import it into your project via [Importing TMX files](/workbench/translation-memory/importing-tmx/). ### Remove unwanted tags If you’re trying to simplify a TMX that contains formatting or CAT-tool tags, you can remove them before importing. ## Related * [Importing TMX files](/workbench/translation-memory/importing-tmx/) * [Translation memory](/workbench/translation-memory/basics/) # Translation Memory Basics Translation Memory (TM) helps you reuse previous translations. ## What is Translation Memory? A Translation Memory stores pairs of source and target text: | Source | Target | Match % | | ------------------- | --------------------- | ------- | | “Save the file" | "Sla het bestand op” | 100% | | “Save the document" | "Sla het document op” | 85% | When you translate new text, the TM finds similar segments. ## How TM Works 1. **You translate** a segment 2. **TM stores** the source + target pair 3. **Later**, when similar text appears: * TM finds matches * Shows them in the Translation Results panel * You can insert or adapt them ## Match Types | Type | Match % | Description | | ---------------- | ------- | ------------------------------------------- | | **Exact** | 100% | Identical source text | | **High Fuzzy** | 90-99% | Minor differences (numbers, capitalization) | | **Medium Fuzzy** | 75-89% | Some words different | | **Low Fuzzy** | 50-74% | Significant differences | ## Benefits ### Save Time Don’t translate the same sentence twice. TM automatically suggests previous translations. ### Consistency Same source = same translation. Important for technical documentation, UI strings, and legal text. ### Cost Savings Clients often pay less for TM matches: * 100% match: Lowest rate * Fuzzy match: Reduced rate * New text: Full rate ## TM in Supervertaler ### Translation Results Panel When you select a segment: 1. TM searches for matches 2. Results appear in the panel on the right 3. Shows match percentage, source, and target 4. Double-click to insert ### Using Matches | Action | How | | --------------- | ------------------------------------------------- | | Insert match | Double-click, or select it and press `Ctrl+Space` | | Copy match | Right-click → Copy | | View in context | Right-click → View in TM | ### Building TM Your TM grows as you translate: 1. Translate a segment 2. Confirm with `Ctrl+Enter` 3. The pair is saved to active TM ## Multiple TMs You can have multiple TMs: * **Project TM**: For the current project * **Client TMs**: One per client * **Master TM**: All your translations ### TM Priority When multiple TMs match: * Higher priority TMs shown first * Can reorder in the **TMs** tab ### Sending segments to several TMs at once To push your confirmed translations into more than one TM in a single run, use **Bulk Operations ▸ Update active TMs**. Under **Target Translation Memories**, tick every TM you want to update – the segments are written to all of them in one pass, with a per-TM summary of how many were sent to each. *** ## See Also * [Creating & Managing TMs](/workbench/translation-memory/managing-tms/) * [Importing TMX Files](/workbench/translation-memory/importing-tmx/) * [Fuzzy Matching](/workbench/translation-memory/fuzzy-matching/) # Fuzzy Matching Fuzzy matching finds similar segments (not just exact duplicates). ## How to use it * As you navigate, Supervertaler searches your TMs for similar source text. * Matches are scored by similarity. ## When to trust a match * **High scores** are often safe to insert as a starting point. * **Mid/low scores** can still be useful, but should be treated as suggestions. ## Tips * Always review fuzzy matches before inserting. * For formatted text, preserve tags when inserting matches. # Importing TMX Files TMX is the common exchange format for translation memories. ## Import steps 1. Open the **TMs** tab 2. Choose **Import TMX** 3. Select your `.tmx` file ## Tips * Import TMs before batch translation to maximize reuse. * If matches don’t show up, verify the TM language pair. # Creating & Managing TMs Translation Memories (TMs) help you reuse past translations. ## Add or create a TM 1. Open the **TMs** tab 2. Add an existing TM (or create a new one) 3. Enable **Read** to use it for matches 4. Enable **Write** if you want new translations saved into it ## Using TM matches * TM matches appear automatically as you navigate. * You can insert matches quickly: * **Ctrl+Space** inserts the currently selected match * Double-click a match in the panel to insert it ## Tips * Keep separate TMs per client or domain if needed. * Ensure the TM language pair matches your project. * If a segment contains tags/placeholders, keep them intact when inserting a match. # Shared TM Bridge with Trados The Shared TM Bridge lets you attach Workbench’s translation memories directly inside Trados Studio – no TMX export/import dance, no separate copy. The Trados side reads from the same `supervertaler.db` SQLite file Workbench writes, so a TU added in Workbench appears in Trados on the next lookup, and vice versa once write-back ships in a later phase. Both halves of the feature are off by default. You opt-in TM by TM, so freelancers with multi-client TM libraries don’t accidentally surface client A’s memory inside a Trados project for client B. ## Half one: tick a TM as “Bridge” in Workbench 1. Open the **TMs** tab. 2. Find the TM you want to expose to Trados. 3. Tick the **Bridge** column for that row. (The column shows an orange checkmark when on.) That’s the entire Workbench side. The TM is now eligible to appear inside Trados Studio. You can flip the flag at any time. Un-ticking it does NOT delete data – it just hides the TM from the Trados-side picker. Any Trados projects that already attached the bridge will start showing an “offline” status pill for it until you tick it again. ## Half two: attach the bridged TM inside Trados You need the **Supervertaler for Trados** plugin installed (`v4.20.26` or newer) and Trados Studio open on a project with the right language pair. 1. In Trados Studio, open your project’s **Project Settings** → **Language Pairs** → **All Language Pairs** → **Translation Memory and Automated Translation**. 2. Click **Add** → **Supervertaler TM**. 3. The picker dialogue lists every TM you’ve ticked as Bridge in Workbench, filtered to those whose language pair matches the current project’s pair (with loose matching – bare `nl` matches `nl-NL`, `en` matches `en-GB`). 4. Tick one or more TMs to attach. Click **OK**. The TM now shows up alongside any SDLTMs you’ve attached, with its full name (e.g. *Supervertaler TM: BRANTS (URSU-008-BE-EP)*). ## What you get in this release * **Exact matches (100%)** – pulled into Trados’s TM-results pane the same way a regular SDLTM would. * **Concordance search** – source-side AND target-side, via the FTS5 index Workbench already maintains. Works in both Trados’s built-in Concordance window and the SuperSearch tab. * **Multiple TMs attached at once** – the per-hit origin strip identifies which bridged TM produced each match (e.g. *Supervertaler: BRANTS (URSU-008-BE-EP)* vs *Supervertaler: PATENTS*). ## What’s NOT in this release * **Write-back from Trados.** Currently read-only. Edits you make to a segment in Trados are confirmed to your normal SDLTM, not to the bridged TM. Bridge support for write-back will land in a later phase. * **Fuzzy matches.** Only 100% matches are returned. Sub-100 fuzzies fall through to any other providers attached to the project. Fuzzy matching against bridged TMs will also land in a later phase. ## Diagnostics If a bridged TM isn’t showing up where you expect, the easiest first checks are: * **Bridge ticked in Workbench?** TMs tab → confirm the orange checkmark is on. * **Language pair matches?** The bridge does loose matching (`nl` matches `nl-NL`) but it still has to match. A TM stored as `en` won’t show up for a `fr-FR → de-DE` project. * **Bridge log.** The Trados plugin writes a diagnostic log to `%TEMP%\supervertaler-tm-bridge.log` every time it talks to a bridged TM. If a lookup is failing, this log usually points straight at the cause. ## See also * [Translation Memory Basics](/workbench/translation-memory/basics/) – the rest of how TMs work in Workbench. * The matching Trados-side help page lives at [Shared TM Bridge with Workbench](/trados/shared-tm-bridge/). # Trados Sdltm You can attach a Trados Studio Translation Memory (`.sdltm` file) directly to Supervertaler and consult it for matches – without exporting it to TMX first, and without closing Trados. ## When to use this The typical scenario: you’re translating a project in Trados Studio with a working TM. You’d like to consult that same TM from inside Supervertaler – maybe to use its concordance, run AI translations against it, or work on a different project that shares terminology with the Trados project. Rather than exporting to TMX every few minutes, you point Supervertaler at the `.sdltm` directly and let it stay in sync. ## Attach a Trados TM 1. Open **TMs → TM List**. 2. Click **🔗 Attach Trados TM** (next to **📥 Import TMX**). 3. Pick the `.sdltm` file. 4. Confirm the dialog – it shows the TM’s languages, name, and translation-unit count. 5. Optionally edit the display name (defaults to the full filename including `.sdltm` so it’s easy to spot in the TM list). 6. Watch the progress dialog as Supervertaler mirrors the TUs (≈ 5 seconds for a 13 K-TU TM). The TM is created **read-only** by default. Supervertaler never writes back to your `.sdltm`; that file remains the source of truth and stays under Trados’s exclusive control for writes. ## How sync works Once attached, the mirror **stays in sync with the live `.sdltm`**. Every 5 seconds Supervertaler checks the file’s modification time. When Trados saves a new or modified TU and the file timestamp changes, Supervertaler pulls in just the delta – not a full re-read – and updates the TM’s entry count automatically. The mtime check itself is essentially free, so idle ticks cost nothing. You can keep working in Trados; new TUs you confirm there appear in Supervertaler within a few seconds. ## Tag preservation Trados-style inline tags are preserved as Supervertaler’s `...` markers on the way in: | Trados | Supervertaler | | --------------------- | ------------- | | Start tag, ID 116 | `<116>` | | End tag, ID 116 | `` | | Standalone tag, ID 12 | `<12/>` | This is the same format Supervertaler uses when it imports SDLXLIFF segments directly, so a TM hit drops cleanly into the editor grid alongside your working segments. The tag IDs in the TM hit won’t necessarily match the IDs in the segment you’re translating – TM `<116>` might be your current `<11>`. Structure (start/end pairs, count) is preserved, but you’ll still need to renumber tags on insertion if the IDs differ. ## Refreshing manually If you’d rather refresh on demand than rely on the 5-second timer, click **🔗 Attach Trados TM** again on the same `.sdltm`. You’ll be asked “TM already attached – replace?”; click **Yes** and Supervertaler wipes the existing entries and re-mirrors from disk in one go. ## Limitations * **Read-only**: Supervertaler never writes back to the `.sdltm`. New translations you confirm in the Workbench go to your normal Supervertaler TMs, not back into the Trados file. * **Tag IDs differ**: as noted above, the numeric IDs on tags in TM hits may differ from the IDs in your current segment. Tag *structure* is preserved. * **Match scores differ slightly**: Supervertaler uses Python’s SequenceMatcher; Trados uses its own token-aligned algorithm. Ranking of matches is similar; exact percentages can be a few points apart. * **Concurrent use is safe**: opening the `.sdltm` while Trados has it open is fine – Supervertaler reads via SQLite’s URI read-only mode, and Trados uses WAL. # API Connection Problems If AI translation isn’t working, this page helps you diagnose provider/API issues. ## Common causes * Missing or invalid API key * No internet connection * Provider rate limits or quota limits * Wrong model selected ## Quick checks 1. Verify your API key in [Setting Up API Keys](/workbench/get-started/api-keys/) 2. Confirm you selected a **provider** and **model** in Settings (LLM/AI settings) 3. Try translating a single short segment (`Ctrl+T`) 4. Check whether your account has credits/quota ## Common errors and fixes | Symptom / message | Likely cause | What to do | | ----------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- | | “Invalid API key” / authentication failed | Key is wrong or has extra whitespace | Re-paste the key; make sure there are no leading/trailing spaces; Save and restart if needed | | “Rate limit exceeded” | Provider is throttling requests | Wait 1–2 minutes; reduce batch size; try a different model | | “Quota/credits exceeded” | Account has no credits or billing disabled | Check provider dashboard; add credits/enable billing | | “Model not found” | Selected model name not available | Pick a supported model in Settings; update if the provider changed model names | | “No response” / empty translation | Transient provider failure, network issue, or timeout | Try single-segment translation; retry the segment; try a different model/provider | | Connection errors / timeouts | Network/VPN/firewall/proxy issues | Try another network; disable VPN; allow Python/Supervertaler through firewall | ## Tips for reliable translation * Start with **single-segment** translation to verify your setup before running batch. * If batch translation returns empty segments, enable the retry option in the batch dialog. * If your segments contain tags/placeholders, add a prompt rule to preserve them exactly. ## Error messages If you see an error dialog, copy the message and include it when asking for help. Include: * Provider + model * Whether single-segment translation works * The exact error text # Common Issues Solutions to frequently encountered problems. ## Startup Issues ### Application won’t start **Symptoms:** Double-click does nothing, or window briefly appears then closes. **Solutions:** 1. **Run from command line** to see error messages: ```bash python Supervertaler.py ``` 2. **Reset UI preferences** (corrupted window state): * Delete `user_data/ui_preferences.json` * Restart the application 3. **Check dependencies**: ```bash pip install -r requirements.txt ``` 4. **Verify Python version** (needs 3.10+): ```bash python --version ``` ### “Module not found” error Install the missing module: ```bash pip install ``` Or reinstall all dependencies: ```bash pip install -r requirements.txt --force-reinstall ``` *** ## Import Problems ### ”Cannot read file” error * Close the file in other programs (Word, Excel, etc.) * Check if the file is read-only * Try copying the file to a different location ### memoQ bilingual shows no segments * Ensure you exported as **Bilingual DOCX** (table format) * Check the file in Word to verify it has a source/target table ### Trados package fails to extract * The SDLPPX might be corrupted * Re-export from Trados Studio * Check if the package includes all required files ### Encoding errors (garbled text) * Open the source file in Notepad++ to check the detected encoding; if it shows ANSI/Windows-1252 with mojibake, use *Encoding → Convert to UTF-8* and re-save. * For more stubborn cases, run [`ftfy`](https://pypi.org/project/ftfy/) on the file from the command line. * Re-export from the source tool with UTF-8 encoding when possible. *** ## Translation Issues ### AI translation returns empty 1. Check your API key is valid 2. Verify you have credits with the provider 3. Check internet connection 4. Try a different model ### ”Rate limit exceeded” error * Wait 1-2 minutes and try again * Reduce batch size * Upgrade your API plan ### Wrong translation language * Check your prompt specifies the correct language pair * Verify source/target languages are set correctly in project settings ### Tags are removed or moved Add explicit instructions to your prompt: ```plaintext Keep all formatting tags like {1}, , in exactly the same positions in the translation. ``` *** ## Reimporting Issues ### Segments don’t match on reimport **Cause:** Segment structure changed. **Solution:** * Don’t merge or split segments in Supervertaler. * Export the matching format for your CAT tool/workflow. * If you’re working from a bilingual table, don’t modify the table structure in Word. ### Formatting lost on reimport **Cause:** Tags/placeholders weren’t preserved. **Solution:** * Verify tags in Tag view before exporting. * Ensure tags are balanced and not renumbered. * Run CAT tool QA after import to catch tag issues early. ### TM matches not appearing **Cause:** TM not loaded, disabled, or language mismatch. **Solution:** * Open the **TMs** tab. * Ensure the TM is added and **Read** is enabled. * Verify source/target language pair matches your project. *** ## Export Problems ### Exported DOCX has no translations * Make sure you translated the segments (target column isn’t empty) * Check you’re exporting the correct format * Verify the segments are confirmed ### ”Source file not found” on export The original imported file was moved or deleted. * Use **Project → Export → 🔗 Relocate Source Folder** to point to the new location * Or re-import the source file ### Formatting lost after round-trip * Keep all inline tags in your translations * Don’t modify the structure of bilingual tables * Check CAT tool import settings *** ## Performance Issues ### Application is slow 1. **Pick a smaller Per page size** above the grid (the grid shows all segments by default; try 100 or 50) 2. **Disable spellcheck** if not needed (Settings → View) 3. **Close other heavy applications** ### Large files take forever to import * Very large files (10,000+ segments) may take time * Consider splitting into smaller files * Use multi-file import for better organization *** ## Spellcheck Issues ### Spellcheck not working 1. Check spellcheck is enabled: **Settings → View Settings → Spellcheck** 2. Verify the correct language is selected 3. For Hunspell, ensure dictionaries are installed ### Wrong language being checked Go to **Settings → View Settings → Spellcheck** and select the correct target language. ### Red underlines appear everywhere The spellcheck language might not match your target language. Or you might need to add technical terms to your dictionary. *** ## UI Issues ### Dark mode colors look wrong Some widgets apply styles when becoming visible. Try: * Switch themes back and forth * Restart the application ### Window opens off-screen Delete `user_data/ui_preferences.json` to reset window position. ### Fonts look different/wrong Go to **Settings → View Settings** and select your preferred font family. *** ## Still Having Issues? 1. Check the [GitHub Issues](https://github.com/Supervertaler/Supervertaler-Workbench/issues) for known bugs 2. Open a new issue with: * Your OS and Python version * Steps to reproduce the problem * Error messages (if any) * Screenshots (if helpful) # Import/Export Errors This page covers common problems when importing or exporting files. ## “Cannot read file” / import fails **Common causes:** * The file is open in Word (or another app) * The file is read-only or in a protected location * The file format doesn’t match the workflow **Fix:** 1. Close the file everywhere (Word, CAT tool editors, preview panes) 2. Copy it to a simple path (for example `C:\Temp\`) and try again 3. Re-export from the CAT tool using the recommended bilingual/package format ## memoQ bilingual shows no segments **Cause:** Export format doesn’t contain the expected bilingual table. **Fix:** * Re-export from memoQ as **Bilingual DOCX** in a **two-column table** format. * Open the DOCX in Word and confirm it really contains a Source/Target table. ## Trados SDLPPX fails to extract **Common causes:** * Corrupt/partial package * Unsupported package structure **Fix:** * Ask for a fresh export from Trados Studio. * Ensure the package includes all required files. ## Garbled characters / encoding issues **Cause:** Text encoding problems coming from the source file or export. **Fix:** * Re-export from the source tool with a modern Unicode/UTF-8-friendly path when possible. * For Latin-1/Windows-1252 mojibake (e.g. “é” appearing where “é” should be), open the file in a text editor that supports re-interpreting the encoding (Notepad++ has *Encoding → Convert to UTF-8*) or run `ftfy` on it from the command line. ## Segments don’t match on reimport **Cause:** Segment structure changed. **Fix:** * Don’t merge or split segments in Supervertaler * Export using the matching CAT format * Avoid deleting placeholder/tag-only segments ## “Source file not found” during export **Cause:** The original source file/folder was moved after import. **Fix:** * Use **Project → Export → 🔗 Relocate Source Folder** and point it to the new location. * If the original source is gone, re-import the project from the correct source. ## Exported file has no translations **Cause:** Targets are empty or the wrong export format was chosen. **Fix:** * Verify the Target column contains translations. * Export the matching format for the workflow you imported. ## Formatting lost on reimport **Cause:** Tags not preserved. **Fix:** * Verify tags are balanced (for example `text`) * Don’t delete CAT placeholder tags * Re-export using the correct CAT workflow ## Bilingual table reimport fails **Cause:** Bilingual tables are great for review, but not always suitable for CAT tool reimport. **Fix:** * Prefer the dedicated CAT exchange formats (memoQ/Trados/Phrase/CafeTran). * If you must use a bilingual table, don’t edit the table structure in Word. # Linux-Specific Issues Supervertaler is Linux compatible, but Windows is the primary development platform. ## Spellcheck dictionaries If spellcheck isn’t working, you may need to install Hunspell dictionaries for your language: ```bash sudo apt install hunspell-en-us ``` If the dictionary package for your language exists, install it using the language code you need (for example `hunspell-de-de`, `hunspell-nl`, etc.). ## Stability tips If you encounter instability: * Disable spellcheck temporarily * Disable semantic memory features temporarily * Use a smaller project to isolate the issue ## Crashes / memory access violations Some native dependencies (spellcheck backends, tokenization libraries) can crash the Python process on certain Linux setups. If you see random crashes (segfaults) when interacting with the grid: 1. Disable spellcheck and restart 2. Retry on a smaller project If that stabilizes the app, re-enable features one by one. # Performance Tips Supervertaler is designed to stay responsive on large projects, but performance can vary with project size and enabled features. ## Tips * Pick a smaller **Per page** size for very large projects (the grid shows all segments by default; projects over 2000 segments auto-paginate at 500). See [Pagination](/workbench/editor/pagination/) * Keep only the needed TMs and termbases enabled * If semantic search is enabled, allow indexing to complete ## Quick wins when it feels slow 1. Disable spellcheck temporarily (Settings → View Settings) 2. Close other heavy apps (browsers with many tabs, IDE builds, etc.) 3. Restart Supervertaler and reopen the project ## Large projects Very large files (thousands of segments) can stress any UI grid. * Prefer pagination. * Consider splitting source documents or using multi-file projects. ## If it feels slow Try restarting the app and reopening the project. If performance is still poor, note: * Project size (segment count) * Whether spellcheck is enabled * Which CAT format you imported # Voice **Voice** is Supervertaler’s voice command and dictation engine. It lets you control any application on your computer – Trados, memoQ, Word, or anything else in the foreground – using your voice, while Supervertaler Workbench stays running in the background. Open it via the **🎤 Voice** top tab in Workbench, the tray icon’s **Open Voice** entry, or press **Ctrl+Alt+A** to toggle Always-On listening from anywhere on your computer.  *** ## Three modes ### Always-On listening Always-On runs a continuous microphone stream in the background. When you speak, Voice detects speech via amplitude-based VAD (voice activity detection), captures the utterance, and hands it to the active recognition engine. **With the Vosk engine** *(default)* the recogniser only emits text for phrases in your command list – anything else is silently dropped as `[unk]`. So Vosk Always-On is “commands only” by design: you can leave it on all day, talk to colleagues, take phone calls, etc., and only matching command phrases will trigger actions. **With faster-whisper or OpenAI Whisper API** every utterance is transcribed in full. If it matches a command the action fires; if not (and “Listen for commands only” is off), the transcribed text is typed into whichever window is in the foreground. **To start:** click **▶ Start Always-On** in the Voice tab, or press **Ctrl+Alt+A** from any application. A red mic icon appears in the system tray while Always-On is active. **To stop:** click **⏹ Stop Always-On** or press **Ctrl+Alt+A** again. **Focus matters:** Voice sends keystrokes and text to whichever window is currently focused. After starting Always-On, click into Trados, Word, or your browser before you speak. ### Push-to-Talk dictation (Ctrl+Shift+Space) Press **Ctrl+Shift+Space** (the default dictation hotkey – ⌘⇧Space on macOS; works globally, from any application, and is configurable in **Settings → Keyboard Shortcuts**) to record a single utterance for free-form running-text dictation. A small ”🎤 Listening…” toast appears in the top-right of the screen so you know the recording is live; it goes away again when you stop. Recording stops when you release the key (in hold-to-talk mode) or when you press the trigger again (in toggle mode). The transcribed text is then typed at the cursor position. **Always-On + push-to-talk coexist.** If Always-On is running when you trigger push-to-talk, Voice pauses the always-on listener for the duration of the recording, runs the dictation, then resumes Always-On automatically. So you get free continuous Vosk command recognition all day *plus* a hotkey for occasional running-text dictation, without having to manually toggle Always-On off and on. **Push-to-talk modes** (configurable in the Push-to-Talk settings): * **Toggle** (default) – press once to start, press again to stop * **Hold-to-talk** – hold the key to record, release to stop. *Note: hold-to-talk only works if you rebind dictation to a non-global (in-app) key. The default global hotkey always uses Toggle mode (Windows can’t reliably deliver key-up events across processes for global hotkeys).* ### Push-to-Talk for commands (Ctrl+Alt+V) — v1.10.193 Press and **hold** **Ctrl+Alt+V** (the default; configurable in **Settings → Keyboard Shortcuts**) to temporarily activate the command listener for the duration of the hold. Release the key to stop it again. Works globally, from any application. This is a third mode that sits between the two above: * Always-On is the **toggle** version of command listening — mic open continuously, listens for commands all day. * Command Push-to-Talk is the **hold** version — mic open only while you hold the chord, so the rest of the time the microphone is genuinely free for other applications. **When to use this mode:** * You also use an external dictation app (Wispr Flow, Dragon, macOS Dictation, etc.) for running-text dictation and don’t want Supervertaler’s always-on mic competing for the audio stream. * You only need voice commands occasionally — pressing a hotkey when you want to issue one is less intrusive than leaving the mic open all day. * You’re on a laptop battery-conscious about the always-on Vosk model running 24/7. **Coexistence with the toggle mode:** if Always-On is already running when you press Ctrl+Alt+V, the hotkey is a no-op — it won’t restart what’s already going, and releasing it won’t stop Always-On either (we never touch what we didn’t start). So the two modes don’t fight each other; you can use whichever feels right for the moment. **Platform notes:** release detection on Windows uses `GetAsyncKeyState` polling (same mechanism as the dictate PTT). On macOS / Linux, the listener stays running until you press Ctrl+Alt+A or click ⏹ Stop Always-On — it doesn’t auto-stop on key release. Lift to a manual toggle there. ### Pause Always-On for external dictation — v1.10.246 The opposite trade-off to Command Push-to-Talk: keep Always-On running **permanently**, but have it step off the microphone for the moments you’re dictating into an **external** tool (Wispr Flow, Dragon, macOS Dictation, …). You bind one of *your* keys — the same key you press to start your external dictation — and Always-On pauses while it’s engaged, then resumes. So your voice commands stay available all day, and the two never fight over the mic. The key is **recorded, not typed**, so it works with keys you can’t express as text — including media keys like **fast-forward**, which many people use to trigger their dictation tool. **To set it up** — Voice tab → **⏸️ Pause Always-On for external dictation**: 1. Click **Record key**, then press the key you use for your external dictation tool. The label shows what was captured (e.g. *Media Next / Fast-Forward*). 2. Choose a **mode**: * **Hold** *(default)* — Always-On pauses only while you hold the key and resumes the instant you release it. Pair this with **hold-to-talk** tools like Wispr Flow: hold your key → speak → release, and Always-On is live again. * **Toggle** — press once to pause, press again to resume. Use this if your tool starts/stops dictation on a single tap. It works **globally** (the Workbench doesn’t need to be focused) and the key is observed *passively* — your external tool still receives it normally. Press detection and release both come from the same low-level hook used by Command Push-to-Talk. *** ## Voice commands Voice commands execute specific actions when you speak a trigger phrase. They can type text, press keyboard shortcuts, run AutoHotkey scripts, or call internal Workbench functions. ### The commands table The commands table (right side of the Voice tab) lists all your configured commands. | Column | Description | | -------- | -------------------------------------------------------------------------- | | ☑ | Enable/disable checkbox – uncheck to silence a command without deleting it | | Phrase | The primary trigger word or phrase | | Aliases | Alternative phrases that also trigger the command | | Type | Command / Keystroke / AHK Script / AHK Inline | | Action | What happens when the phrase is recognised | | Category | Organisational label (Navigation, Editing, etc.) | ### Enabling and disabling commands * **Single command** – click the checkbox in the first column * **All commands** – click the checkbox column header to toggle all at once (enables any disabled, or disables all if all are already active) * **Multiple commands** – select rows with **Shift+Click** or **Ctrl+Click**, then right-click and choose **✅ Activate** or **⬜ Deactivate** Disabled commands are greyed out and are skipped during recognition. Their settings are preserved. ### Editing a command Double-click any row to open the Edit Voice Command dialog. You can change the phrase, aliases, action type, and action value. You can also use the **Edit** button in the toolbar above the table. ### Adding a command Click **+ Add** above the table. Choose a command type: * **Command** – calls an internal Workbench action (confirm segment, next segment, etc.) * **Keystroke** – sends a key combination to the active window. Click into the **Keystroke** field and press the keys you want to send (e.g. press Ctrl+Enter); the field shows the platform-native symbols (⌘⇧⌥⌃ on macOS, Ctrl+Shift+Alt elsewhere) so you don’t have to translate between platforms. * **AHK Script** – runs an AutoHotkey v2 script file * **AHK Inline** – runs a short AutoHotkey v2 snippet directly The Edit Voice Command dialog includes a **context-sensitive cheat sheet** below the Action field that updates with the Type dropdown – it explains the press-to-capture editor for Keystroke commands, lists common AHK patterns for AutoHotkey Code, names the available internal actions, etc. So you don’t need to memorise the full reference up front. ### Removing a command Select the row and click **Remove**, or select multiple rows and remove them together. ### Edits take effect immediately under Vosk When the Always-On engine is **Vosk**, adding / editing / removing / disabling a command immediately rebuilds Vosk’s recogniser grammar in the background – you don’t have to stop and restart Always-On to “teach” Vosk a new phrase. The status bar briefly shows `🔄 Vosk grammar refreshed (N phrases)` to confirm the swap took effect. The next utterance you speak will use the new grammar. *** ## Settings ### Always-On engine The dropdown in the Always-On section picks which speech-recognition backend listens for commands. | Engine | Best for | Speed | Cost | Internet | | --------------------------------- | ------------------------------------------------------------------- | ----------------- | ------------------------ | ------------- | | **Vosk** *(default, recommended)* | Commands only – your phrase list, ignores everything else | Instant (\~30 ms) | Free | No | | **faster-whisper** | Commands + dictation of running text from one continuous mic stream | \~1–3 s | Free | No | | **OpenAI Whisper API** | Same as faster-whisper but offloaded to OpenAI’s servers | \~0.5–2 s | $0.006 / minute of audio | Yes (API key) | **Vosk** is the default for new installs. It’s purpose-built for fixed-vocabulary command recognition: pass it your active phrase list, and it biases the recogniser toward those phrases while silently dropping anything else as `[unk]`. That makes it both faster *and* more accurate for commands than any Whisper variant – and you can leave Always-On running all day for $0 in API fees and near-zero CPU load. **faster-whisper** runs the same Whisper models OpenAI ships, but on a CTranslate2 C++ engine – roughly 4× faster than the original `openai-whisper` package on CPU, with much lower RAM. Choose this if you want **continuous dictation of running text** in always-on mode (every utterance gets transcribed in full, then either typed if it doesn’t match a command, or fires the matched command). **OpenAI Whisper API** sends each utterance to OpenAI’s hosted `whisper-1` model. Slightly faster end-to-end than running faster-whisper locally on most laptops, but each minute of audio costs about $0.006 – so leaving it on all day adds up. Requires an OpenAI API key in **Settings → AI Settings**. The first time you start Always-On with Vosk, the small English model (\~40 MB) auto-downloads to `/vosk-models/`. Same for the small Dutch model when your project’s target language is Dutch. Models are cached forever after the first download. ### Push-to-talk dictation engine The **Dictation engine** dropdown in the Push-to-Talk Mode group controls what handles your push-to-talk dictation hotkey (**Ctrl+Shift+Space** by default). This is independent of the Always-On engine, because the two paths have different needs: | Setting | What runs when you trigger push-to-talk dictation | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Same as Always-On** *(default)* | Auto-routes: Vosk or faster-whisper Always-On → faster-whisper push-to-talk; OpenAI API Always-On → OpenAI API push-to-talk | | **faster-whisper (offline)** | Always faster-whisper, regardless of Always-On engine | | **OpenAI Whisper API (online, fast)** | Always the API, regardless of Always-On engine. Useful pairing: Vosk for free continuous commands + OpenAI API for fast running-text dictation. | The “ℹ️ Push-to-talk will use: …” indicator below the dropdown shows the *resolved* engine (after auto-routing) so you always know which backend will run. **Why isn’t Vosk an option here?** Vosk’s grammar mode is built for fixed phrases, not free-form transcription. Pressing Ctrl+Shift+Space produces running text, which Whisper handles vastly better. So push-to-talk silently falls through to a Whisper engine even when Always-On is set to Vosk. ### faster-whisper model The Whisper model size dropdown applies whenever a Whisper engine is active – that’s faster-whisper for either Always-On or push-to-talk, *or* the OpenAI API. (The API ignores this setting and always uses `whisper-1` server-side.) Larger models are more accurate but slower and need more RAM. | Model | Download size | Notes | | ------ | ------------- | -------------------------- | | tiny | \~75 MB | Very fast, lowest accuracy | | base | \~142 MB | Good balance (recommended) | | small | \~466 MB | Noticeably better accuracy | | medium | \~1.5 GB | High accuracy | | large | \~2.9 GB | Best accuracy, slow on CPU | ### Mic sensitivity Controls the amplitude threshold used to detect speech onset. * **Low (noisy)** – raises the threshold; ignores quiet background sounds but may miss soft speech * **Medium (normal)** – default; works well in a typical home office * **High (quiet)** – lowers the threshold; captures quiet voices but may trigger on background noise ### Listen for commands only *Whisper engines only.* The checkbox is hidden when the Always-On engine is **Vosk**, because Vosk’s grammar mode already drops non-command speech at the recogniser level – the setting would be a structural no-op there. For **faster-whisper** and the **OpenAI Whisper API**: when checked, Always-On fires voice commands but discards any speech that doesn’t match a command – it is not typed. Use this if you only want voice control with a Whisper engine, not dictation. When unchecked, unmatched speech is transcribed and typed at the cursor position. ### Maximum recording duration Sets the upper limit (in seconds) for a single voice clip. Speech that exceeds this length is cut and transcribed up to the limit. Useful to prevent long silences from being held open indefinitely. ### Language * **Auto** – uses the project’s target language as the transcription hint * Explicit language – forces Whisper to transcribe in the selected language, which improves accuracy when the target language differs from the source *** ## AutoHotkey integration AutoHotkey v2 must be installed for AHK-type commands to work. Supervertaler checks for it automatically and shows the path in the AutoHotkey section of the Voice settings panel. To verify: the status line shows either the AHK path (green) or “AutoHotkey v2 not found” (orange). Click **Open scripts folder** to open the folder where standalone AHK script files are stored. *** ## Using Voice with Trados Studio Voice sends input at the Win32 hardware-input level (equivalent to physical keystrokes), which is fully compatible with Trados Studio’s WPF editor. Useful commands to add: | Phrase | Type | Action | | ------------------ | --------- | ------------ | | ”confirm segment” | Keystroke | `ctrl+enter` | | ”next segment” | Keystroke | `alt+down` | | ”previous segment” | Keystroke | `alt+up` | | ”go to top” | Keystroke | `ctrl+home` | | ”undo” | Keystroke | `ctrl+z` | After creating a command, start Always-On, click into Trados Studio, and speak the phrase. *** ## Global hotkeys | Shortcut | Action | | --------------------------------------- | ---------------------------------------------------- | | **Ctrl+Alt+A** (⌘⌥A on macOS) | Toggle Always-On listening | | **Ctrl+Shift+Space** (⌘⇧Space on macOS) | Push-to-talk (one utterance) — default, configurable | Global hotkeys work on macOS too (via the NSEvent monitor), but require Accessibility permission for whichever binary launched Python – see [Keyboard Shortcuts](/workbench/settings/shortcuts/#per-platform-notes) for setup. All hotkeys can be customised in **Settings → Keyboard Shortcuts**. *** ## Related pages * [Clipboard Manager](/workbench/clipboard/overview/) * [Keyboard Shortcuts](/workbench/settings/shortcuts/) * [General Settings](/workbench/settings/general/)