Repository navigation
Translate
Translate replaces the text on your screen with a translation, in place: the original glyphs are erased from the picture and the translation is drawn where they were, with matching colour, size and alignment. It is built for games, but works on anything you can see.

Before (left) and after (right). The translation takes the original's place.
Two ways in, all from the same bar or keys:
-
Translate on a selection (the bar, or
Alt+Shift+Tfor the whole screen). - Select text, then Translate, for only the words you picked.
- OpenCircle captures the screen.
- Text is read on your PC (OCR).
- The text is translated in sentence-sized blocks, by your AI provider or offline on your PC (see Engines). With AI, only text goes out, not the picture.
- The original text is erased and the translation is drawn over the result. Names and items that the game shows in a highlight colour keep that colour when the AI marks them.
Pick the languages in Settings → Translate: Source (what the text on screen is in; Detect automatically is the default) and Target (what it is translated into; the first-run setup's Your language step sets it, and until then it is your system's language, or English). Right-to-left targets (Arabic, Persian, Urdu, Hebrew) are laid out right-aligned.
While translating, the pill at the top shows the pair (Detect → Arabic);
click either side to switch for this session, with your recent picks first
and a search field for the rest. The pill's Snip button, after the language
chips, takes the translated page into Snip (see
Snip and annotate). Copy, Save, Copy text or Esc in Snip bring you back to the translated screen.
Reading the text (OCR) needs a model for the source's script. English is the default; the first time you pick a source in another script, OpenCircle asks before downloading its model (about 8 MB; Chinese and Japanese about 17 MB):
| Script | Source languages |
|---|---|
| English | English (also Detect automatically) |
| Latin | French, German, Spanish, Portuguese, Italian, Dutch, Polish, Turkish, Indonesian, Vietnamese |
| Arabic | Arabic, Persian, Urdu |
| Cyrillic | Russian, Ukrainian |
| Chinese and Japanese | Chinese (Simplified, Traditional), Japanese |
Detect automatically reads with the English model; when the result looks wrong (lines it couldn't read, or not in its script), it tries the other models you have downloaded and keeps the best. So pick a source in another script once (its model is then on your PC) and detection finds it from then on. Hebrew, Hindi, Thai and Korean can be targets but not sources yet.
Choose one in Settings → Translate → Engine.
-
Offline (the default) needs no key and no account, and nothing leaves your PC. It is a small neural translation model (OPUS-MT, by the University of Helsinki) that runs on your CPU: about a third of a second for 20 game lines, fast enough for game text. It is more literal than AI, can miss the game meaning of a word ("Quit" as in leaving, "pelts"). One model per direction; the first time you use a direction, OpenCircle asks before downloading it (about 108-116 MB, plus the text-recognition files if they are missing, checked against pinned checksums). Most come from Hugging Face; the direct Arabic ones (below) come from AmerAlreyahi/OpenCircle-models on GitHub. Licences and credits are in NOTICE. The decoders are the lighter build, the OptimaMT models (OPUS-MT with the output layer built once instead of twice: the same translations, less memory; 501 -> 256 MB in the helper, measured for one pair). A download that hits a server error or a dropped connection retries by itself and resumes where it stopped.
Where they are kept. Each pair has its own folder in your local data folder,
OpenCircle/mt/OptimaMT-<from>-<into>(for exampleOptimaMT-en-ar, the name of its OptimaMT repository). Folders an older version namedopus-mt-<from>-<into>are renamed to this once, when OpenCircle starts: the same files, nothing is downloaded again. (An older version of OpenCircle does not know the new names and downloads its models again.)Older, heavier decoders. A pair downloaded before v0.1.4 still has the first decoder. It keeps translating, and the next time you translate with it, OpenCircle downloads the lighter decoder for that pair in the background (about 57-60 MB; both pairs of a route through English), after the translation is on screen. The pill shows a quiet line with its progress. The new file is checked against its pinned checksum and takes the old one's place when the pair is no longer loaded (when translation has been idle for a minute, or at the next translation), so only one copy stays on disk. If the download is interrupted (no internet, the app closed), the old decoder keeps working and the next translation continues it. Settings → Translate → Translation models shows how many pairs still have the older decoder and updates them all at once (Update now, with its size; Cancel keeps what was downloaded). Nothing is downloaded unless you translate or press that button.
From Into English Arabic, French, Spanish, German, Russian, Chinese (Simplified), Italian, Dutch, Ukrainian, Portuguese (Brazilian), Hindi, Indonesian, Vietnamese Arabic, French, Spanish, German, Russian, Italian, Dutch, Ukrainian, Polish, Portuguese, Hindi, Indonesian, Vietnamese, Thai, Korean, Chinese, Japanese English Spanish French, German, Italian, Russian French Spanish, German, Russian German Spanish, French Italian Spanish, French Russian Spanish, French, Ukrainian Ukrainian Russian Dutch French French, Spanish Arabic Arabic French, Spanish, German The last two rows are direct models we converted ourselves (so are the two Portuguese ones, from Helsinki-NLP's multi-language Romance models), so these pairs take one model instead of two through English: about twice as fast, and as good as or better than going through English on our test pages. Other pairs go through English when both halves exist (for example Italian into Arabic: Italian to English, then English to Arabic): two models, a bit slower and a little looser. A pair with no way offline (for example into Korean) is not available offline: OpenCircle says so and offers AI (it never sends the text anywhere you didn't choose). With Detect automatically, the direction follows the script of the text it read; Latin text is told apart by its common words (English, Spanish, French or German). Detecting needs no download: only the translation model does.
-
AI uses the provider from AI setup. It is best at context and at marking names in their highlight colour; with a local model it stays on your PC. Pick it in Settings → Translate → Engine. If no AI provider with a key is set up, OpenCircle translates offline instead, so translation works without a key.
-
Online sends only the text it read (never the picture) to Google's free web translator, one-shot Translate only. It is unofficial: when it doesn't answer, OpenCircle translates offline instead. Nothing is sent unless you pick it in Settings → Translate → Engine.
Offline, a highlighted name inside a line is drawn in the line's colour: the model can't say which translated words are the name. A line drawn entirely in a highlight colour keeps it.
Explain on a word card always asks your AI provider.
A game's menu, quest log or HUD reads differently from a web page, so on a screen that looks like a game (no browser address bar on it) Translate works to keep the screen usable:
- It fits. A long translation shrinks (to about 70 %) to stay inside its button or label; if it still does not fit, a one-line label is cut at a word with "..." and a paragraph is never cut (the original stays instead).
- Names stay. A character's or a place's name inside a short line is kept as written, not translated into a common word ("Marco" does not become "Framework").
-
Counters survive.
x10,Lv. 80,21msand the like keep their form. - A glossary you made for the game decides names better still (next section).
Games must be borderless or windowed (see below).
A glossary is a short list of terms for one game: a name to keep as written, or the translation you want for a word. It is guided into the offline translation and, with AI, offered to the provider as the names to use; it never changes a word outside the terms. Matching ignores case and accents.
- Where. On a game screen only: the pill's book button, and the word card's dotted names, appear there and never in a browser or a normal app. Each game has its own glossary; a game without one gets none (never the last game's).
-
Make one. Settings > Translate > Glossary opens the editor: New,
Rename, Import, Export, Delete, and a table of terms (a term with an empty
translation is kept as it is). On the translated screen, click a dotted name
on the word card (or press
G) to add it from there. - Which game. Where the system gives the focused window's title (Windows and X11), a glossary's Use for windows named list picks it by itself when that game is in front. On Wayland the desktop doesn't tell, so you pick the glossary on the pill and it stays until you change it; the pill shows which one is active. OpenCircle never looks into the game's process.
-
Share. A glossary is one TOML file in OpenCircle's
glossariesdata folder; Export writes it, Import reads one (up to 1 MB and 5000 terms). Importing into a game that already has a glossary merges: new terms are added, your own translations win over the imported ones, and a summary tells you ("12 terms added, 3 kept yours, 0 duplicates"). - Suggested names. When the same name shows up on at least three different translated screens of a game, a small dot with a count appears on the pill's glossary button. Open the list and keep the name as it is, give it a translation, or reject it (rejected names are not suggested again). Nothing appears during play on its own, and nothing leaves your PC.
- Big outlined subtitles (a film's or a game's: white or yellow with a dark outline over a moving picture) are erased as a whole, not in slivers, and the translation is drawn at the subtitle's size. Lines a subtitle splits in two are joined before they are translated.
- A browser's address bar, file names and e-mail addresses are left exactly as they are, and a lone letter (an icon read as "X") is not translated.
Press Alt+Shift+T. The whole screen is translated at once and shown in
place. Esc closes it.
-
Click a translated block to open a card with the meaning, the
translation, and a one-line explanation in the context of the scene. Press
Athere to continue as an AI chat.
No application can draw over a game in exclusive fullscreen. Switch the game to borderless ("fullscreen windowed") or windowed mode for the translation to appear over it.
- Very large erased areas over busy art can show smudges; translation quality depends on the OCR and on the model you use.
- Drawing a translation in a script OpenCircle doesn't bundle a font for (Cyrillic, Chinese, Japanese, Thai, ...) uses your system's fonts. Windows has them; on Linux install a font for that script (for example Noto Sans CJK).
- With AI, the text it read is sent to your AI provider. Use the offline engine or a local model to keep everything on your PC.
This page is generated from docs/translate.md. Edit it there; changes made here are overwritten.