InstaTrans

In-place translation and grammar correction for macOS, powered by LLMs & Apple Translation.

---

InstaTrans is a premium, lightweight macOS menu bar utility that allows you to translate or proofread selected text directly in-place inside any active application. By combining the speed of local Apple Translation, the depth of Google Gemini, and the privacy of offline Ollama LLMs, InstaTrans streamlines your daily writing and reading workflows.

---

Features

• Dual Global Hotkeys (Stateless UI):
  • ⌥ T (Translate): Translates selected text directly into your target language.
  • ⌥ F (Fix Typos & Grammar): Fixes spelling, punctuation, and grammar mistakes in-place (automatically detects the language and edits it in-place without translating).
• Multi-Engine Support:
  • Apple Translation: Native macOS system translation with automatic language detection.
  • Gemini API: Highly contextual, state-of-the-art translations using Google's gemini-3.1-flash-lite models.
  • Ollama (Local LLM): Complete offline translation/proofreading using models like translategemma.
• Custom Translation Tones:
  • Tailor your LLM translations with predefined tones: Standard, Professional / Business, Casual / Informal, Formal / Polite, and Slang / Conversational.
• Universal Accessibility Fallbacks:
  • Uses macOS Accessibility APIs first for native reading/writing.
  • Falls back to simulated keyboard copy/paste (Cmd+C / Cmd+V) for Chromium/Electron apps (e.g., Slack, WhatsApp, Discord) with clipboard history preservation.
  • Auto-Select: Automatically simulates Cmd+A to select all text in the active text field if no manual selection is active (configurable).
• Multi-Space & Fullscreen Support:
  • A custom invisible hosting window enables background SwiftUI translation tasks to run seamlessly across virtual desktops (Spaces) and fullscreen windows.
• Secure Credentials:
  • API keys are stored securely inside the macOS System Keychain using AppKit Keychain Services APIs.
• Structured Task Concurrency:
  • Structured tasks are automatically cancelled if overlapping shortcuts are triggered, preventing API rate limit issues and saving API credits.

---

Architecture

InstaTrans is built with a highly decoupled, modular Swift architecture:

Sources/
├── Accessibility/    # Native AXUIElement accessibility & keyboard simulation fallbacks.
├── App/              # Application delegates, status menus, and state controllers.
├── Hotkeys/          # System-wide carbon hotkey event registration.
├── Support/          # User default keys, Keychain wrappers, and shared configurations.
├── Translation/      # Apple, Gemini, and Ollama engine clients.
└── Views/            # SwiftUI modular settings panes.

---

Getting Started

Installation (Ready-to-Use)

1. Download the latest compiled release archive InstaTrans-v1.0.0.zip from the Releases page.
2. Decompress the downloaded archive.
3. Drag InstaTrans.app to your /Applications folder and open it.

Required Permissions

InstaTrans requires Accessibility permission to read and replace text in other apps.

1. When prompted, open System Settings -> Privacy & Security -> Accessibility.
2. Toggle InstaTrans to ON.

Building from Source (For Developers)

Prerequisites

• macOS 12.0 or newer
• Xcode 14.0+ / Swift 5.8+

Compilation

1. Clone the repository:

   git clone https://github.com/dendyelo/InstaTrans.git
   cd InstaTrans

2. Build and package the release .app bundle:

   ./build_app.sh

   The compiled, code-signed bundle will be generated at ./InstaTrans.app. Drag it to your /Applications folder.

---

Configuration

1. General Settings

Open the Settings panel (⌘,) from the menu bar to:

• Configure and record custom hotkeys for Translate and Proofread actions.
• Toggle Auto-Select text capture.
• Verify Accessibility permission status.

2. LLM Engine Setup

• Gemini API: Generate an API key from Google AI Studio, and paste it into the Engine Settings.
• Ollama: Start your local Ollama server (defaults to http://localhost:11434), pull a model (e.g., translategemma), and select it in the Engine Settings.

---

Running Unit Tests

InstaTrans comes with a comprehensive suite of unit tests verifying all workflow states, LLM prompt templates, preference storage, and clipboard snapshot lifecycles:

swift test

---

License

This project is licensed under the MIT License - see the LICENSE file for details.