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

简体中文 | English

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

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

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

• 智能语言检测: AI自动识别网页源语言，无需用户手动指定语言类型
• 智能文本处理: 使用大语言模型分析网页内容，智能选择适合用户水平的词汇进行翻译
• 精确替换控制: 可精确控制翻译比例（1%-100%），支持字符级精确计算
• 上下文感知: 考虑语境和用户水平，选择最合适的翻译词汇
• 多语言支持: 支持20+种语言的智能翻译（英语、日语、韩语、法语、德语、西班牙语、俄语、意大利语、葡萄牙语、荷兰语、瑞典语、挪威语、丹麦语、芬兰语、波兰语、捷克语、土耳其语、希腊语等）理论上依赖大模型能力。
• 翻译位置控制: 新增翻译文本位置自定义功能，更灵活的显示方式
• 括号显示控制: 可选择是否显示翻译文本的括号，提供更清爽的阅读体验

• 交互式悬浮框: 鼠标悬停翻译词汇即可查看音标、AI词义和朗读功能，智能定位避免边界溢出
• 双层学习体验: 短语显示可交互的单词列表，点击单个单词查看详细信息，支持嵌套悬浮框
• 多TTS服务支持: 集成有道TTS（高质量）和Web Speech API（备用），支持英式/美式发音切换
• 智能音标获取: 自动获取Dictionary API音标数据，24小时TTL缓存优化性能
• AI词义解释: 实时调用AI生成中文词义解释，理解更准确，支持上下文语境分析
• 渐进式加载: 先显示基础信息，再异步加载详细内容，优化用户体验
• 音频缓存: 内存级TTS音频缓存，同一单词无需重复生成语音
• 快捷键支持: 新增发音弹出框快捷键设置，提升操作效率

• 7种翻译样式: 默认、微妙、粗体、斜体、下划线、高亮、学习模式（模糊效果）
• 学习模式: 翻译词汇初始模糊显示，鼠标悬停时清晰化，增强记忆效果
• 辉光动画: 新翻译词汇出现时的柔和提示效果，不干扰阅读体验
• 响应式设计: 自适应深色/浅色主题，智能悬浮框定位
• 悬浮工具球: 新增可配置的悬浮工具球，快速访问常用功能

• 智能翻译模式: 用户只需选择目标语言，AI自动检测源语言并进行翻译
• 用户水平适配: 从初级到精通5个级别，AI智能调整词汇难度和选择策略
• 触发模式: 支持自动触发（页面加载时处理）和手动触发两种工作方式
• 原文显示控制: 可选择显示、隐藏或学习模式（模糊效果）显示被翻译的原文
• 段落长度控制: 自定义AI单次处理的最大文本长度
• 发音功能开关: 可独立控制发音悬浮框功能的启用状态
• 多API配置: 支持配置多个API服务，可灵活切换不同的翻译服务提供商
• 数据导入导出: 新增配置数据的导入导出功能，方便备份和迁移

• 兼容OpenAI API: 支持任何兼容 OpenAI 格式的AI服务（ChatGPT、Claude、豆包等国产大模型）
• 灵活配置: 自定义API Key、Endpoint、模型名称、Temperature参数
• 智能提示词: 根据翻译方向和用户水平动态生成最优提示词
• 错误处理: 完善的API错误处理和重试机制
• 多API支持: 支持配置多个API服务并灵活切换，提供更可靠的服务保障

• 智能缓存: 翻译结果、音标数据、TTS音频多级缓存策略
• 增量处理: 只处理新增内容，避免重复翻译
• DOM安全: 使用Range API确保DOM结构完整性
• 内存管理: 及时清理监听器，优化内存使用

• 框架: WXT - 现代WebExtension开发框架
• 前端: Vue 3 + TypeScript + Vite
• UI库: Tailwind CSS + Lucide Icons
• 构建: ESLint + Prettier + TypeScript编译
• API集成: OpenAI兼容接口 + Dictionary API + 有道TTS
• 跨浏览器兼容: 支持Chrome、Edge、Firefox，部分支持Safari

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

• 翻译结果: 基于内容和设置的智能缓存，避免重复API调用
• 音标数据: 24小时TTL本地缓存，提升响应速度
• TTS音频: 内存级缓存，同一单词无需重复生成语音

• DOM监听: 只处理新增内容，避免重复翻译
• 防抖优化: 动态内容变化时的智能延迟处理
• Range API: 精确DOM操作，保持页面结构完整性

 
 

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

• Node.js（版本 18 或更高）
• npm 或其他包管理器

1. 克隆仓库:

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

2. 安装依赖:

   npm install

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

项目通过 .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 中，所以你的密钥不会被意外提交。

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

npm run build
npm run zip

npm run build:firefox
npm run zip:firefox

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

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/     # 浮动球功能
│   ├── api/              # 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          # 项目依赖配置

• 框架: WXT - 现代WebExtension开发框架
• 前端: Vue 3 + TypeScript + Vite
• UI库: Tailwind CSS + Lucide Icons
• 构建: ESLint + Prettier + TypeScript编译
• API集成: OpenAI兼容接口 + Dictionary API + 有道TTS
• 架构模式: Provider模式 + 模块化设计 + 事件驱动
• 发音系统: 工厂模式 + 多TTS服务 + 智能缓存
• 存储管理: 配置版本控制 + 跨浏览器兼容

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

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

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

• 音标显示: 自动获取Dictionary API音标数据
• AI词义: 实时调用AI获取中文释义解释
• 双TTS支持: 有道TTS（高质量）+ Web Speech API（备用）
• 交互悬浮框: 鼠标悬停查看，支持英美发音切换
• 短语学习: 短语中每个单词都可独立查看和朗读

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

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

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

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

• 语言水平: 5个级别从初级到精通，AI智能调整词汇难度
• 替换比例: 1%-100%精确控制，支持按字符数计算
• 原文显示: 可选择显示、隐藏或学习模式（模糊效果）
• 智能适配: 在智能模式下，系统会根据检测到的语言自动优化翻译策略

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

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

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

• 方法一：通过在地址栏输入 about:debugging#/runtime/this-firefox 选择 临时加载附加组件... 可以从文件安装Firefox扩展
• 方法二：地址栏输入 about:config 搜索 xpinstall.signatures.required 设置项，双击改为 false

检查以下配置：

• API Key格式是否正确（通常以sk-开头）
• API Endpoint URL是否有效
• 模型名称是否支持
• 网络连接是否正常

可以尝试：

• 调整用户水平设置
• 修改翻译比例
• 更换更强大的AI模型
• 调整Temperature参数（建议0.1-0.3）

• 检查Node.js版本（需要18+）
• 确保依赖安装完整：npm install
• 查看构建日志是否有错误

• 验证API配置是否正确
• 检查网络连接
• 查看开发者控制台错误信息

• 确保浏览器支持Web Speech API
• 检查有道TTS服务状态
• 验证Dictionary API可访问性

• Firefox用户确认使用正确的安装方式
• 检查扩展权限设置
• 清除浏览器缓存后重试

我们非常欢迎各种形式的贡献！无论是提交 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. 改进文档

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

• 架构原则: 遵循Provider模式和模块化设计，特别是发音系统的工厂模式
• 代码规范: TypeScript严格模式，ESLint + Prettier格式化，完整类型定义
• 测试要求: 确保新功能在多种浏览器和网站上正常工作，特别是多语言环境
• 性能考虑: 注意DOM操作效率、内存管理和多语言缓存策略
• API兼容: 保持与现有API接口的向后兼容性，支持配置版本迁移
• 多语言支持: 新增语言时需要在languageManager.ts注册并测试翻译效果
• 发音功能: 扩展TTS服务时需要实现ITTSProvider接口并注册到工厂
• 浏览器兼容性: 新功能需要在Chrome、Edge、Firefox中测试

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

• 项目主页: GitHub Repository
• 问题反馈: GitHub Issues
• 版本发布: GitHub Releases
• 技术文档: 架构与功能详解
• WXT框架: WXT.dev

• 作者: Xiao-zaiyi
• GitHub: @xiao-zaiyi
• 项目讨论: 通过GitHub Issues进行技术讨论

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