Skip to content

README.md

Latest commit

 

History

History
260 lines (192 loc) · 9.92 KB

README.md

File metadata and controls

260 lines (192 loc) · 9.92 KB
Raw

YouTube 双语字幕 / YouTube Bilingual Subtitles

一个开源的 Chrome 扩展，在 YouTube 上显示 AI 双语字幕，支持生词高亮、点词查义、词汇追踪，可接入云端 API 或本地大模型。

An open-source Chrome extension that shows AI-powered bilingual subtitles on YouTube, with word highlighting, click-to-define, vocabulary tracking, and support for both cloud APIs and local LLMs.

Chrome Extension Manifest V3 License Ollama OpenAI Compatible

✨ 功能特点 / Features

功能 描述
🌍 双语字幕 同时显示视频原文字幕 + AI 翻译字幕
🧭 三种显示模式 可随时切换原文、双语、仅译文，并支持顶部/底部位置
⏱️ 准确跟随时间 保留人工字幕时间，滚动字幕不会提前显示后文，跳转后快速定位
🎨 生词高亮 已掌握（绿色）、生词（橙色）、学习中（蓝色虚线）
⏸️ 点击暂停 点击字幕区域暂停/恢复视频
📖 单词弹窗 点击任意单词，显示发音 / 词性 / 释义 / 例句解释
✅ 词汇追踪 标记单词为"已掌握"或"学习中"，持久保存
📝 字幕面板 右侧可滑动字幕列表，点击跳转到对应时间
🤖 AI 翻译 支持 OpenAI / 任意兼容 API / 本地 Ollama 大模型
🛟 可用性回退 翻译不可用时保留原文，并在播放器与弹窗中说明状态
📱 多页面支持 支持普通视频、Shorts、嵌入式播放器和页面内切换
📚 词汇管理 统计、导出、导入词汇表（JSON 格式）
🚫 零成本可选 配置本地大模型后完全免费使用

🚀 安装扩展 / Installation

1. 下载源码

git clone https://github.com/YOUR_USERNAME/YouTubeTranslator.git
# 或直接下载 ZIP 解压

2. 加载到 Chrome

  1. 打开 Chrome，地址栏输入：chrome://extensions/
  2. 右上角开启 「开发者模式」（Developer mode）
  3. 点击 「加载已解压的扩展程序」（Load unpacked）
  4. 选择项目文件夹 YouTubeTranslator
  5. 扩展加载成功，首次安装会自动打开设置页面

3. 选择翻译方式（AI 可选）

首次安装默认使用 YouTube 自带翻译，不要求本地模型或 API。若希望获得更稳定的上下文翻译，可点击浏览器右上角的扩展图标 → 「Full Settings」，开启 AI Translation 并选择以下任一方式。

🤖 可选的 AI 翻译配置 / Optional AI Translation Setup

方式一：云端 API（推荐新手）

在设置页选择 「Cloud API」，填写服务商提供的 API 地址、密钥与模型名称。插件支持 OpenAI 兼容接口。配置后先点击 Test Connection；价格和模型可用性以各服务商的最新说明为准。

方式二：本地大模型（免费、隐私）

本地部署无需任何 API Key，完全免费且数据不离开你的电脑。

💻 本地大模型部署指南 / Local LLM Deployment

🔧 工具：Ollama

Ollama 是目前最简单的本地大模型运行工具，一条命令即可下载并运行模型。

安装 Ollama

Windows：

# 方法一：通过 winget 安装（推荐）
winget install Ollama.Ollama

# 方法二：直接下载安装包
# 访问 https://ollama.com/download 下载 OllamaSetup.exe

macOS：

# 方法一：官网下载（推荐）
# 访问 https://ollama.com/download 下载 .dmg 安装包

# 方法二：Homebrew
brew install ollama

Linux：

curl -fsSL https://ollama.com/install.sh | sh

▶️ 启动 Ollama 服务

下载模型后，每次使用前需要确保 Ollama 服务在运行：

Windows：

  • 安装后 Ollama 会自动在系统托盘运行（右下角查看）
  • 或手动在 PowerShell 运行：ollama serve

macOS：

  • 安装后自动后台运行
  • 或终端运行：ollama serve

验证服务是否正常：

# 在浏览器访问或命令行测试
curl http://localhost:11434/api/tags
# 应返回已安装的模型列表

⚙️ 在插件中配置本地大模型

  1. 打开 YouTube 视频页面
  2. 点击浏览器右上角扩展图标
  3. 点击 「Full Settings」
  4. 在 「AI Translation Settings」 中：
    • Translation Provider 选择 「Local LLM」
    • Local Endpoint 填写：http://localhost:11434/api/generate
    • Model Name 填写你下载的模型名（如 qwen2.5:14b）
  5. 点击 「Test Connection」 验证连接
  6. 点击 「Save Settings」 保存
  7. 刷新 YouTube 页面，开启视频字幕（CC），即可看到双语字幕！

📁 项目结构 / Project Structure

YouTubeTranslator/
├── manifest.json          # Chrome Extension Manifest V3
├── background/
│   └── background.js      # Service Worker，处理安装和消息路由
├── content/
│   ├── inject.js          # 尽早捕获字幕响应，并支持初始化后重放
│   ├── content.js         # 内容脚本主入口，处理 YouTube SPA 导航
│   ├── content.css        # 字幕、弹窗、面板样式（暗色主题）
│   ├── subtitle.js        # 字幕拦截、双语渲染、词汇高亮
│   ├── subtitleOptimizer.js # 字幕时序、轨道选择、翻译调度与状态管理
│   ├── panel.js           # 右侧字幕面板 + 词汇本标签页
│   └── wordPopup.js       # 单词释义弹窗组件
├── lib/
│   ├── languages.js       # 语言定义、文本分词（支持中日韩）
│   ├── storage.js         # Chrome storage 封装（设置、词汇、翻译缓存）
│   └── translator.js      # AI 翻译服务（云端 API + 本地 LLM）
├── popup/
│   ├── popup.html         # 工具栏弹出窗口
│   ├── popup.css          # 弹窗样式
│   └── popup.js           # 弹窗逻辑（快速设置、状态显示）
├── options/
│   ├── options.html       # 完整设置页面
│   ├── options.css        # 设置页样式
│   └── options.js         # 设置页逻辑（API 测试、词汇管理）
├── icons/                  # 扩展图标（16/48/128px）
├── tests/                  # 字幕时序、翻译可靠性、设置与清单检查
├── package.json            # 一键运行全部检查
└── _locales/
    ├── en/messages.json   # 英文本地化
    └── zh_CN/messages.json # 中文本地化

🎮 使用方法 / How to Use

  1. 打开 YouTube 视频或 Shorts，确保视频有字幕并开启 CC
  2. 字幕自动显示：插件会读取当前字幕轨并按所选模式显示
  3. 点击字幕区域 → 视频暂停/播放
  4. 点击单词 → 视频暂停 + 弹出释义窗口
    • 查看发音、词性、翻译、解释
    • 点击 ✓ Mastered 标记为已掌握（绿色）
    • 点击 📖 Learning 标记为学习中（蓝色）
  5. 字幕面板：点击播放器中的列表按钮切换显示
    • Subtitles 标签：完整字幕列表，点击跳转
    • Vocabulary 标签：查看所有标记的单词

🔑 颜色标注说明 / Word Color Guide

颜色 含义
🟢 绿色 已标记为「已掌握」的单词
🟠 橙色下划线 未标记的单词（可能是生词）
🔵 蓝色虚线 已标记为「学习中」的单词

⚙️ 设置说明 / Settings Reference

设置项 说明
Target Language 视频的语言（你在学习的语言）
Native Language 你的母语（翻译目标语言）
Proficiency Level 语言水平（影响词汇高亮策略）
AI Provider 翻译服务：Cloud API / Custom API / Local LLM
API Key 云端 API 密钥
API Endpoint API 地址（支持任何 OpenAI 兼容接口）
Model 模型名称
Font Size 字幕字体大小（12-28px）
Display Mode 原文 / 双语 / 仅译文
Subtitle Position 字幕显示在播放器顶部或底部
Background Opacity 字幕背景透明度
Auto Translate 是否自动翻译每条字幕
Show Panel 启动时是否自动显示字幕面板

🔧 常见问题 / FAQ

Q：字幕没有出现？ A：请确保：（1）当前是普通视频、Shorts 或嵌入式播放器；（2）视频本身有字幕且已开启 CC；（3）扩展已启用。弹窗会说明当前是在等待字幕、CC 已关闭、视频无字幕，还是翻译服务不可用。

Q：翻译不出来 / 显示 Translation Error？ A：先看播放器或弹窗中的状态提示。若开启了 AI，检查设置页的配置并点击 Test Connection；本地模型还需确认 Ollama 已运行。翻译不可用时插件会继续显示原文。

Q：Ollama 没有使用 GPU？ A：运行 ollama run qwen2.5:14b 时查看任务管理器 GPU 占用。AMD 用户 Windows 下可能需要更新驱动或改用 Linux

Q：MacBook 发热明显？ A：32b 模型计算量大属正常，可切换到 14b 降低负载

Q：能换其他翻译模型吗？ A：可以！任何 Ollama 支持的模型都能用，在设置中修改 Model Name 即可。推荐翻译模型：qwen2.5:14b、qwen2.5:32b、gemma2:9b

✅ 本地检查 / Verification

修改代码后，在项目目录运行：

npm run check

它会检查扩展引用的文件、脚本语法，以及字幕时序、翻译失败恢复、任务取消、缓存、设置迁移和 Shorts 字幕重放等关键场景。

🤝 贡献 / Contributing

欢迎提交 Issue 和 Pull Request！

📄 许可证 / License

MIT License © 2026