# 译泡 · 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（普通 API） | open.bigmodel.cn | `glm-4-flash` | 免费额度，按量计费 |
| 智谱 GLM Coding Plan | open.bigmodel.cn | `glm-5.3` | 订阅套餐，走专属接入点不按 token 扣费 |
| 月之暗面 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/模型名是否对、额度是否充足，设置页有「测试连接」可一键诊断