Translator-UNI

A powerful Chrome/Edge Manifest V3 extension that reads selected text using multiple TTS engines. Features synchronized sentence-level highlighting, a draggable floating control pill, and offline support via Piper.

Features

• 6 TTS Engines

  • System — Uses your OS built-in voices (no setup required).
  • Edge TTS — Free, high-quality cloud voices (requires Python native host).
  • Piper — 100% offline local TTS. Privacy-first, no internet needed.
  • ElevenLabs — Premium AI voices (requires API key).
  • OpenAI — GPT-powered speech (requires API key).
  • Google/Gemini — AI Studio TTS (requires API key).

• Synchronized Highlighting — Real-time word and sentence highlighting using the CSS Custom Highlights API (Chrome 105+).

• Floating Pill — Glassmorphism control bar that appears on text selection. Draggable, with pause/play, speed control, and voice switching.

• Chunked Playback — Long texts are split into sentence chunks for reliable playback across all engines.

• Dark/Light Theme — Toggle via popup, applied to both popup and floating pill.

• 14 Languages — pt-BR, pt-PT, en-US, en-GB, es, fr, de, it, ja, ko, zh-CN, ru, ar, hi.

• Reader Tracker — Estimated reading time and chunk progress display.

Project Structure

Translator-UNI/
├── manifest.json                  # MV3 configuration
├── package.json                   # Node test runner
├── src/
│   ├── background/
│   │   └── background.js          # Service worker: TTS engines, context menu, chunking
│   ├── content/
│   │   ├── content.js             # Core: mouse coords, pill messages, theme relay
│   │   ├── floating-pill.js       # Draggable floating control pill (IIFE)
│   │   └── tts-highlighter.js     # Word-level highlight sync (CSS Custom Highlights API)
│   ├── popup/
│   │   ├── popup.html             # Popup UI with tabs (Main + Settings)
│   │   ├── popup.css              # Dark/Light theme styles
│   │   └── popup.js               # Popup logic, engine/voice/speed/pitch controls
│   └── offscreen/
│       ├── offscreen.html         # Offscreen document for audio playback
│       └── offscreen.js           # Audio element playback (MP3/WAV from base64)
├── native/
│   ├── nm_host_edge_tts.py        # Python native messaging host
│   ├── install_host.sh            # Installer for Linux + macOS (bash)
│   ├── install_host.ps1           # Installer for Windows (PowerShell)
│   ├── auto_install.sh            # Auto-detects extension ID and installs NM host (Linux)
│   └── com.ai_voice_translator.edge_tts.json  # NM manifest template
├── logos/
│   └── logo.png                   # Extension icon
├── tests/
│   ├── quick.test.js              # Quick validation (12 tests)
│   ├── unit.test.js               # Unit tests
│   ├── integration.test.js        # Integration tests
│   └── e2e.test.js                # End-to-end tests
└── docs/
    ├── README.md                  # Full documentation
    └── PROGRESS.md                # Development progress log

Installation

Prerequisites

• Chrome or Edge (Manifest V3 compatible).
• Python 3.8+ with pip.

1. Clone or Download

git clone https://github.com/vanppsa/Translator-UNI.git
cd Translator-UNI

2. Install Python Dependencies

pip install edge-tts requests

On systems with Python 3.12+, you may need:

pip install edge-tts requests --break-system-packages

3. Clean Python Cache (Critical)

Chrome refuses to load extensions that contain directories starting with _.

rm -rf __pycache__/ native/__pycache__/

You must run this command before every reload in chrome://extensions/.

4. Load the Extension

1. Open Chrome and go to chrome://extensions/.
2. Enable Developer mode (toggle in the top-right corner).
3. Click Load unpacked and select the Translator-UNI folder.
4. Copy the Extension ID from the extension card (32 lowercase characters).

5. Install the Native Messaging Host

This step is required for Edge TTS, Piper, ElevenLabs, OpenAI, and Gemini voices.

Linux / macOS

bash native/install_host.sh

When prompted, paste the Extension ID from step 4 and press Enter.

Windows

Open PowerShell as Administrator and run:

powershell -ExecutionPolicy Bypass -File .\native\install_host.ps1

When prompted, paste the Extension ID from step 4 and press Enter.

Linux (Auto-detect)

Alternatively, run the auto-installer which detects the Extension ID automatically:

bash native/auto_install.sh

6. Restart Chrome

Close and reopen Chrome to activate Native Messaging.

Usage

1. Select any text on a webpage.
2. Right-click and choose "Speak Selection (Translator-UNI)".
3. Use the Floating Pill to pause, resume, change speed, or switch voices.
4. Open the extension popup to switch TTS engines or configure API keys (ElevenLabs, OpenAI, Gemini).

Troubleshooting

Issue	Solution
"Cannot load extension with file or directory name pycache"	Run rm -rf __pycache__/ native/__pycache__/
"Native host has exited"	Ensure edge-tts is installed: pip install edge-tts
Pill does not appear	Refresh the page (F5) after reloading the extension
No audio from premium engines	Check API keys in the Settings tab of the popup

Development

Run tests:

npm test        # Quick validation
npm run test:full   # Full integration suite

License

MIT