illa-helper: 提升语言学习体验的浸入式助手

Published:

原文链接

浸入式学语言助手

Version License PRs Welcome Status Built with WXT Firefox Compatible

一款基于”可理解输入”理论的浏览器扩展，帮助你在日常网页浏览中自然地学习语言。

简体中文 | English

✨ 核心理念

我坚信，语言学习的最佳途径是大量接触”可理解的”输入材料，即著名的 “i+1” 理论。这意味着内容应该略高于你当前的水平，既有挑战性，又不至于让你完全看不懂。本扩展旨在将整个互联网变成你的个性化语言学习教材，通过智能地将网页上的部分词语替换为你正在学习的目标语言词汇，让你在沉浸式的阅读中，不知不觉地提升词汇量和语感。

🎯 项目亮点: 集成了完整的发音学习生态系统和智能多语言翻译功能，包括自动语言检测、音标显示、AI词义解释、双TTS语音合成和交互式悬浮框，为用户提供从智能翻译到发音学习的一站式沉浸式体验。

📚 完整文档: 查看 架构与功能详解 了解技术架构、API接口、开发指南和故障排除。

🚀 功能特性

🎯 核心翻译引擎

🔊 发音学习生态系统 ⭐

🎨 丰富的视觉体验

⚙️ 高度可配置性

🔌 开放式API集成

🚀 性能与优化

💻 现代技术架构

🌐 浏览器兼容性

本扩展基于 Web Extension API 和 WXT 构建，支持以下浏览器：

浏览器支持状态特殊说明
Chrome✅ 完全支持推荐环境，所有功能可用
Edge✅ 完全支持基于Chromium，完整兼容
Firefox✅ 支持需配置addon ID，详见Firefox安装指南
Safari⚠️ 部分支持需要额外配置，自行查询

⚡ 性能特性

🚀 智能缓存系统

🔄 增量处理机制

📸 功能展示

🎬 动态演示

浸入式语言学习助手完整演示 浸入式语言学习助手完整演示 浸入式语言学习助手完整演示浸入式语言学习助手完整演示

🎯 完整演示: 从智能翻译到发音学习的一站式沉浸式体验

🎨 主题适配展示

深色主题翻译效果 深色主题变体 浅色主题翻译效果

🌗 主题适配: 深色/浅色主题智能切换，现代化视觉体验

设置 设置

👍 设置页支持多种配置

🌍 多语言学习场景

中文学习场景 英文学习场景
日文学习场景 韩文学习场景

🧠 智能多语言: 支持20+种语言的AI自动检测和翻译，涵盖中文、英语、日语、韩语等主流学习语言

🛠️ 安装与运行

1. 先决条件

2. 安装

  1. 克隆仓库:

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

  2. 安装依赖:

    npm install

提示: 如果你只想使用这个扩展而不参与开发，请直接前往 Releases 页面下载最新版本的打包文件。

3. 配置

项目通过 .env 文件管理本地开发环境的配置。

  1. 创建 .env 文件: 复制 .env.example 文件来创建你自己的本地配置文件。

    cp .env.example .env

  2. 修改配置: 打开新建的 .env 文件，至少你需要提供一个有效的 API Key 才能让翻译功能正常工作。

    VITE_WXT_DEFAULT_API_KEY="sk-your-real-api-key"
# 你也可以在这里覆盖其他的默认设置
VITE_WXT_DEFAULT_API_ENDPOINT="https://xxxxx/api/v1/chat/completions"
VITE_WXT_DEFAULT_MODEL="gpt-4"
VITE_WXT_DEFAULT_TEMPERATURE="0.2"

    注意: .env 文件已被添加到 .gitignore 中，所以你的密钥不会被意外提交。

4. 构建扩展

根据目标浏览器执行相应的构建命令：

Chrome/Edge构建

npm run build
npm run zip

Firefox构建

npm run build:firefox
npm run zip:firefox

5. 加载扩展

Chrome/Edge安装

  1. 打开浏览器（Chrome、Edge等）
  2. 进入扩展管理页面（chrome://extensions 或 edge://extensions）
  3. 打开 “开发者模式”
  4. 点击 “加载已解压的扩展程序”
  5. 选择项目根目录下的 .output/chrome-mv3 文件夹
  6. 完成！现在你应该能在浏览器工具栏看到扩展的图标了

Firefox安装指南

Firefox由于安全限制，需要特殊的安装步骤：

方法一：临时安装（推荐开发调试）

  1. 在Firefox地址栏输入 about:debugging#/runtime/this-firefox
  2. 点击 “临时加载附加组件…”
  3. 选择 .output/firefox-mv2/manifest.json 文件
  4. 扩展将以临时方式加载，浏览器重启后需要重新加载

方法二：修改安全配置（永久安装）

  1. 在Firefox地址栏输入 about:config
  2. 搜索 xpinstall.signatures.required
  3. 双击将值改为 false
  4. 现在可以通过 about:addons 安装未签名的扩展

Firefox Storage API配置说明

Firefox中的storage API需要明确的addon ID才能正常工作。本项目已在 wxt.config.ts 中配置了Firefox特定设置：

browser_specific_settings: {
  gecko: {
    id: 'illa-helper@xiao-zaiyi',
    strict_min_version: '88.0'
  }
}

这确保了在Firefox中可以正常使用存储功能保存用户设置。

📂 目录结构

.
├── .output/              # WXT 打包输出目录
│   ├── chrome-mv3/       # Chrome/Edge扩展文件
│   └── firefox-mv2/      # Firefox扩展文件
├── assets/               # 静态资源目录 (例如 CSS, 字体)
├── components/           # 全局Vue组件
├── docs/                 # 📚 项目文档
│   └── ARCHITECTURE_AND_FEATURES.md  # 详细技术文档
├── entrypoints/          # 扩展入口点
│   ├── background.ts     # 后台服务 (配置验证、通知管理)
│   ├── content.ts        # 内容脚本 (核心翻译逻辑)
│   ├── popup/            # Vue 3 弹窗界面
│   │   ├── App.vue       # 主界面组件
│   │   ├── index.html    # 弹窗页面
│   │   ├── main.ts       # 入口点脚本
│   │   └── style.css     # 弹窗样式
│   └── options/          # 设置页面（Vue 3）
│       ├── App.vue       # 设置主界面
│       ├── index.html    # 设置页面HTML
│       ├── main.ts       # 设置页面入口脚本
│       └── components/   # 设置页面组件 (内容无法获取)
├── images/               # 项目图片资源
├── lib/                  # 第三方库或辅助模块
├── src/modules/          # 核心功能模块 (注意：由于环境限制，此目录下的详细结构未能完全验证)
│   ├── pronunciation/    # 🔊 发音系统模块（完整生态系统）
│   │   ├── phonetic/     # 音标获取服务（Dictionary API）
│   │   ├── tts/          # 语音合成服务（有道TTS + Web Speech）
│   │   ├── translation/  # AI翻译集成（词义解释）
│   │   ├── services/     # 发音服务协调器（核心逻辑）
│   │   ├── ui/           # 悬浮框UI组件（交互界面）
│   │   ├── utils/        # 工具函数库（DOM、定位、计时器）
│   │   ├── config/       # 配置管理（常量、配置项）
│   │   └── types/        # 类型定义（完整类型系统）
│   ├── options/          # 设置管理模块
│   │   └── blacklist/    # 网站黑名单功能
│   ├── processing/       # 文本处理模块
│   ├── floatingBall/     # 浮动球功能
│   ├── apiService.ts     # AI翻译API服务
│   ├── textProcessor.ts  # 智能文本处理器
│   ├── textReplacer.ts   # 文本替换引擎
│   ├── styleManager.ts   # 样式管理器
│   ├── storageManager.ts # 配置存储管理
│   ├── languageManager.ts# 多语言支持
│   ├── promptManager.ts  # AI提示词管理
│   ├── messaging.ts      # 消息传递系统
│   └── types.ts          # 核心类型定义
├── public/               # 静态资源
│   ├── icon/             # 扩展图标 (内容无法获取)
│   ├── warning.png       # 通知图标
│   └── wxt.svg           # WXT 图标
├── .env.example          # 环境变量模板
├── wxt.config.ts         # WXT 框架配置
└── package.json          # 项目依赖配置

🔧 核心技术栈

📖 查看详细文档: 架构与功能详解 - 包含完整的技术架构、API参考和开发指南

❓ 常见问题

为什么我需要提供API密钥？

本扩展使用AI技术进行智能文本翻译，这需要调用API服务。您可以使用 OpenAI 的API密钥，或任何兼容 OpenAI API格式的第三方服务。

发音功能如何工作？

发音系统是我们的核心特色功能，提供完整的学习体验：

智能翻译模式如何使用？

智能翻译是我们的新功能，使用简单：

  1. 选择翻译模式: 在设置中选择”🧠 智能多语言模式”
  2. 选择目标语言: 从20+种支持语言中选择你想学习的语言
  3. 开始浏览: AI会自动检测网页语言并翻译到你的目标语言
  4. 无需额外配置: 系统会自动处理不同语言的网页内容

扩展会收集我的浏览数据吗？

不会。本扩展在本地处理所有网页内容，只将需要翻译的文本片段发送到配置的API服务。发音功能的音标和词义数据也会本地缓存，保护您的隐私。

我可以控制翻译比例吗？

可以。扩展提供了精确的翻译控制：

Safari浏览器如何安装？

Safari需要额外的步骤将Web扩展打包为Safari扩展。请参考Apple开发者文档。

Firefox相关问题解决 🚨

“获取用户设置失败: Error: The storage API will not work with a temporary addon ID”

这是Firefox的已知限制。解决方案：

  1. 使用最新版本: 确保使用最新的构建版本，已包含Firefox特定配置
  2. 使用Firefox专用构建: 运行 npm run build:firefox && npm run zip:firefox
  3. 临时安装: 通过 about:debugging 页面安装，而不是直接安装.xpi文件

”扩展此组件无法安装，因为它未通过验证”

API相关问题

“API配置错误”通知

检查以下配置：

翻译质量不理想

可以尝试：

🛠️ 故障排除

常见问题诊断

1. 扩展加载失败

2. 翻译功能不工作

3. 发音功能异常

4. 设置无法保存

🤝 贡献指南

我们非常欢迎各种形式的贡献！无论是提交 Bug、提出新功能建议，还是直接贡献代码。

如何贡献

  1. 提交问题

    • 使用 GitHub Issues 报告 bug 或提出功能建议
    • 清晰描述问题或建议的详细内容
    • 如果是 bug，请提供复现步骤和环境信息

  2. 贡献代码

    • Fork 本仓库
    • 创建一个新的分支 (git checkout -b feature/your-amazing-feature)
    • 编写并测试您的代码
    • 确保代码遵循项目的编码规范
    • 提交您的代码更改 (git commit -m 'Add some amazing feature')
    • 将您的分支推送到远程仓库 (git push origin feature/your-amazing-feature)
    • 创建一个 Pull Request

  3. 改进文档

    • 文档改进对项目同样重要
    • 可以修正错别字、完善解释或添加示例

开发指南

📖 详细开发指南: 查看 架构与功能详解 获取完整的开发环境配置、代码结构说明和最佳实践。

🔗 相关链接

📧 联系我们

📜 版权许可

本项目基于 MIT License 开源。您可以自由使用、修改和分发此代码，包括用于商业目的。

⭐ 如果这个项目对您有帮助，请给我们一个Star！

🔄 欢迎Fork并贡献您的改进！

Previous Post
MyRingtone：免费高质量铃声下载，轻松更换手机铃声
Next Post
ProseKit: 跨框架的无头富文本编辑器