项目时间：K7-Translate 最早提交于 2026 年 10 月 28 日。本文基于 2026 年 10 月 31 日的仓库代码，介绍它解决的问题、使用方式和当前边界。
阅读英文技术文档时，有时只需要理解选中的一句话，有时则需要在原文和译文之间持续对照。K7-Translate 是我为此开发的浏览器扩展，面向 Microsoft Edge 和 Google Chrome，支持选中文本自动翻译，也能将网页正文切换为原文、双语或译文视图。
项目默认使用 Index-Translate-2B，通过 llama.cpp 在本机运行。按默认方式部署时，网页文本不需要发送到第三方在线翻译服务，翻译请求可以在自己的电脑上完成。
它具体能做什么
K7-Translate 目前提供两种翻译方式。
选文翻译，在普通网页中选中一段文本后，扩展会显示翻译浮层。浮层支持切换目标语言、复制译文和失败重试。输入框与可编辑区域不会自动触发，避免影响正常输入。
选文翻译适合局部理解，比如确认一个术语、一段错误信息或文档中的某句话。当前支持 2 至 4000 个字符，目标语言包括简体中文、繁体中文、英语、日语、韩语、法语、德语、西班牙语和俄语。
整页正文翻译，点击浏览器工具栏中的 K7 图标后，扩展会优先从页面的 article 或 main 区域收集正文段落，再逐段请求翻译。译文随任务进度逐步插入，不需要等整页完成后才能阅读。
整页翻译提供三种显示模式：
- 原文：暂时隐藏译文。
- 双语：保留原文，并在段落后显示译文。
- 译文：隐藏已翻译的原文，只显示译文。
点击「恢复原始页面」会取消当前任务并移除译文，让页面回到翻译前的状态。
本地模型如何与浏览器扩展配合
项目由浏览器扩展和本地推理服务两部分组成：
网页中的选文或正文段落 ↓Content Script ↓扩展 Background Service Worker ↓TranslationService ↓IndexTranslateProvider ↓本机 llama.cpp 服务 ↓Index-Translate-2B GGUF 模型Content Script 负责识别选中文本、展示浮层和处理页面段落。Background Service Worker 负责发送翻译请求、取消任务和返回结果。模型适配层负责生成提示词，并通过 OpenAI 兼容接口调用 llama.cpp。
项目默认使用 Index-Translate-2B 的 Q4_K_M GGUF 模型。首次启动需要下载模型，后续可以复用本地缓存。原生服务监听 127.0.0.1，Docker 容器端口也只映射到宿主机的 127.0.0.1。
安装与使用
使用项目需要完成两部分部署。
先启动模型服务。macOS 可以运行：
./scripts/setup-macos.sh --port 8000这个脚本会安装固定版本的 llama.cpp、下载模型并启动服务，优先使用 Metal。macOS 或 Linux 也可以选择 Docker CPU 方式：
K7_TRANS_PORT=8000 docker compose up --build -d然后构建并安装扩展：
pnpm installpnpm build在 Edge 的 edge://extensions 或 Chrome 的 chrome://extensions 中开启开发人员模式，选择「加载解压缩的扩展」，加载项目生成的 dist/ 目录。两个浏览器共用同一份 Manifest V3 构建产物。
默认服务地址为 http://127.0.0.1:8000/v1，模型名为 Index-Translate-2B。设置页提供「保存并测试真实翻译」，可以用一次实际请求检查模型地址、端口和配置是否正确。
K7-Translate 目前更适合有一定开发经验的用户，安装和配置还做不到开箱即用。
模型可以替换，页面逻辑不必跟着改
模型调用被收敛在 TranslationProvider 接口之后，选文和整页逻辑只依赖统一的翻译请求与响应。
默认的 IndexTranslateProvider 通过 OpenAI 兼容协议调用服务。只要其他服务也提供兼容接口，就可以在设置页修改 Base URL、模型名称、API Key 和提示词预设，不需要修改页面代码。
如果服务使用其他协议，可以新增 provider，把协议转换放在适配层内部，再在 ProviderFactory 中注册。页面功能不需要理解不同模型的 API 差异，替换模型时也不用重写选文和整页翻译。
TranslationService 还统一处理超时、取消、短期缓存和错误信息。当前缓存最多保留 100 条翻译结果，原文和译文不会写入扩展的持久化存储；扩展设置则保存在浏览器本地。
自定义服务地址会改变数据流向
按默认配置使用本机 llama.cpp 时，文本会发送到本机服务，翻译过程不依赖第三方在线翻译 API。
项目也允许自定义 OpenAI 兼容服务地址。如果改为远程服务，网页文本就会发送到对应服务。「本地模型翻译」描述的是默认部署方式，实际数据流向取决于用户配置的 Base URL。
本地推理的成本也需要考虑。整页翻译按段调用模型，速度会受到硬件、模型大小、段落数量和并发数影响。默认并发为 2，可以调整为 1 至 4；提高并发会增加内存和计算压力，不一定总能缩短整体时间。
当前版本还有哪些限制
K7-Translate 目前版本为 0.1.0，仍处于较早阶段，主要边界包括：
- 整页译文采用纯文本渲染，复杂内联链接和富文本格式还不能完整保留。
- 动态加载的长页面需要在内容出现后重新执行整页翻译。
- 暂不支持流式输出、图片和音频翻译、术语表及浏览器同步。
edge://、chrome://、扩展商店和独立 PDF 查看器等受保护页面无法使用内容脚本。- Windows 一键安装脚本和 Firefox 适配仍在 TODO 中，Edge 与 Chrome 扩展商店也尚未发布。
- 翻译质量由实际使用的模型决定，替换为非翻译专用模型时可能需要调整提示词。
项目代码采用 MPL-2.0，模型权重及其使用条件则遵循 Index-Translate 自身许可，两者需要分别确认。
适合哪些用户
如果主要需求是阅读技术文档、希望在本地完成翻译，并且愿意配置 llama.cpp 和浏览器扩展，K7-Translate 提供了一种相对直接的实现。
如果更关注开箱即用、复杂网页格式还原、移动端使用或无需维护的在线服务，当前版本不太合适。
这个项目目前的形态很简单：在浏览器中保留原文阅读体验，同时让选文和整页正文可以使用本地模型翻译。