Select text, press the shortcut, and view an AI translation near the selection.
简体中文 · English
WordSnap is a lightweight desktop selection-translation utility. Select copyable text in any application, then press Option+T on macOS or Alt+T on other platforms to display the translation near the selection. Foreign-language input is translated into the configured target language. Simplified Chinese input is translated into natural English.
Application settings and saved words remain on the local device. When a translation is requested, the selected text is sent to the OpenAI-compatible API configured by the user.
Download the latest release · Contributing · Privacy · Security
- Translate copyable selected text in any application by pressing
Option+TorAlt+T. - Translate foreign-language text into the selected target language and Simplified Chinese into natural English.
- Display the translation near the selection and close a completed card by clicking outside it.
- Remain visible over native full-screen applications and multiple Spaces on macOS without taking focus from the current application.
- Save only a single ASCII English word, optionally containing a hyphen, to the local SQLite word list.
- Update the translation, lookup count, and most recent lookup time when a word is queried again.
- Provide access to the word list, settings, and quit action from the menu bar or system tray.
- Support a custom OpenAI-compatible Base URL, model ID, and target language.
- Include no account system, cloud synchronization, advertising, or telemetry.
Download the portable build or installer for the current platform from GitHub Releases.
| Platform | Recommended download | Other formats |
|---|---|---|
| macOS Apple Silicon | WordSnap_<version>_macos-aarch64_portable.zip |
.dmg |
| macOS Intel | WordSnap_<version>_macos-x64_portable.zip |
.dmg |
| Windows x64 | WordSnap_<version>_windows-x64_portable.zip |
.msi, NSIS .exe |
| Linux x64 | .AppImage |
.deb, .rpm |
Portable builds do not require an installer. On macOS and Windows, extract the archive and run WordSnap.app or WordSnap.exe. Before running an AppImage for the first time, execute chmod +x WordSnap_*.AppImage.
Note
Current releases are not code-signed. If macOS Gatekeeper prevents the first launch, right-click WordSnap.app and select Open, or run xattr -cr WordSnap.app. Windows SmartScreen may also display a security warning.
- Start WordSnap and select its icon in the menu bar or system tray.
- Open Settings and enter the API key.
- Modify the Base URL, model ID, and target language if required.
- Select copyable text in any application.
- Press
Option+Ton macOS orAlt+Ton another platform, then view the translation.
The default configuration is as follows:
| Setting | Default value |
|---|---|
| Base URL | https://api.openai.com/v1 |
| Model | gpt-4o-mini |
| Target language | Simplified Chinese |
On macOS, selection capture may require Accessibility permission. If WordSnap cannot read text that is already selected, allow WordSnap under System Settings, Privacy & Security, Accessibility.
The Base URL may include or omit its scheme. WordSnap normalizes the address and appends /chat/completions when required. An address that already ends with this path is used without modification. Remote services should use HTTPS. Plain HTTP is appropriate only for an explicitly local development endpoint.
Tauri stores local data in the application data directory assigned by the operating system:
settings.json: stores the API key, Base URL, model, and target language.wordsnap.sqlite3: stores English words, translations, lookup counts, and timestamps.
Runtime logs are stored in the project root logs/ directory. Every application start creates a
separate YYYY-MM-DD_HH-mm-ss.SSS_pid-<process-id>.log file. All DEBUG, INFO, and ERROR
entries for that application session are written to the same file until the application exits. Logs
cover startup, initialization, hotkeys, clipboard handling, translation requests, database
operations, windows, settings, and shutdown. They contain diagnostic metadata such as events,
outcomes, durations, character counts, and HTTP status codes. They do not contain API keys, selected
text, translations, clipboard contents, complete service responses, or configured endpoint addresses.
Important
Selected text is sent to the API service configured by the user. The API key is currently stored as plain text in the local settings.json file, and the application does not use the system credential store. Read Privacy and data handling before use.
- Node.js 20 or later and npm.
- Rust stable with
rustfmtand Clippy. - The Tauri 2 system prerequisites for the current platform.
- An OpenAI-compatible API key.
git clone https://github.com/YunFy26/WordSnap.git
cd WordSnap
npm ci
npm run tauri devnpm run check
npm run audit
npm run tauri build| Command | Purpose |
|---|---|
npm run build |
Type-check and build the Vite frontend |
npm run format:check |
Check Rust formatting |
npm run lint |
Run strict Clippy checks for all Rust targets |
npm test |
Run the Rust unit tests |
npm run check |
Run the frontend build, formatting check, Clippy, and tests |
npm run audit |
Check high-severity dependency advisories through the official npm registry |
npm run tauri dev |
Start the complete desktop development environment |
npm run tauri build |
Build application packages for the current platform |
npm run icons |
Regenerate application and tray icons from the source files |
Run npm run audit whenever dependencies change. Local packages are written to src-tauri/target/release/bundle/.
- When the shortcut is triggered, the application records the current pointer position.
- The application saves the clipboard, simulates a copy operation to read the selection, and attempts to restore the original clipboard content.
- The application constructs an OpenAI-compatible
/chat/completionsrequest from the input and user settings. - The loading state and translation result are displayed near the selection.
- After translation completes, clicking outside the card hides the popup.
- If the input is a single ASCII English word, the application inserts or updates the corresponding local word-list record.
Phrases, sentences, Chinese text, and failed translations are not written to the word list.
.
├── docs/ # Privacy information, release instructions, and demonstrations
├── scripts/ # Icon generation scripts
├── src/ # TypeScript window views and styles
├── src-tauri/ # Tauri configuration, Rust backend, and application resources
│ ├── capabilities/ # Tauri permissions available to the frontend
│ ├── icons/ # Application and tray icons
│ └── src/lib.rs # Shortcut, selection, translation, word-list, and window logic
├── CONTRIBUTING.md # Contribution workflow
├── SECURITY.md # Vulnerability reporting process and support scope
└── package.json # npm commands and frontend dependencies
The primary entry points are:
src-tauri/src/lib.rs: application state, global shortcut, selection capture, translation requests, SQLite, windows, and tray.src/main.ts: translation popup, word list, settings, and menu views.src/styles.css: all production interface styles and light or dark theme behavior.src-tauri/tauri.conf.json: window, package, and Tauri security configuration.
CIruns the frontend build, Rust formatting check, Clippy, tests, and npm audit for pushes and pull requests targetingmain.Releasebuilds macOS Apple Silicon, macOS Intel, Windows x64, and Linux x64 packages for each push tomain, then publishes a GitHub Release.
See Release workflow for package formats, portable builds, and unsigned-release behavior.
- Confirm that WordSnap is running and that no other application has registered
Option+TorAlt+T. - Check Accessibility permission on macOS.
- Confirm that the selected text can be copied normally.
- Check the API key, Base URL, and network connection.
- Confirm that the current API key is authorized to use the selected model.
- Do not disclose API keys or private text in issues, logs, or screenshots.
General problems can be submitted through GitHub Issues. Vulnerabilities must be reported privately according to the Security Policy.

