Annotate Translate

主题

快速开始 ​

本指南帮助您快速安装、配置和使用 Annotate Translate 扩展。

安装扩展 ​

方式 1: 开发者模式安装 (推荐) ​

适用于想要 Fork 和二次开发的开发者。

  1. 克隆仓库
bash
git clone https://github.com/your-username/annotate-translate.git
cd annotate-translate

  1. 加载扩展

    • 打开 Chrome 浏览器
    • 访问 chrome://extensions/
    • 打开右上角的 "开发者模式"
    • 点击 "加载已解压的扩展程序"
    • 选择项目根目录

  2. 验证安装

    • 扩展图标出现在浏览器工具栏
    • 点击图标查看 Popup 界面

无需构建

此扩展使用 Vanilla JavaScript，无需 npm install 或构建步骤，克隆后即可加载。

方式 2: Chrome Web Store 安装 (未来) ​

(待扩展发布到 Chrome Web Store 后提供)

Annotation and Translation Demo

基本使用 ​

1. 翻译选中文本 ​

最常用的功能，快速翻译网页中的任意文本。

步骤:

  1. 在网页上选中要翻译的文本
  2. 等待浮动菜单出现 (约 0.2 秒)
  3. 点击 "翻译" 按钮

效果:

  • 显示翻译卡片，包含:
    • 翻译结果
    • 音标 (如果有)
    • 释义 (如果有)
    • 例句 (如果有)
    • 音频播放按钮

快捷操作:

  • 音频播放: 点击 🔊 图标朗读原文
  • 关闭卡片: 点击卡片外任意位置或按 Esc 键

2. 添加文本标注 ​

为网页文本添加永久性标注 (Ruby 注释)。

步骤:

  1. 选中要标注的文本
  2. 点击浮动菜单中的 "标注" 按钮

效果:

  • 文本上方显示标注 (音标 + 翻译)
  • 标注会保存到云端，刷新页面后仍然存在

示例:

html
<!-- 原始文本 -->
Hello world

<!-- 标注后 -->
<ruby>Hello<rt>/həˈloʊ/ 你好</rt></ruby> world

查看已保存的标注:

  • 点击扩展图标 → "我的标注"
  • 按网站分组查看所有标注

3. 词汇模式 ​

批量扫描页面词汇并自动标注。

步骤:

  1. 打开设置页面 (chrome://extensions/ → 找到扩展 → "扩展程序选项")

  2. 找到 "词汇模式" 开关，启用

  3. 选择词库:

    • CET-4 (大学英语四级)
    • CET-6 (大学英语六级)
    • TOEFL (托福)
    • IELTS (雅思)
    • GRE (研究生入学考试)
    • 自定义词库

  4. 刷新任意网页

效果:

  • 自动扫描页面中的词汇
  • 匹配词库的单词自动添加标注
  • 适合学习英语、阅读外文文献

性能优化:

  • ✅ 批量翻译 (10 词/批次)
  • ✅ 并发限制 (最多 3 个并发请求)
  • ✅ 可中断扫描 (点击 "停止扫描" 按钮)

配置翻译提供商 ​

Annotate Translate 支持 5 个翻译提供商，可根据需求切换。

Google Translate (默认) ​

优势: 免费、无需配置、支持多种语言

缺点: 翻译质量一般

配置: 无需配置

有道翻译 ​

优势: 中文翻译质量高、支持音标和释义

缺点: 需要 API Key

配置步骤:

  1. 访问 有道智云 注册账号
  2. 创建应用，获取 App Key 和 App Secret
  3. 打开扩展设置页面
  4. 找到 "有道翻译" 配置项
  5. 填入 App Key 和 App Secret
  6. 点击 "测试连接" 验证
  7. 切换到 "有道翻译" 提供商

DeepL ​

优势: 翻译质量最高 (特别是欧洲语言)

缺点: 需要 API Key、免费额度有限

配置步骤:

  1. 访问 DeepL API 注册账号
  2. 获取 API Key
  3. 打开扩展设置页面
  4. 找到 "DeepL" 配置项
  5. 填入 API Key
  6. 选择端点:
    • Free API: https://api-free.deepl.com/v2/translate
    • Pro API: https://api.deepl.com/v2/translate
  7. 点击 "测试连接" 验证
  8. 切换到 "DeepL" 提供商

OpenAI (AI 翻译) ​

优势:

  • 上下文感知翻译
  • 专业术语理解能力强
  • 可自定义提示词

缺点:

  • 需要 API Key
  • 按 Token 计费

配置步骤:

  1. 访问 OpenAI Platform 获取 API Key
  2. 打开扩展设置页面
  3. 找到 "OpenAI 翻译" 配置项
  4. 配置参数:
    • API Key: 必填
    • Model: 选择模型 (推荐 gpt-3.5-turbo)
    • Base URL: 默认 https://api.openai.com/v1 (可改为兼容端点)
    • Temperature: 0.3 (值越低越确定)
    • Max Tokens: 500
  5. 高级选项:
    • 提示词格式: JSON 格式 (推荐) / 简单格式
    • 使用上下文: 启用后提取选中文本的上下文
  6. 点击 "测试连接" 验证
  7. 切换到 "OpenAI" 提供商

成本估算:

模型输入价格输出价格每次翻译成本 (估算)
gpt-3.5-turbo$0.0015/1K tokens$0.002/1K tokens$0.0003 - $0.001
gpt-4$0.03/1K tokens$0.06/1K tokens$0.006 - $0.02
gpt-4-turbo$0.01/1K tokens$0.03/1K tokens$0.002 - $0.008

兼容其他 API

只要 API 兼容 OpenAI Chat Completions 格式，都可以使用，例如:

  • Azure OpenAI
  • Claude (通过兼容层)
  • DeepSeek
  • 本地 LLM (Ollama + LiteLLM)

FreeDictionary ​

用途: 音标补充 (内部使用)

说明:

  • 当其他提供商未返回音标时，自动查询 FreeDictionary API
  • 仅支持英文单词
  • 不能作为主翻译提供商

高级功能 ​

自定义显示设置 ​

翻译卡片:

  • 位置: 自动 / 文本上方 / 文本下方
  • 最大宽度: 300px - 600px
  • 字体大小: 12px - 18px

浮动菜单:

  • 显示延迟: 选中文本后多久显示菜单 (0 - 1000ms)
  • 隐藏延迟: 鼠标移开后多久隐藏菜单 (0 - 2000ms)

标注样式:

  • 颜色: 自定义标注文本颜色
  • 下划线: 实线 / 虚线 / 点线 / 无

配置位置: 设置页面 → "显示设置"

自定义标注内容 ​

控制标注显示哪些信息。

选项:

  • ✅ 显示音标: 在标注中包含音标
  • ✅ 显示翻译: 在标注中包含翻译
  • ⬜ 显示释义: 在标注中包含第一条释义 (可能很长)

示例:

配置标注效果
音标 + 翻译/həˈloʊ/ 你好
仅翻译你好
音标 + 翻译 + 释义/həˈloʊ/ 你好 (int. 喂，你好)

配置位置: 设置页面 → "标注设置"

性能优化 ​

缓存设置:

  • 启用缓存: 缓存翻译结果 (强烈推荐)
  • 缓存大小: 最多缓存多少条翻译 (默认 100)
  • 缓存 TTL: 缓存有效期 (默认 1 小时)

效果:

  • ✅ 相同文本无需重复请求 API
  • ✅ 提升响应速度
  • ✅ 节省 API 配额

配置位置: 设置页面 → "性能设置"

右键菜单 ​

除了浮动菜单，还可以使用右键菜单。

启用方法:

  1. 设置页面 → "常规设置"
  2. 启用 "启用右键菜单"

使用:

  1. 选中文本
  2. 右键点击
  3. 选择 "翻译选中文本" 或 "标注选中文本"

使用技巧 ​

1. 快速翻译单词 ​

选中单词后等待浮动菜单出现，点击 "翻译"。

适合场景: 阅读外文文章时快速查词

2. 上下文翻译 (AI 提供商) ​

选中专业术语，AI 会根据上下文选择最合适的翻译。

示例:

原文: "The chamber is designed to protect sensitive equipment from electromagnetic interference."

选中词: "chamber"

AI 翻译: "舱室" ✅ (而非 "房间")

配置: 使用 OpenAI 提供商，启用 "使用上下文"

3. 批量标注词汇 ​

启用词汇模式，打开英文网页，自动标注所有词库单词。

适合场景:

  • 学习英语文章
  • 阅读技术文档
  • 准备考试 (CET/TOEFL/IELTS/GRE)

4. 导出标注数据 ​

保存的标注存储在 chrome.storage.sync，可以导出备份。

方法:

  1. 打开设置页面 → "数据管理"
  2. 点击 "导出标注数据"
  3. 保存 JSON 文件

导入:

  1. 打开设置页面 → "数据管理"
  2. 点击 "导入标注数据"
  3. 选择 JSON 文件

5. 多设备同步 ​

标注和设置自动同步到 Google 账号 (通过 chrome.storage.sync)。

要求:

  • 登录 Chrome 账号
  • 启用 "同步扩展程序"

同步内容:

  • ✅ 所有标注数据
  • ✅ 扩展设置
  • ❌ 翻译缓存 (仅本地)

常见问题 ​

翻译失败怎么办? ​

检查清单:

  1. ✅ 网络连接正常
  2. ✅ API Key 配置正确 (有道/DeepL/OpenAI)
  3. ✅ 提供商 API 额度充足
  4. ✅ 打开浏览器控制台查看错误消息

解决方法:

  • 切换到 Google Translate (无需配置)
  • 刷新页面重试
  • 检查设置页面 "测试连接" 功能

标注不显示怎么办? ​

可能原因:

  1. 网站 CSS 冲突: 某些网站样式覆盖了 <ruby> 标签
  2. 动态内容: 网站使用 JavaScript 动态加载内容，标注被清除

解决方法:

  • 刷新页面后重新标注
  • 在设置中调整标注样式
  • 使用翻译卡片而非标注功能

词汇模式扫描太慢? ​

优化方法:

  1. 减小词库: 选择更小的词库 (如 CET-4 而非 GRE)
  2. 关闭批量翻译: 设置 → "性能设置" → 减小批量大小
  3. 中断扫描: 点击 Popup 中的 "停止扫描" 按钮

音频播放失败? ​

原因: 某些提供商不提供音频

解决方法:

  • 系统会自动降级到浏览器 TTS (Text-to-Speech)
  • 切换到支持音频的提供商 (Google/有道)

API 成本太高? ​

节省方法:

  1. 使用 gpt-3.5-turbo: 比 GPT-4 便宜 10 倍
  2. 启用缓存: 避免重复翻译
  3. 禁用上下文: 减少 Token 消耗
  4. 切换到免费提供商: Google Translate 完全免费

键盘快捷键 ​

(未来功能)

计划支持的快捷键:

  • Ctrl/Cmd + Shift + T: 翻译选中文本
  • Ctrl/Cmd + Shift + A: 标注选中文本
  • Esc: 关闭翻译卡片

下一步 ​

相关链接 ​

Released under the MIT License.

Copyright © 2024-present