MagicTranslate · User Guide

The offline-first translator in your macOS menu bar: selection, screenshot, typing, and long-form bilingual reading. Local features are free forever — no account, and your text never leaves your Mac.

Quick Start

Open the downloaded MagicTranslate.dmg, drag MagicTranslate into your Applications folder, and double-click to launch.

MagicTranslate is a menu bar app: it doesn't occupy the Dock and lives in the top-right of your screen. It's ready out of the box — no upfront permissions: type-to-translate, clipboard translation, the dictionary and bilingual reading all work right away. Two system permissions are optional and requested only when needed:

1. Screen Recording (for screenshot translation / OCR) — the first time you use screenshot translation, macOS shows the permission prompt; grant it and retry.
   System Settings → Privacy & Security → Screen Recording → check “MagicTranslate”.
2. Automatic text capture (optional enhancement) — when enabled, selection translation reads the text you selected in other apps automatically; without it you can still translate: copy the text and press the shortcut, or use “Translate Clipboard” in the menu bar.
   In-app Settings → Privacy → “Enable Automatic Text Capture” (uses the system Accessibility permission; text is read only when you actively trigger a translation).

Ready out of the box: the default engine is Local Fast (Apple's system translation — offline, free, unlimited), zero setup, zero accounts.

Shortcut Cheatsheet

Everything is remappable (or clearable) in Settings → Shortcuts. “Read selection aloud”, “Finder image OCR” and “Bilingual Reading” ship unassigned — bind them if you like.

Selection Translate

In your browser, a PDF, a chat window — select some text in any app and press ⌥ D; the translation appears instantly. You can also enable the double-tap modifier gesture in Settings (e.g. double-tap ⌥).

Reading the selection automatically requires “Automatic Text Capture” (Settings → Privacy, optional); without it ⌥ D opens an input window — paste and translate.

Two result styles, switchable anytime

• Full window (default): several engines and the dictionary on one screen — best for careful comparison;
• Compact popup: a small card right by your cursor — read and move on, or pin it (📌) to keep it around.

What you can do on a result card

• Copy / read the translation aloud; click the engine name to retranslate with another engine in place;
• Click the pencil to edit the original and retranslate (fix typos / remove stray line breaks);
• Compare engines side by side; press ⌘ K for AI Actions.

Screenshot Translation & OCR

Press ⌥ S, the screen dims, then drag to select any area — text in images, video subtitles, scans, code comments all get recognized and translated. Recognition runs on-device (Apple Vision, offline).

Helpful for low-vision users too: tiny on-screen text or unselectable text inside images becomes clear, readable text with one selection; in the result window both the original and the translation can be read aloud (🔊), so you can listen to what's on screen instead of straining to see it.

Consecutive capture & stitch (great for long content)

Chat logs, paginated PDFs, long scrolling pages that don't fit one screen? Do this:

1. ⌥ S and select the first part — the result appears;
2. Click the ⊕ keep capturing icon in the result window (a hint highlights it the first time);
3. Scroll, select the next part — new text is appended to the original and the whole piece retranslates;
4. Repeat until done; the translation is always one complete text.

Other recognition entries

Type to Translate & the Main Window

⌥ A opens the main window — type or paste, press Return to translate (⇧ Return for a newline). The menu bar icon also has a one-click “Translate Clipboard” entry.

Multiple translation slots (several engines at once)

Click “＋ Add Translation” under the results to translate the same text with several engines side by side: Local Fast, the local LLM, the dictionary, your cloud engines… Each slot can switch sources independently, be added or removed, and the layout is remembered.

Top bar icons: pin the window, switch to the compact popup, history, Model Market, settings. The language row supports auto-detect and one-key swap (⇧⌘X).

Bilingual Reading / Document Translation

Menu bar → “Bilingual Reading / Documents…”. The right way to read whole articles, web pages, and books:

• Three sources: paste long text / enter a URL / import documents (TXT, Markdown, PDF, EPUB, DOCX, SRT/VTT subtitles);
• Paragraph-level bilingual view, streaming in paragraph by paragraph — read as it translates;
• Retranslate any single paragraph with a different engine; export the whole piece as a bilingual PDF;
• Switching target language / engine reruns the document; finished paragraphs restore instantly from cache.

Live Captions (macOS 26+)

Designed for deaf and hard-of-hearing users: it turns the system audio of any app into real-time on-screen text — videos, meetings, podcasts, online classes — so every sentence you can't hear (or can't hear clearly) can be read instead; add translation (bilingual captions) and audio in a foreign language becomes accessible too. Menu bar → Live Captions to start. Transcription and translation (Apple language packs) both run on-device. The first launch asks for the Screen Recording permission — ScreenCaptureKit needs it to capture system audio.

• Accessibility first — “Original Only” mode is pure same-language captioning, giving deaf and hard-of-hearing users the same information hearing users get; “Bilingual / Translation Only” turns audio you don't understand into text you do; four font sizes (up to 40 pt) help low-vision scenarios as well;
• Hover to configure — move the mouse onto the caption bar and switch everything in place: audio language, translation language, display mode (bilingual / translation only / original only) and font size (S / M / L / XL); drag the bar to reposition it;
• Bilingual captions — translation on top, original below; pick a target in “Caption Translation” to turn it on. The first time you use a language pair macOS may offer to download a language pack — click Download once;
• Live translation — the translation streams in while the sentence is still being spoken, then the final version replaces it;
• Quiet badge — with no audio the captions shrink to a small badge that doesn't cover the picture, and come back automatically;
• Session export — stopping captions shows a session summary: export SRT / VTT (bilingual / translation only / original only) or copy the transcript; the session is saved to History and its segments feed the translation memory.

Supported audio languages: English, Simplified/Traditional Chinese, Japanese, Korean, French, German, Spanish. The menu-bar Live Captions submenu and the hover bar are equivalent — use either.

Dictionary & Vocabulary Book

Select a single word and the dictionary card appears right next to the translation — no app switching to look things up.

• Dictionary sources: Cambridge Dictionary (rich online entries) → automatic offline fallback to the system dictionary / built-in CC-CEDICT / CMUdict phonetics;
• Vocabulary Book: looked-up words are collected automatically (can be turned off), frequent ones tagged “looked up N times”; built-in review mode, plus Anki export;
• If Chinese entries ask you to enable a wordbook: open the system Dictionary app → Settings → check a Chinese dictionary.

History & Favorites

Menu bar → “History” (there's also a clock icon in the main window's top bar). Every translation is kept: original, translation, the engine actually used, and the time. Search by original or translation, star favorites (they get their own tab). All history lives on this Mac and keeps working in Privacy Mode.

AI Actions (⌘K)

Press ⌘ K in the main window or popup to run Polish / Summarize / Rewrite / Fix Grammar and more on the current text, with streaming output. You can also define custom action templates in Settings (e.g. “rewrite as marketing copy”).

AI Actions are powered by the local LLM (download once in Model Market — then fully offline and free), or by any cloud engine you've configured.

Shortcuts & Automation

Apple Shortcuts

Search “MagicTranslate” in the Shortcuts app for the “Translate Text” action: pass in text, choose a target language and engine, and it returns the translated string — chain it into any flow, like “translate clipboard → show notification” or “batch-translate selected filenames”. Runs in the background with no UI.

URL scheme (for third-party selection tools)

• magictranslate://translate?text=hello — open the translation window
• magictranslate://reader?url=https://… — send a page to Bilingual Reading

Translation Engines

Model Market (local LLMs, one click)

Menu bar → “Local Model Market…”. It rates what runs smoothly on your chip and RAM — pick one and click Download (resumable, checksum-verified; switch to the China mirror if you're on a network in mainland China). Once downloaded it's ready — no command line, ever.

API keys are stored only in the macOS Keychain and never uploaded; a confirmation dialog appears before text is first sent to a cloud engine (can be disabled).

Settings in Depth

Menu bar → “Settings…” (or the gear in the main window, ⌘ ,). Grouped navigation on the left: Translate (General / Services / Shortcuts), Data & Privacy (Privacy / Glossary & Persona), About.

General

• Launch at login — live in the menu bar from sign-in;
• Watch clipboard and translate automatically — whatever you copy gets translated (handy in bursts of foreign-language reading);
• Appearance — follow system / light / dark;
• Default languages — keep the source on “Auto-Detect” (mixed text is handled intelligently); the target language is what you translate into.

Services (engines, OCR, speech)

• Three tabs on top: Text Translation / Text Recognition (OCR) / Speech Synthesis;
• The “Built-in” group is always on with zero setup: Local Fast, local LLM, Cambridge Dictionary, system dictionary; the Default Engine dropdown decides what selection translation and the main window use first;
• “More services” are bring-your-own-key cloud engines: pick one → enter credentials on the right → “Verify & Enable”. The switch only unlocks after verification passes (honesty gate: not configured, not enabled).

Shortcuts

• Double-tap modifier to translate — double-tap ⌥ (or ⌃/⇧/⌘, three sensitivity levels) to translate the selection without using up a hotkey;
• Menu bar left-click action — show menu / open main panel / translate clipboard (right-click always shows the menu);
• Global shortcuts — rebind anything or clear it with ⊗; conflicts are flagged immediately.

Privacy

• Privacy Mode — fully offline with one switch (same as ⌃ ⌥ P); “Verify Offline” actually tests the blocking, with a counter of intercepted requests beside it;
• Confirm before using cloud engines — a dialog before text first goes to the cloud, with “don't ask again”;
• Permissions — Accessibility / Screen Recording status at a glance, with one-click jumps to System Settings.

Glossary & Persona

• Translation persona — the overall style applied to the local LLM and cloud LLMs (standard / more casual / more formal…);
• Glossary — enforced “source → target” renderings (with optional domain and priority), CSV import/export; team terms, names and product names never get mistranslated again.

About

Version info, quick links to User Guide / Feedback (this site), and license notes for models and dictionary data.

Privacy Mode

⌃ ⌥ P to enter: every network-facing service is disabled (cloud engines, online dictionary, model downloads); translation, OCR and speech all run on-device — peace of mind for contracts, internal docs, private content.

• Menu bar → “Privacy Weekly”: honest stats on local vs. cloud processing and blocked outbound requests;
• History, vocabulary and all other data stay on this Mac.

FAQ

Which Macs are supported?

macOS 15 or later with Apple silicon (M1 and newer). Intel Macs aren't supported by the current version.

Translation spins forever / says a language pack is missing?

Local Fast needs a one-time system language pack per direction: download when macOS prompts. If no prompt shows, retry once in the main window, or grab it in Model Market → Apple Language Packs.

Selection translate doesn't react?

Automatic text capture is an optional enhancement: enable it in in-app Settings → Privacy → “Enable Automatic Text Capture” (which uses System Settings → Privacy & Security → Accessibility). Without it, the selection shortcut opens an input window — paste and translate; or copy first and use “Translate Clipboard” in the menu bar. After app updates macOS may require re-granting (remove, then re-check).

Screenshot translation shows black / recognizes nothing?

Check the Screen Recording permission. Empty recognitions stay silent by design — try a clearer area.

Live Captions missing from the menu / not reacting?

Live Captions requires macOS 26 or later (the menu item is hidden on older systems); grant the Screen Recording permission when prompted (used to capture system audio). Translation on but nothing shows: download the language pack when macOS offers it, or grab it in Model Market → Apple Language Packs.

Local model download slow / failing?

Switch the download mirror in Settings (recommended on networks in mainland China); downloads resume automatically — just retry.

Simplified ↔ Traditional Chinese?

Just pick the target variant: conversion runs on-device via ICU glyph mapping, returns in milliseconds, and is honestly labeled “Simplified ⇄ Traditional · glyphs only” (no vocabulary localization — e.g. 内存 won't become 記憶體).

Cloud engine says “No API key configured”?

Cloud engines use your own key (costs under your control, privacy in your hands): Settings → Engines → pick a service (each links to a how-to) → enter the key → “Verify & Enable”.

Feedback

Found a bug, a bad translation, or missing a feature you need? Write it below — every single entry gets read. In the app: menu bar → User Guide & Feedback leads right here.

Type Translation quality Feature request Bug / crash Other Description (required; for bugs please include steps and what happened) Contact (optional; email so we can follow up) App version (optional; see Settings → About) Screenshot (optional; PNG/JPG/WebP, ≤ 2 MB — a screenshot speeds up diagnosis a lot)

Remove screenshot

Submit Feedback

To prevent abuse, up to 5 submissions per day; screenshots are used only for diagnosis and never shown publicly.