Immersive Language Learning Assistant

A browser extension based on the "comprehensible input" theory to help you learn languages naturally while browsing the web.

English | 简体中文

🚀 Quick Install

📥 Official Store Installation (Recommended)

Chrome/Edge Users

📥 Install from Chrome Web Store

Firefox Users

📥 Install from Firefox Add-ons

💡 Recommended: Official store installation is the easiest way - one-click install with automatic updates!

✨ Core Philosophy

We firmly believe that the best way to learn a language is through extensive exposure to "comprehensible input," the famous "i+1" theory. This means content should be slightly above your current level—challenging but not incomprehensible. This extension aims to turn the entire internet into your personalized language learning material by intelligently replacing selected words with their translations in your target language, allowing you to naturally improve your vocabulary and language intuition while immersed in reading.

🎯 Project Highlights: Features a complete pronunciation learning ecosystem with intelligent multi-language translation, including automatic language detection, phonetic notation, AI definitions, dual TTS support, and interactive tooltips for a comprehensive one-stop immersive experience from smart translation to pronunciation learning.

📚 Complete Documentation: See Architecture & Features Guide for technical architecture, API reference, development guide, and troubleshooting.

🚀 Features

🎯 Core Translation Engine

Intelligent Language Detection: AI automatically identifies webpage source language, no need for users to manually specify language type
Intelligent Text Processing: Uses AI large language models to analyze webpage content and intelligently select vocabulary suitable for user proficiency levels
Precise Replacement Control: Precisely control translation ratio (1%-100%) with character-based calculation support
Context Awareness: Considers context and user level to select the most appropriate translation vocabulary
Multi-language Support: Supports 20+ languages intelligent translation (English, Japanese, Korean, French, German, Spanish, Russian, Italian, Portuguese, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Turkish, Greek, etc.) theoretically depends on AI model capabilities
Translation Position Control: Added a feature to customize the position of translated text for more flexible display
Parentheses Display Control: Option to show or hide parentheses around translated text for a cleaner reading experience
Lazy Loading Translation: Translates paragraphs only when scrolled to, reducing resource consumption and improving performance

🔊 Pronunciation Learning Ecosystem ⭐

Interactive Pronunciation Tooltips: Hover over translated words to view phonetics, AI definitions, and pronunciation features with intelligent positioning to avoid boundary overflow
Dual-layer Learning Experience: Phrases display interactive word lists, click individual words for detailed information with nested tooltip support
Multi-TTS Service Support: Integrates Youdao TTS (high quality) and Web Speech API (backup), supports British/American pronunciation switching
Smart Phonetic Retrieval: Automatically retrieves Dictionary API phonetic data with 24-hour TTL caching for optimized performance
AI Definition Explanations: Real-time AI-generated Chinese definitions for more accurate understanding with contextual analysis support
Progressive Loading: Display basic information first, then asynchronously load detailed content to optimize user experience
Audio Caching: Memory-level TTS audio caching, no need to regenerate audio for the same word
Shortcut Key Support: Added shortcut key settings for the pronunciation pop-up to improve operational efficiency

🎨 Rich Visual Experience

7 Translation Styles: Default, subtle, bold, italic, underlined, highlighted, learning mode (blur effect)
Learning Mode: Translation words initially displayed blurred, clarified on hover to enhance memory effect
Glow Animation: Gentle hint effects when new translated words appear, non-intrusive to reading experience
Responsive Design: Auto-adapts to dark/light themes with intelligent tooltip positioning
Floating Tool Ball: Added a configurable floating tool ball for quick access to frequently used functions
Appearance Settings: Support customizing floating ball transparency, position, and other appearance parameters

⚙️ Highly Configurable

Smart Translation Mode: Users only need to select target language, AI automatically detects source language and translates
User Level Adaptation: 5 levels from beginner to advanced with AI-intelligent vocabulary difficulty and selection strategy adjustment
Trigger Modes: Supports automatic trigger (process on page load) and manual trigger working modes
Original Text Display Control: Choose to show, hide, or learning mode (blur effect) display of translated original text
Paragraph Length Control: Customize maximum text length for AI single processing
Pronunciation Feature Toggle: Independent control of pronunciation tooltip functionality activation status
Multiple API Configurations: Supports configuring multiple API services, allowing for flexible switching between different translation providers
Data Import/Export: Added functionality to import and export configuration data for easy backup and migration
Interface Language: Support 5 interface languages (Chinese, English, Japanese, Korean, Spanish)

🔌 Open API Integration

OpenAI API Compatible: Supports any AI service compatible with OpenAI format (ChatGPT, Claude, domestic large models like Doubao, etc.)
Google Gemini Support: Added Google Gemini API integration, providing more AI service options
Flexible Configuration: Customize API Key, Endpoint, model name, Temperature parameters
Smart Prompts: Dynamically generate optimal prompts based on translation direction and user level
Error Handling: Comprehensive API error handling and retry mechanisms
Multiple API Support: Supports configuring and flexibly switching between multiple API services for more reliable service
Thinking Mode: Support AI thinking process output to improve translation quality

🖱️ Enhanced Interactive Features

Context Menu: Added browser context menu functionality for quick access to translation-related operations
Floating Ball Feature: Configurable floating tool ball providing quick translation and settings access
Hotkey Management: Comprehensive hotkey settings and management functionality
Website Management: Blacklist and whitelist functionality for precise control of translation behavior

🚀 Performance & Optimization

Smart Caching: Multi-level caching strategy for translation results, phonetic data, and TTS audio
Incremental Processing: Only processes new content, avoiding duplicate translations
DOM Safety: Uses Range API to ensure DOM structure integrity
Memory Management: Timely cleanup of listeners and optimized memory usage
Lazy Loading Optimization: On-demand translation when scrolling, reducing initial loading time

💻 Modern Technical Architecture

Framework: WXT - A modern WebExtension development framework
Frontend: Vue 3 + TypeScript + Vite
UI Library: Tailwind CSS + Lucide Icons + Reka UI
Tooling: ESLint + Prettier + TypeScript compilation
API Integration: OpenAI-compatible interfaces + Google Gemini + Dictionary API + Youdao TTS
Cross-browser Compatibility: Supports Chrome, Edge, Firefox, with partial support for Safari
Internationalization: Vue I18n support for multi-language interfaces

🌐 Browser Compatibility

This extension is built with Web Extension API and WXT, supporting the following browsers:

Browser	Support Status	Notes
Chrome	✅ Fully Supported	Recommended environment, all features available
Edge	✅ Fully Supported	Chromium-based, full compatibility
Firefox	✅ Supported	Requires addon ID configuration, see Firefox Installation Guide
Safari	⚠️ Partially Supported	Requires additional configuration

⚡ Performance Features

🚀 Smart Caching System

Translation Results: Smart caching based on content and settings, avoiding duplicate API calls
Phonetic Data: 24-hour TTL local caching for improved response speed
TTS Audio: Memory-level caching, no need to regenerate audio for the same word

🔄 Incremental Processing Mechanism

DOM Monitoring: Only processes new content, avoiding duplicate translations
Debounce Optimization: Smart delayed processing for dynamic content changes
Range API: Precise DOM operations maintaining page structure integrity
Lazy Loading: On-demand translation when scrolling, optimizing performance

📸 Feature Showcase

🎬 Dynamic Demo

Complete demonstration of immersive language learning assistant

🎯 Complete Demo: One-stop immersive experience from smart translation to pronunciation learning

🎨 Theme Adaptation

🌗 Theme Adaptation: Smart dark/light theme switching with modern visual experience

👍 Settings page supports multiple configurations

🌍 Multi-language Learning Scenarios

🧠 Smart Multi-language: AI automatic detection and translation for 20+ languages, covering mainstream learning languages including Chinese, English, Japanese, Korean, etc.

🛠️ Developer Installation

🔧 Build from Source (For Developers)

If you want to participate in development or need to build from source:

1. Prerequisites

Node.js (version 18 or higher)
npm or other package managers

2. Installation

Clone the repository:

git clone https://github.com/xiao-zaiyi/illa-helper.git
cd illa-helper

Install dependencies:
```
npm install
```

Tip: If you just want to use this extension without participating in development, please go directly to the Releases page to download the latest packaged version.

3. Configuration

The project manages local development environment configuration through .env files.

Create .env file: Copy the .env.example file to create your own local configuration file.
```
cp .env.example .env
```

Edit configuration: Open the newly created .env file. At minimum, you need to provide a valid API Key for the translation function to work properly.

VITE_WXT_DEFAULT_API_KEY="sk-your-real-api-key"
# You can also override other default settings here
VITE_WXT_DEFAULT_API_ENDPOINT="https://xxxxx/api/v1/chat/completions"
VITE_WXT_DEFAULT_MODEL="gpt-4"
VITE_WXT_DEFAULT_TEMPERATURE="0.2"

Note: The .env file has been added to .gitignore, so your keys won't be accidentally committed.

4. Build Extension

Execute the appropriate build commands based on your target browser:

Chrome/Edge Build

npm run build
npm run zip

Firefox Build

npm run build:firefox
npm run zip:firefox

5. Load Extension

Chrome/Edge Installation

Open your browser (Chrome, Edge, etc.)
Go to the extension management page (chrome://extensions or edge://extensions)
Turn on "Developer mode"
Click "Load unpacked"
Select the .output/chrome-mv3 folder in the project root directory
Done! You should now see the extension icon in your browser toolbar

Firefox Installation Guide

Firefox requires special installation steps due to security restrictions:

The official release version currently cannot be installed through this method, only through the store.

Method 1: Temporary Installation (Recommended for Development)

Enter about:debugging#/runtime/this-firefox in Firefox address bar
Click "Load Temporary Add-on..."
Select the .output/firefox-mv2/manifest.json file
Extension will be loaded temporarily and needs to be reloaded after browser restart

Method 2: Modify Security Configuration (Permanent Installation)

Enter about:config in Firefox address bar
Search for xpinstall.signatures.required
Double-click to change the value to false
Now you can install unsigned extensions through about:addons

Firefox Storage API Configuration

The storage API in Firefox requires an explicit addon ID to work properly. This project has configured Firefox-specific settings in wxt.config.ts:

browser_specific_settings: {
  gecko: {
    id: 'illa-helper@1932794922@qq.com',
    strict_min_version: '88.0'
  }
}

This ensures proper storage functionality for saving user settings in Firefox.

🔧 Core Tech Stack

Framework: WXT - A modern WebExtension development framework
Frontend: Vue 3 + TypeScript + Vite
UI Library: Tailwind CSS + Lucide Icons + Reka UI
Tooling: ESLint + Prettier + TypeScript compilation
API Integration: OpenAI-compatible interfaces + Google Gemini + Dictionary API + Youdao TTS
Architectural Patterns: Provider pattern + Modular design + Event-driven
Pronunciation System: Factory Pattern + Multi-TTS services + Smart Caching
Storage Management: Configuration versioning + Cross-browser compatibility
Internationalization: Vue I18n support for multi-language interfaces

📖 See Detailed Documentation: Architecture & Features Guide - Contains the complete technical architecture, API reference, and development guidelines.

❓ FAQ

Why do I need to provide an API key?

This extension uses AI technology for intelligent text translation, which requires an API service. You can use OpenAI's API key or any third-party service that's compatible with OpenAI's API format, including the newly supported Google Gemini API.

How does the pronunciation feature work?

Our pronunciation system is a core feature providing a complete learning experience:

Phonetic Display: Automatically retrieves Dictionary API phonetic data
AI Definitions: Real-time AI-generated Chinese definition explanations
Dual TTS Support: Youdao TTS (high quality) + Web Speech API (backup)
Interactive Tooltips: Hover to view, supports British/American pronunciation switching
Phrase Learning: Each word in phrases can be independently viewed and pronounced

How to use Smart Multi-language Mode?

Smart multi-language mode is our new feature, easy to use:

Select Translation Mode: Choose "🧠 Smart Multi-language Mode" in settings
Select Target Language: Choose your learning language from 20+ supported languages
Start Browsing: AI automatically detects webpage language and translates to your target language
No Additional Configuration: System automatically handles different language webpage content

Will the extension collect my browsing data?

No. This extension processes all webpage content locally and only sends text fragments that need translation to your configured API service. Pronunciation function's phonetic and definition data are also cached locally to protect your privacy.

Can I control the translation ratio?

Yes. The extension provides precise translation control:

Language Level: 5 levels from beginner to advanced with AI-adjusted vocabulary difficulty
Replacement Ratio: 1%-100% precise control with character-based calculation support
Original Text Display: Choose to show, hide, or learning mode (blur effects)
Smart Adaptation: In smart mode, system automatically optimizes translation strategy based on detected language

How to install on Safari?

Safari requires additional steps to package Web Extensions as Safari extensions. Please refer to Apple's developer documentation.

Firefox Issues Resolution 🚨

According to Add-on signing in Firefox, only Extended Support Release (ESR), Developer Edition, and Nightly versions will read the xpinstall.signatures.required setting when set to false; regular versions can only use temporary installation even if set to false.

"Failed to get user settings: Error: The storage API will not work with a temporary addon ID"

This is a known limitation in Firefox. Solutions:

Use Latest Version: Ensure you're using the latest build version with Firefox-specific configuration
Use Firefox-specific Build: Run npm run build:firefox && npm run zip:firefox
Temporary Installation: Install through about:debugging page instead of directly installing .xpi file

"This component cannot be installed because it has not been verified"

Method 1: Enter about:debugging#/runtime/this-firefox in address bar, select Load Temporary Add-on... to install Firefox extension from file
Method 2: Enter about:config in address bar, search for xpinstall.signatures.required, double-click to change to false

API-related Issues

"API Configuration Error" Notification

Check the following configurations:

API Key format correct (usually starts with sk-)
API Endpoint URL validity
Model name support
Network connection status

Poor Translation Quality

You can try:

Adjusting user level settings
Modifying translation ratio
Switching to more powerful AI models
Adjusting the Temperature parameter (a range of 0.1-0.3 is recommended)

🛠️ Troubleshooting

Common Issue Diagnosis

1. Extension fails to load

Check your Node.js version (requires 18+)
Ensure all dependencies are installed: npm install
Check the build logs for any errors

2. Translation feature is not working

Verify that your API configuration is correct
Check your internet connection
Look for errors in the developer console

3. Pronunciation feature is abnormal

Ensure your browser supports the Web Speech API
Check the status of the Youdao TTS service
Verify that the Dictionary API is accessible

4. Settings cannot be saved

Firefox users, confirm you are using the correct installation method
Check the extension's permission settings
Try clearing your browser cache and retrying

5. Content script functionality issues

Check if ContentManager service initializes properly
Look for service loading errors in the console
Verify configuration service and processing service status
Ensure the website is not in the blacklist

6. Floating ball feature issues

Check if floating ball is enabled in settings
Confirm floating ball position settings are correct
Check for conflicts with other extensions

7. Context menu not displaying

Confirm context menu feature is enabled
Check if website is in blacklist
Verify extension permission settings

🤝 Contribution Guide

We warmly welcome contributions of all kinds! Whether it's submitting a bug, proposing a new feature, or contributing code directly.

How to Contribute

Submit Issues
- Use GitHub Issues to report bugs or suggest features
- Clearly describe the issue or suggestion in detail
- If it's a bug, please provide steps to reproduce and environment information
Contribute Code
- Fork this repository
- Create a new branch (git checkout -b feature/your-amazing-feature)
- Write and test your code
- Ensure your code follows the project's coding standards
- Commit your changes (git commit -m 'Add some amazing feature')
- Push your branch to the remote repository (git push origin feature/your-amazing-feature)
- Create a Pull Request
Improve Documentation
- Documentation improvements are just as important to the project
- You can fix typos, improve explanations, or add examples

Development Guide

Architectural Principles: Follow service-oriented architecture and modular design, especially the Factory Pattern for the pronunciation system
Coding Standards: TypeScript strict mode, ESLint + Prettier formatting, complete type definitions
Testing Requirements: Ensure new features work correctly on multiple browsers and websites, especially in multi-language environments
Performance Considerations: Pay attention to DOM manipulation efficiency, memory management, and multi-language caching strategies
API Compatibility: Maintain backward compatibility with existing API interfaces and support configuration version migration
Multi-language Support: When adding a new language, register it in languageManager.ts and test the translation effect
Pronunciation Feature: When extending TTS services, implement the ITTSProvider interface and register it in the factory
Browser Compatibility: New features need to be tested in Chrome, Edge, and Firefox
New Feature Development: When adding new features, consider internationalization support and user configuration management

📖 Detailed Development Guide: Check out the Architecture & Features Guide for complete development environment setup, code structure explanations, and best practices.

🔗 Related Links

Project Homepage: GitHub Repository
Issue Tracker: GitHub Issues
Releases: GitHub Releases
Technical Documentation: Architecture & Features Guide
WXT Framework: WXT.dev

📧 Contact Us

Author: Xiao-zaiyi
GitHub: @xiao-zaiyi
Project Discussion: Technical discussions through GitHub Issues

📜 License

This project is open-sourced under the MIT License. You are free to use, modify, and distribute this code, including for commercial purposes.

🌟 Star History

⭐ If this project helps you, please give us a Star!

🔄 Welcome to Fork and contribute your improvements!