Guide
For version 0.1.0
Installing and permissions
Drag ShotTrans into your Applications folder and open it. It lives in the menu bar — it has no Dock icon and no main window. Look for the closed-book icon at the top right of your screen.
Screen Recording permission
The first time you draw a capture box, macOS asks for Screen Recording permission. This is not optional and not specific to this app: anything that reads pixels off your screen needs it, and without it captures come back blank.
Grant it under System Settings → Privacy & Security → Screen
Recording, tick ShotTrans, then restart the app — macOS
requires the restart before the permission takes effect.
If ShotTrans is already ticked and captures still fail, the app was
rebuilt and its signature changed, so the old grant no longer applies.
Remove it from the list with the − button and add it again.
Two ways to translate
| What it does | Default shortcut | When to use it |
|---|---|---|
| Capture & translate | ⌥A | Text you can't select: PDFs, games, video, images |
| Type to translate | ⌥D | You know the words but not the translation |
Both shortcuts are yours to change under Settings → Shortcuts.
Capture & translate
Press the shortcut, drag a box around the text. Recognition happens on your Mac using Apple's Vision framework — the image itself is never uploaded, only the recognised text is sent to whichever engine you've enabled.
You don't have to box the text precisely. If your selection cuts a sentence in half, the app looks slightly beyond the edges to complete it, then translates the whole sentence. Turn this off under Auto-complete in the menu if you want strictly what you selected and nothing more.
Type to translate
A plain input window. Useful in the other direction — you know what you want to say and need it in another language. Results appear in the same window.
Choosing languages
Both windows have a direction picker at the top. The defaults are Auto-detect → your system language.
- Auto-detect reads the text and works out the language. It stays showing "Auto-detect" — it never quietly rewrites itself to whatever it guessed. What it decided is shown next to the original text.
- If the text turns out to be in your target language already, translating it would be pointless, so the target switches — usually to English — and the picker updates so you can see it happened.
34 languages are available. The eleven most common sit at the top level of the picker; the rest are under More languages.
Translation engines
Every enabled engine translates at once and the results are stacked, so you never wait on the slowest one.
Local translation — no setup
macOS has a built-in translation framework. It's offline, free, unlimited, and already switched on. Quality is below the cloud services, which is why it sits last in the priority order, but it means the app is useful the second you install it.
Language packs are downloaded by macOS, not by us. If a pair isn't installed yet, that row says so and offers an Install link straight to the right settings pane.
DeepL and Microsoft — classic machine translation
These two are the ones to add first if you want fast, cheap translation with a real free allowance, and neither needs anything more than an email address to sign up for.
| Engine | Free allowance | Worth knowing |
|---|---|---|
| Microsoft Translator | 2,000,000 characters a month | The largest free tier here, and the widest coverage — all 34 languages, Cantonese and Literary Chinese included. Create a Translator resource in the Azure portal on the F0 tier, then copy both the key and the region. A missing region and a wrong region give the same 401, so check it before you blame the key. |
| DeepL | 500,000 characters a month | Widely held to be the best quality for European languages. It covers fewer
languages than the others — no Cantonese, Literary Chinese, Thai, Vietnamese,
Malay or Hindi — and the app tells you so rather than failing at request time.
Free keys end in :fx; the app notices and uses the right host by
itself. |
Custom AI channel — anything speaking the OpenAI format
Anything that speaks the OpenAI chat API works here: OpenAI itself, OpenRouter, most proxy services, and a local Ollama or LM Studio.
| Field | What to enter |
|---|---|
| API Key | From your provider's console. For a local Ollama, any non-empty string. |
| Model | Click the ⌄ beside the field to fetch the models your key can actually call. Don't guess — model names get retired. |
| API base URL | Up to /v1 and no further — leave off the trailing /chat/completions. Local Ollama is http://localhost:11434/v1. |
Large language models translate noticeably better than classic machine translation on prose, and they cost per token rather than per character.
OpenAI, Claude, Google Gemini, xAI Grok and Mistral each have their own entry in the list, already pointed at the right endpoint — you only paste a key and pick a model. Gemini has a free allowance; the rest bill per token. Anything else that speaks the OpenAI format — OpenRouter, a proxy, a local Ollama — goes in the generic Custom AI channel entry.
Engines aimed at the Chinese market
Baidu Translate, Tencent Translate, DeepSeek, Kimi, Zhipu GLM and Doubao are all supported and all have generous free tiers — but registering for them generally needs a mainland Chinese phone number and identity verification. If you have those accounts, the settings panel walks you through each one. If you don't, skip them: local translation plus DeepL or Microsoft covers everything.
Not sure what a field wants? Take a screenshot of the settings page and ask any AI assistant what goes in each box. They know these providers' consoles and will tell you where to copy each value from.
Order matters
The order in the engine list decides two things: how the results are stacked, and which engine's translation gets saved to your history and wordbook — the topmost successful one. Drag to reorder.
Wordbook and history
Every translation is kept locally. Star one and it moves to the Wordbook, which shows the original and the translation with larger type, pronunciation, and — if you ask for it — an explanation generated by whichever language model you configured.
That explanation costs money on your own API account, so the app asks before generating one, and caches the result forever. Asking again for the same word never bills you twice.
Both the wordbook and the full history can be exported: JSON for moving to another machine, Markdown for reading elsewhere.
When something goes wrong
| What you see | What it means |
|---|---|
| "No text recognised" | The selection missed the text, or caught only a fragment. Try a slightly wider box. |
| An engine says it doesn't support a language | Classic machine translation has a fixed language list set by the provider. Language models don't — configure one and that language works. |
| "Cooling down" | That engine failed three times in a row, so it's skipped for five minutes rather than making you wait on it every time. |
| "Quota used up" | The provider's free monthly allowance is gone. It resets next month; other engines carry on. |
| A shortcut does nothing | Another app claimed it first. macOS offers no way to query third-party shortcuts, so we can't always warn you — pick a different key. |