VocabMeld - 沉浸式语言学习 Chrome 插件

智能替换网页词汇，创造沉浸式双语学习环境，在日常浏览中自然习得语言。
_{基于「可理解性输入」理论，让语言学习融入日常生活}

核心设计理念

VocabMeld 基于语言学家 Stephen Krashen 的「可理解性输入 (Comprehensible Input)」理论设计：

语言习得发生在我们理解比当前水平稍高一点的输入时 (i+1)

核心逻辑：在用户浏览母语内容时，将部分词汇智能替换为学习语言，反之亦然。这种方式：

保持内容可理解性（大部分词汇保持原文）
在上下文中接触新词汇（自然语境记忆）
控制语言接触压力（细水长流，避免认知负荷）

项目灵感与致敬

VocabMeld 从以下优秀项目中汲取灵感，并在多个维度上进行了显著改进：

参考项目对比

项目	核心优势	主要局限性
Ries	综合效果优秀，单词难度划分合理	闭源架构、无法使用自定义大模型 API
illa-helper	类似 Ries 开源版本	翻译质量一般、经常误译短语、难度划分不准、不支持标记已学单词
qiayi	较早出现的沉浸式局部翻译插件	长期未维护、无 AI 能力、整体效果一般

核心改进点

多 LLM 支持：支持 OpenAI、DeepSeek、Moonshot 等主流 AI 服务，一次配置即可使用
智能缓存策略：可配置容量（500-10000词）的 LRU 缓存，显著提升响应速度
精确难度控制：基于 CEFR 标准的六级难度体系，本地过滤确保准确性
现代化架构：持续维护，采用最新技术栈，提供更好的用户体验

安装方法

1. 加载扩展

打开 Chrome 浏览器，访问 chrome://extensions/
开启右上角的"开发者模式"
点击"加载已解压的扩展程序"
选择 VocabMeld 文件夹

2. 配置 API

点击扩展图标，进入设置页面
选择预设服务（推荐 DeepSeek）或自定义配置
填入 API 密钥
点击"测试连接"确认配置正确

完整功能清单

1. AI 智能翻译引擎

1.1 LLM 集成

OpenAI 兼容 API：支持任何 OpenAI 格式的 API（OpenAI、DeepSeek、Moonshot、Groq、Ollama 等）
自定义配置：用户可配置 API 端点、密钥、模型名称
连接测试：提供一键测试 API 连通性功能

1.2 智能词汇选择

LLM 根据以下规则选择替换词汇：

避免替换：专有名词、数字、代码、URL
优先选择：常用词汇、有学习价值的词汇
难度评估：为每个词汇标注 CEFR 等级（A1-C2）
动态数量：根据用户设置的单词量（低/中/高）动态调整翻译数量

1.3 双向翻译

母语页面：将母语词汇替换为学习语言（如中文 → English）
学习语言页面：将学习语言词汇替换为母语（如 English → 中文）
自动检测：根据页面主要语言自动决定翻译方向

2. CEFR 六级难度系统

等级	描述	词汇特征
A1	入门级	最基础的日常词汇，如 hello, thank you
A2	初级	简单日常交流词汇，如 weather, family
B1	中级	一般性话题词汇，如 opinion, experience
B2	中高级	抽象概念词汇，如 consequence, implement
C1	高级	专业/学术词汇，如 ubiquitous, paradigm
C2	精通级	罕见/文学词汇，如 ephemeral, quintessential

难度过滤逻辑：用户选择 B2 时，系统显示 B2、C1、C2 难度的词汇（即该等级及以上），避免过于简单的词汇干扰。

3. 替换强度控制

三档强度设置：

强度	每段最大替换数	使用场景
较少	4 词	轻度学习，保持阅读流畅
适中	8 词	日常学习，平衡阅读与学习
较多	14 词	强化学习，最大化词汇接触

4. 热词缓存系统

4.1 缓存机制

容量：可配置 500/1000/2000/5000/10000 个词汇（默认 2000）
存储格式：原文:源语言:目标语言 作为键
持久化：使用 chrome.storage.local 存储，跨会话保留
LRU 淘汰：达到上限时淘汰最早加入的词汇

4.2 缓存命中逻辑

发送 API 请求前，检查文本中是否有已缓存词汇
已缓存词汇直接使用缓存结果，不发送给 API
只将未缓存的词汇发送给 LLM 处理
新词汇处理完成后加入缓存

4.3 缓存统计与管理

缓存词汇数量（可配置上限）
命中率百分比
搜索功能：支持按单词或翻译搜索
难度筛选：按 CEFR 等级（A1-C2）筛选
难度显示：每个单词显示难度标签
可在设置页面查看和清空
智能缓存策略：优先使用缓存结果，大幅提升响应速度

4.4 优化后的翻译流程

先展示缓存：缓存结果立即显示，无需等待 API
异步处理：未缓存词汇后台异步处理，不阻塞页面
避免重复：已替换的词汇不会被重复替换
智能限制：如果缓存已满足配置，异步替换最多1个词

5. 已学会词汇（白名单）

5.1 功能说明

用户可将已掌握的词汇加入白名单，这些词汇：

不再被替换：浏览时保持原文显示
不发送给 API：从请求文本中预先移除
持久存储：使用 chrome.storage.sync 同步
难度记录：保存词汇的难度信息，便于管理

5.2 添加方式

页面交互：右键点击已翻译的词汇，直接标记为"已学会"
自动恢复：标记后词汇立即恢复为原文显示

5.3 已学会词汇管理

搜索功能：支持按单词或翻译搜索
难度筛选：按 CEFR 等级（A1-C2）筛选
难度显示：每个单词显示难度标签
删除功能：支持单个删除已学会的词汇

6. 需记忆词汇列表

6.1 功能说明

用户可将页面上未翻译的生词加入"需记忆"列表，便于后续复习。

6.2 添加方式

划选/双击：选中页面上的未翻译词汇
弹出提示：显示"添加到需记忆"按钮
点击添加：词汇被存入记忆列表
自动翻译：添加到记忆列表后，立即触发翻译并更新页面，走LRU缓存流程

6.3 记忆列表管理

搜索功能：支持按单词或翻译搜索
难度筛选：按 CEFR 等级（A1-C2）筛选
难度显示：每个单词显示难度标签
清空功能：一键清空记忆列表

7. 页面内容处理

7.1 文本过滤规则

跳过明显的代码文本（变量声明、命令行等）
跳过特定 HTML 标签（script, style, code, pre 等）
跳过隐藏元素和可编辑元素

7.2 视口优先处理

优先处理视口内及附近 300px 范围的内容
滚动时按需处理新进入视口的内容

7.3 内容指纹去重

为每段文本生成指纹（取内容前100字符的哈希）
已处理的指纹存入 Set，避免重复处理
页面重新处理时清空指纹缓存

8. 用户交互

8.1 替换词汇样式

支持三种显示样式（可在设置中选择）：

样式	显示格式	说明
译文(原文)	`translated(original)`	默认样式
仅译文	`translated`	只显示译文，悬停查看原文
原文(译文)	`original(translated)`	原文在前，译文在后

所有样式都支持：

翻译词带紫色下划线标记
原文以灰色显示（在括号中或通过悬停查看）

8.2 悬停提示框

鼠标悬停在替换词汇上时显示：

音标（永远展示学习语言的发音）
难度等级徽章（如 B2）
提示文字："左键点击发音 · 右键标记已学会"

8.3 点击交互

左键点击：播放发音
右键点击：标记为已学会

9. 快捷键支持

9.1 快捷键

Alt+T：快速处理当前页面
在任何网页上都可以使用，无需打开扩展

10. 学习统计

10.1 统计项目

指标	说明	统计规则
累计接触	总共接触的新词汇数	只计算未命中缓存的词汇
今日接触	当天接触的新词汇数	每日 0 点重置
已学会	白名单中的词汇数	用户手动标记
需记忆	需记忆列表中的词汇数	用户手动添加
已缓存	热词缓存中的词汇数	自动管理
命中率	缓存命中百分比	hits / (hits + misses)

11. 设置项

11.1 API 配置

API 端点 URL
API 密钥（安全存储）
模型名称
预设快捷选择（OpenAI/DeepSeek/Moonshot/Groq/Ollama）

11.2 学习偏好

母语语言（zh-CN, zh-TW, en, ja, ko）
学习语言（en, zh-CN, zh-TW, ja, ko, fr, de, es）
难度等级（A1-C2）
替换强度（较少/适中/较多）

11.3 行为设置

界面主题：支持深色/浅色两种主题切换（popup 可快速切换）
自动处理：开启后自动处理新页面（默认开启）
音标显示：开关控制是否显示音标
缓存上限：可选 500/1000/2000/5000/10000 词
翻译显示样式：三种样式可选
- 译文(原文) - 默认样式
- 仅译文 - 只显示译文，悬停查看原文
- 原文(译文) - 原文在前，译文在后
自动保存：所有设置修改后自动保存，无需手动操作

11.4 词汇管理

已学会词汇：查看、搜索、筛选、删除已学会的词汇
需记忆词汇：查看、搜索、筛选需记忆的词汇
已缓存词汇：查看、搜索、筛选已缓存的词汇
所有列表都支持：
- 搜索功能（按单词或翻译）
- 难度筛选（A1-C2）
- 难度标签显示
- 清空功能

11.5 站点规则

所有网站模式（默认）：在所有网站运行，可设置排除列表
仅指定网站模式：只在指定的网站上运行
支持部分匹配（如 "github" 匹配所有包含 github 的域名）
可在 popup 中快速添加/移除当前站点

支持的 API 服务

服务商	端点	推荐模型
OpenAI	`https://api.openai.com/v1/chat/completions`	gpt-4o-mini
DeepSeek	`https://api.deepseek.com/chat/completions`	deepseek-chat
Moonshot	`https://api.moonshot.cn/v1/chat/completions`	moonshot-v1-8k
Groq	`https://api.groq.com/openai/v1/chat/completions`	llama-3.1-8b-instant
Ollama	`http://localhost:11434/v1/chat/completions`	qwen2.5:7b

项目结构

VocabMeld/
├── _locales/               # 国际化文件
│   ├── en/
│   │   └── messages.json
│   └── zh_CN/
│       └── messages.json
├── css/                    # 样式文件
│   ├── content.css         # 注入页面的样式
│   ├── options.css         # 设置页面样式
│   └── popup.css           # 弹出窗口样式
├── icons/                  # 图标文件
│   └── icon.svg
├── js/                     # JavaScript 文件
│   ├── background.js       # 后台脚本
│   ├── content.js          # 内容脚本 (核心逻辑)
│   ├── options.js          # 设置页面脚本
│   ├── popup.js            # 弹出窗口脚本
│   ├── core/               # 核心模块
│   │   ├── config.js       # 配置管理
│   │   └── storage.js      # 存储服务
│   └── services/           # 服务模块
│       ├── cache-service.js # 缓存服务
│       ├── content-segmenter.js # 内容分段
│       └── text-replacer.js # 文本替换
├── manifest.json           # Chrome 扩展配置
├── options.html            # 设置页面
├── popup.html              # 弹出窗口
├── package.json            # 项目配置
├── scripts/                # 构建脚本
│   └── build.js
└── README.md               # 项目说明

核心算法流程

页面处理流程

智能分段与增量处理
- 通过 ContentSegmenter 对页面 DOM 进行遍历，将内容按"语义单元"智能分段
- 仅处理新增或变化的内容，通过 MutationObserver 监听 DOM 变化
- 为每个内容段落生成唯一指纹，防止重复处理
精准且高效的 DOM 替换
- 采用原生 Range API 精确定位和替换文本节点，保持页面结构完整
- 自动排除代码块、脚本、样式、已处理内容等
- 大页面采用懒加载（滚动才按需翻译），动态内容采用防抖优化
智能缓存与状态管理
- LRU 缓存机制：可配置容量（500-10000词），自动淘汰最少使用的词汇
- 并发控制：3个段落同时处理，平衡性能与稳定性
- 状态追踪：防止重复处理，优化用户体验

难度过滤算法

const CEFR_LEVELS = ['A1', 'A2', 'B1', 'B2', 'C1', 'C2'];

function isDifficultyCompatible(wordDifficulty, userDifficulty) {
  const wordIdx = CEFR_LEVELS.indexOf(wordDifficulty);
  const userIdx = CEFR_LEVELS.indexOf(userDifficulty);
  // 只显示大于等于用户选择难度的词汇
  return wordIdx >= userIdx;
}

使用技巧

推荐配置：母语中文 + 学习英语 + B1难度 + 适中强度
快捷键：Alt+T 快速处理当前页面（推荐）
右键标记：遇到已掌握的词汇，右键标记为已学会，下次不再替换
选中添加：遇到想记住的生词，选中后点击"添加到需记忆"
缓存加速：第二次访问同一页面，响应速度显著提升（毫秒级）
智能过滤：自动跳过停用词和已缓存词汇，节省 API 调用
自动保存：设置页面所有修改自动保存，无需手动操作

开发说明

技术栈

Chrome Extension Manifest V3
Vanilla JavaScript (ES6+)
CSS Variables + Modern CSS

本地开发

修改代码后，在 chrome://extensions/ 页面点击刷新按钮
或使用扩展开发工具的热重载功能

隐私政策

VocabMeld 尊重您的隐私。以下是我们的数据处理说明：

数据收集

本地存储：所有用户数据（设置、已学会词汇、需记忆词汇、缓存）均存储在您的浏览器本地，使用 Chrome 的 storage API
不收集个人信息：我们不收集、不存储、不传输任何个人身份信息

数据传输

API 请求：仅在翻译功能使用时，将网页文本片段发送到您配置的 AI 服务（如 OpenAI、DeepSeek 等）
您控制 API：所有 API 配置由您自行提供，我们不提供也不访问任何 API 密钥
无第三方追踪：插件不包含任何分析、追踪或广告代码

权限说明

storage：用于保存您的设置和学习数据
activeTab：用于获取当前标签页信息
scripting：用于在网页中注入翻译功能
contextMenus：用于提供右键菜单功能
tts：用于单词发音功能
host_permissions (all_urls)：用于在所有网站上提供翻译服务

数据安全

所有数据存储在本地，不会上传到任何服务器
API 密钥使用 Chrome 安全存储机制保存
您可以随时在设置页面导出、删除所有数据

打赏

万水千山总是情，一块几块都是情。本软件完全开源，用爱发电，如果你愿意，可以以打赏的方式支持我一下：

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
_locales		_locales
assets		assets
css		css
icons		icons
js		js
scripts		scripts
README.md		README.md
manifest.json		manifest.json
options.html		options.html
package.json		package.json
popup.html		popup.html

Folders and files

Latest commit

History

Repository files navigation

VocabMeld - 沉浸式语言学习 Chrome 插件

核心设计理念

项目灵感与致敬

参考项目对比

核心改进点

安装方法

1. 加载扩展

2. 配置 API

完整功能清单

1. AI 智能翻译引擎

1.1 LLM 集成

1.2 智能词汇选择

1.3 双向翻译

2. CEFR 六级难度系统

3. 替换强度控制

4. 热词缓存系统

4.1 缓存机制

4.2 缓存命中逻辑

4.3 缓存统计与管理

4.4 优化后的翻译流程

5. 已学会词汇（白名单）

5.1 功能说明

5.2 添加方式

5.3 已学会词汇管理

6. 需记忆词汇列表

6.1 功能说明

6.2 添加方式

6.3 记忆列表管理

7. 页面内容处理

7.1 文本过滤规则

7.2 视口优先处理

7.3 内容指纹去重

8. 用户交互

8.1 替换词汇样式

8.2 悬停提示框

8.3 点击交互

9. 快捷键支持

9.1 快捷键

10. 学习统计

10.1 统计项目

11. 设置项

11.1 API 配置

11.2 学习偏好

11.3 行为设置

11.4 词汇管理

11.5 站点规则

支持的 API 服务

项目结构

核心算法流程

页面处理流程

难度过滤算法

使用技巧

开发说明

技术栈

本地开发

隐私政策

数据收集

数据传输

权限说明

数据安全

打赏

Star History

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages