HoverTranslate

HoverTranslate is a lightweight, native macOS menu bar application that provides instant, seamless translation right where your mouse is. Simply hover over text or select it, and HoverTranslate will instantly recognize and translate it for you—no need to switch between apps or interrupt your workflow.

🌟 Features

• Hover to Translate: Point your mouse at any word on the screen, and HoverTranslate will use OCR to instantly recognize and translate it.
• Selection Translation: Select any text (sentences, paragraphs), and get an instant translation popup.
• Text-to-Speech (TTS): Hold down the Option (⌥) key to hear the pronunciation of the recognized or selected text.
• Global Hotkey Command: Quickly toggle the translation feature on or off using Command + Option + T (⌘⌥T).
• Native & Lightweight: Built purely with SwiftUI and native macOS APIs, making it fast and energy-efficient.
• Menu Bar Integration: Unobstrusive menu bar app text.bubble.fill icon that stays out of your way until you need it.

📋 Requirements

• macOS 15.0 (Sequoia) or later
• Xcode 16.0+ (For building the project)

🚀 Installation & Build

1. Clone this repository:

   git clone https://github.com/hkJerryLeung/hover-translate.git

2. Open the project folder in Xcode.
   • The project is built using Swift Package Manager (SPM). Look for the Package.swift file.
3. Select your local Mac as the build destination.
4. Press Cmd + R (⌘R) to build and run the application.

⚙️ Permissions

To work its magic, HoverTranslate requires certain system permissions on its first launch:

1. Screen Recording: Required for the OCR (Optical Character Recognition) engine to capture the words under your mouse cursor.
   • System Settings → Privacy & Security → Screen Recording
2. Accessibility: Required to detect and read the text you have highlighted/selected across different applications.
   • System Settings → Privacy & Security → Accessibility

Note: HoverTranslate processes OCR and reads selected text entirely on-device.

📖 Usage

1. Open the app. You will see a chat bubble icon in your macOS menu bar.
2. Ensure the translation engine is active (It will say "翻譯中" in the menu bar menu, or you can toggle it).
3. Translating Single Words: Simply leave your mouse cursor resting over a text element on your screen. A translation tooltip will pop up.
4. Translating Sentences: Highlight any text, and the translation tooltip will appear automatically.
5. Speech/Pronunciation: Hold Option (⌥) while hovering over or selecting text to hear it spoken aloud.
6. Toggle On/Off: Use the global shortcut Command + Option + T (⌘⌥T) to quickly disable the translator when you are gaming or doing focused work.

🛠️ Architecture / Technologies

• SwiftUI: Modern, declarative UI framework for the menu bar and overlay panels.
• Vision Framework / ScreenCaptureKit: Used for real-time Optical Character Recognition (OCR) around the mouse cursor.
• AVFoundation: Powers the Text-to-Speech (TTS) engine.
• Accessibility APIs: To read currently selected text buffer from the active application.

📄 License

This project is open-source. Please refer to the LICENSE file for more details.