112 lines
5.4 KiB
Markdown
112 lines
5.4 KiB
Markdown
# 译泡 · PopLingo
|
||
|
||
> AI 划词翻译 · Chrome 扩展 —— 划词即译，大模型随身翻译气泡。
|
||
|
||
接入大模型（LLM）的浏览器划词翻译插件。选中网页文本 → 点击浮出的「译」按钮（或按 `Alt+T` / 右键菜单）→ 流式显示译文。
|
||
|
||
## ✨ 功能
|
||
|
||
- **划词翻译**：选中文本后显示图标，点击翻译；也支持划词自动翻译、仅快捷键两种触发模式
|
||
- **多服务商接入**：
|
||
- **OpenAI 兼容协议**：DeepSeek、OpenAI、月之暗面 Kimi、智谱 GLM、通义千问、硅基流动、Ollama（本地）、任意自定义兼容接口
|
||
- **Google Gemini**（原生协议）
|
||
- **Anthropic Claude**（原生协议）
|
||
- **流式输出**：逐字显示译文，跟 ChatGPT 一样的打字机效果
|
||
- **左右分栏对照**：左原文、右译文，带「原文 / 译文」栏目标签与竖向分隔线，字号更大更易读
|
||
- **精致弹窗**：拖拽移动、右下角调整大小、一键复制、重新翻译、「原文」按钮一键展开/收起（收起后译文独占全宽）、`Esc` 关闭、自动适配暗色模式
|
||
- **快捷入口**：`Alt+T` 快捷键、右键菜单「AI 翻译」、工具栏 Popup 快捷开关
|
||
- **可定制**：目标/源语言、译文字号、Temperature、自定义 Prompt（支持 `{targetLang}` `{sourceLang}` 变量）
|
||
- **隐私安全**：API 请求由扩展后台直接发给你配置的服务商，不经过任何第三方中转
|
||
|
||
## 📦 安装（开发者模式）
|
||
|
||
1. 打开 Chrome，访问 `chrome://extensions/`
|
||
2. 右上角打开 **开发者模式**
|
||
3. 点击 **加载已解压的扩展程序**，选择本目录（`fanyi/`）
|
||
4. 点击工具栏拼图图标，把「AI 划词翻译」固定到工具栏
|
||
|
||
## ⚙️ 配置模型
|
||
|
||
1. 点击工具栏图标 → **⚙ 模型设置**（或在扩展管理页进入「扩展程序选项」）
|
||
2. 选择服务商（会自动填好接口地址和推荐模型）
|
||
3. 填入 **API Key**（Ollama 本地无需 Key）
|
||
4. 点击 **测试连接** 验证，保存
|
||
|
||
### 推荐服务商
|
||
|
||
| 服务商 | 获取 Key | 推荐模型 | 备注 |
|
||
|---|---|---|---|
|
||
| DeepSeek | platform.deepseek.com | `deepseek-chat` | 便宜好用，国内直连 |
|
||
| 智谱 GLM | open.bigmodel.cn | `glm-4-flash` | 免费额度 |
|
||
| 月之暗面 Kimi | platform.moonshot.cn | `moonshot-v1-8k` | 长上下文 |
|
||
| 通义千问 | bailian.aliyun.com | `qwen-plus` | 阿里云百炼 |
|
||
| Google Gemini | aistudio.google.com | `gemini-2.0-flash` | 有免费额度 |
|
||
| Ollama | 本地 `ollama serve` | `qwen2.5:7b` | 无需 Key，完全本地 |
|
||
|
||
### Ollama 用户注意
|
||
|
||
启动时需允许跨域：`OLLAMA_ORIGINS='*' ollama serve`，接口地址填 `http://localhost:11434/v1`，模型名用 `ollama list` 里的名字。
|
||
|
||
## 🖱️ 使用
|
||
|
||
| 操作 | 效果 |
|
||
|---|---|
|
||
| 选中文字 | 出现紫色「译」按钮，点击翻译 |
|
||
| `Alt+T` | 翻译当前选中文字（可在 `chrome://extensions/shortcuts` 改键） |
|
||
| 右键选中文本 | 菜单「AI 翻译"…"」 |
|
||
| `Esc` | 关闭翻译弹窗 |
|
||
| 拖弹窗标题栏 / 右下角 | 移动 / 调整大小 |
|
||
| 点弹窗顶部「原文」按钮 | 展开 / 收起左栏原文（收起后译文独占全宽，长文各自独立滚动） |
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
fanyi/
|
||
├── manifest.json # MV3 清单
|
||
├── background.js # Service Worker：LLM API 调用 + SSE 流解析 + 快捷键/右键菜单
|
||
├── content/
|
||
│ ├── content.js # 内容脚本：划词检测、FAB、翻译弹窗（Shadow DOM 隔离）
|
||
│ └── content.css # 占位（样式在 Shadow DOM 内）
|
||
├── popup/ # 工具栏弹窗：开关、语言、触发方式
|
||
├── options/ # 设置页：服务商、Key、模型、Prompt
|
||
├── icons/ # 图标
|
||
└── README.md
|
||
```
|
||
|
||
## 🚀 版本发布（Gitea Actions 流水线）
|
||
|
||
流水线跑在 NUC 的 act_runner 上，配置见 `.gitea/workflows/`：
|
||
|
||
| 工作流 | 触发条件 | 作用 |
|
||
|---|---|---|
|
||
| `ci.yml` | push 到 `main` / PR | manifest 校验 + JS 语法检查 |
|
||
| `release.yml` | 推送 `vX.Y.Z` 标签 | 校验版本一致 → 打包 zip → 生成 Changelog → 创建 Release 并上传附件 |
|
||
|
||
### 方式一：网页触发（推荐）
|
||
|
||
打开仓库 **Actions → Release workflow → Run workflow**，填入版本号（如 `1.0.2`），点 Run 即可。流水线会自动：
|
||
|
||
1. 把 `manifest.json` 的 `version` 同步为该版本号并提交（提交带 `[skip ci]`，避免重复触发）
|
||
2. 创建并推送 `vX.Y.Z` 标签
|
||
3. 打包 zip、生成 changelog、创建 Release 并上传附件
|
||
|
||
可选填「发布说明」，留空则自动生成；重复触发同一版本是幂等的，不会重复发布。
|
||
|
||
### 方式二：本地打 tag
|
||
|
||
```bash
|
||
# 1. 更新 manifest.json 中的 version 字段
|
||
# 2. 提交
|
||
git add -A && git commit -m "release: v1.0.1"
|
||
# 3. 打 tag 并推送（tag 必须与 manifest 版本一致，否则流水线报错）
|
||
git tag v1.0.1 && git push origin main --tags
|
||
```
|
||
|
||
发布地址：`https://git.zzzjy.cloud/zzzjy/PopLingo/releases`
|
||
|
||
## ❓ 常见问题
|
||
|
||
- **本地 HTML 文件不生效**：在 `chrome://extensions/` → 本插件 → 详情 → 打开「允许访问文件网址」
|
||
- **API Key 存在哪**：Chrome 账号的 `storage.sync`，随浏览器账号同步，不上传到任何第三方
|
||
- **请求失败 401/404/429**：分别检查 Key 是否正确、Base URL/模型名是否对、额度是否充足，设置页有「测试连接」可一键诊断
|