How it works, and what it cannot do yet
BetterTranslator runs a translation model on your own machine. This page states what it does today, and marks what is built but not finished.
What it is
A Windows desktop translation application for software teams. It translates words, sentences and whole documents, and it indexes the project you point it at, so established wording is kept. The models run locally.
A WPF application on .NET 10, shipped as a standalone executable. The floor is Windows 10 build 19041 or newer, and the only build target is win-x64.
Three ways in, one engine
The window, the command line and the agent tool surface are not three implementations. All three build the job through the same factory, run the same guards, and write to the same chat history.
- The window, which is the application itself.
- The bt command line, headless and made for scripts. Read the command reference
- The agent tool surface, spoken over the Model Context Protocol. Read the agent documentation
What comes back
Each format carries its own guarantee about what survives the round trip. Nothing is re-rendered from a syntax tree.
| Format | What is guaranteed |
|---|---|
| JSON | Translated value by value, never as one blob. Keys are never sent to the model. Each answer is spliced back over the bytes its value occupied, so everything else in the file comes back identical. |
| Markdown | Parsed, with only the prose sent, and each answer spliced over the text it replaced. Headings, lists, tables, quotes, fences, link and image targets, raw HTML and front matter stay byte identical. Link text and image alt text are translated. |
| Any other text file | Keeps its line count. |
| PDF, DOCX | Read with the same readers the window uses, and written back as text, because neither can be written back in place. A file named terms.pdf becomes terms.pdf.cs.txt. |
Placeholder tokens are lifted behind numbered sentinels before the text is sent, and put back afterwards. That covers curly braces, printf style tokens, HTML-ish tags, URLs, hex colours and line breaks. A batch that comes back wrong is retried one value at a time.
A format with no reader is refused by name rather than mangled, and Office lock files are skipped.
Languages
One registry of 51 languages feeds the picker in the window and the language list an agent reads. That is the set of languages that can be asked for, not the set a given model supports.
Every row carries an availability of supported, unverified or unsupported for the selected model. EuroLLM publishes a language list inside the model file, so its rows resolve either way. TranslateGemma publishes no such list, so every row reads unverified for it, and an unverified row stays selectable.
There is no source language picker yet, so text is assumed to be English on the way in.
Effort and models
The effort control chooses the model and its token budget together. Fast runs EuroLLM with a smaller budget, Thinking runs the TranslateGemma 4B GGUF with a larger one.
Effort outranks the model picker in Settings, which is only the fallback when the effort model is not installed. Both models are found by file name, never by a path composed from a catalogue identifier.
Free context, and the one switch that changes it
By default the context of a chat is free. Every send builds its whole prompt from its own text. A long chat costs no more than a new one, and no chat can leak into another. Checked against the real model: the same sentence, sent cold and again after eighty unrelated sends, comes back byte identical.
The Memory chip in the plus menu is the only switch that adds project knowledge. It contributes the earlier pairs of this chat, passages from the indexed project or folder, and the project glossary, capped at 3000 characters.
The Czech glossary that ships with the application is a worked example, not a default. Nothing is applied until you save your own from Settings.
The other two surfaces expose the same idea differently. On the agent surface, memory is an option on the text tool alone, and is off unless asked for. On the command line it is opt in for text, while a file or a folder always translates with memory on.
When the engine declines
A guard stack runs on every send and can decline an answer. The entry then says so, names the gate that stopped it, and offers a retry.
A message of more than one line goes through the document path a unit at a time. A gate that refuses one line costs that line, not the whole message. A retry is a re-roll with a different sampling seed. The runtime seeds deterministically, so an identical request returns identical bytes.
The guards can be wrong, and when they are the reader pays. Two such defects are on record, both found by translating real pasted text and fixed in what the guard measures.
Where it runs, where it is stored
Inference goes through BetterRuntime, a flat C interface over llama.cpp, with one self-contained library per backend. The model loads in a supervised child process, because the native runtime can abort in a way no managed handler can intercept. A send that hits that starts a fresh child and retries.
Runtime data sits under your profile: %LOCALAPPDATA%\BetterTranslator
What the application sends, and what it does not, has its own page. Read the security page
What is not finished
An overstating description is worse than a short one. Each item is built to some degree, and none is something you can rely on yet.
- All three runtime flavours are built, measured and wired, and each can be downloaded from the installer or its card in Settings. Only the CPU path has been run. Neither GPU offload path has been exercised on real hardware.
- The document path has been run with a real model over four Markdown documents from the command line. The Translate file button in the window has not yet been watched with a model behind it.
- The Memory workspace mode is built and locked. The Project and Folder scopes each carry a padlock, and choosing one does nothing.
- The retrieval map is not built yet.
- There is no source language picker.
- No build has been published yet, so there is nothing to install from this site.