feat: 新增视频字幕翻译功能，支持 YouTube 平台

[airhunter]

功能概述

新增视频字幕翻译功能，在 YouTube 等平台开启原生字幕后，
自动拦截字幕数据、翻译并以双语形式叠加显示在视频上。

新增文件

• entrypoints/video/manager.ts — 核心调度：拦截消息、解析、翻译、渲染
• entrypoints/video/overlay.ts — 字幕浮层渲染，RAF 时间轴同步 + 二分搜索
• entrypoints/video/parser.ts — 支持 YouTube XML、JSON3、WebVTT 三种格式
• entrypoints/video/platforms.ts — 平台配置（域名、字幕 URL 规则）
• public/video-subtitle-inject.js — MAIN world 注入脚本，Hook XHR/fetch 拦截字幕请求

修改文件

• components/Main.vue — 新增视频字幕翻译开关（默认开启）
• entrypoints/content.ts — 初始化字幕翻译模块
• entrypoints/utils/model.ts — 新增 enableVideoSubtitle 配置项
• wxt.config.ts — 注册 MAIN world content script，限定支持平台域名

技术方案

字幕拦截
通过 MAIN world content script 在 document_start 注入，绕过页面 CSP 限制，
Hook XHR/fetch 拦截字幕请求，通过 postMessage 传递给 content script。

翻译质量
YouTube ASR 字幕无标点、全小写，使用时间间隔（< 600ms）作为断句信号，
将连续的碎片 cue 合并为完整句子组后翻译，解决"united states"等跨 cue 短语被切断的问题。
同时引入 carry-over 机制，防止句尾碎片（如"but the seeds"）因词数上限而被孤立。

翻译调用
每批 5 组，附带前文上下文，字幕专用提示词告知模型允许跨行借用语义，
译文回填到组内所有 cue，组内 cue 共享同一译文。

渲染
requestAnimationFrame 驱动时间轴同步，二分搜索定位当前 cue，
使用 createElement + textContent 安全写入 DOM。
YouTube 播放器工具栏注入快捷开关按钮，支持实时切换显示/隐藏。

安全

• 所有 DOM 写入改用 createElement + textContent，消除 XSS 风险
• SVG 图标改用 createElementNS 构建，移除 innerHTML
• MAIN world 脚本注入范围限定为已支持的平台域名，不注入无关站点

Summary by Sourcery

Add a video subtitle translation pipeline for supported video platforms and wire it into the extension configuration and content scripts.

New Features:

• Introduce configurable video subtitle translation, enabled by default and controllable via the main UI switch.
• Implement a video subtitle manager that intercepts subtitle network traffic, parses multiple subtitle formats, batches translations, and renders bilingual overlays synchronized with video playback.
• Add a YouTube-specific in-player toggle button to quickly enable or disable translated subtitles.
• Provide a main-world injected script to hook XHR/fetch subtitle requests and communicate them to the content script, with dynamic subtitle URL pattern configuration.
• Define per-platform configurations for video elements, containers, and subtitle URL patterns, including a generic WebVTT fallback.

Enhancements:

• Update extension manifest and WXT config to register a main-world content script for subtitle interception on selected video-learning domains.
• Refine DOM manipulation for newly added UI and overlay elements to avoid innerHTML and reduce XSS risk by using element creation APIs.

[sourcery-ai]

Reviewer's Guide

Implements a new video subtitle translation pipeline for YouTube and generic VTT-based platforms by injecting a MAIN-world network hook script, parsing multiple subtitle formats, grouping and batch-translating cues, and rendering a bilingual overlay synchronized to the video timeline, with a UI toggle and configuration flag to control the feature.

Sequence diagram for video subtitle interception and translation pipeline

sequenceDiagram
    actor User
    participant YouTubePage
    participant MainWorldScript as MainWorldScript_video_subtitle_inject
    participant ContentScript as ContentScript
    participant VideoManager as VideoSubtitleManager
    participant SubtitleParser as SubtitleParser
    participant Overlay as SubtitleOverlay
    participant TranslateApi as TranslateApi
    participant Config as ConfigStore

    User->>YouTubePage: Enable native subtitles

    ContentScript->>Config: Read enableVideoSubtitle
    Config-->>ContentScript: enableVideoSubtitle=true
    ContentScript->>VideoManager: initVideoSubtitle()
    VideoManager->>MainWorldScript: window.postMessage config(patterns)
    VideoManager->>VideoManager: attachMessageListener()
    VideoManager->>VideoManager: watchNavigation()

    Note over MainWorldScript,YouTubePage: Network interception in MAIN world
    YouTubePage->>MainWorldScript: XHR or fetch to subtitle URL
    MainWorldScript->>MainWorldScript: isSubtitleUrl(url)
    MainWorldScript-->>YouTubePage: Proceed with request
    YouTubePage-->>MainWorldScript: Response with subtitle data
    MainWorldScript->>MainWorldScript: Cache lastCapture
    MainWorldScript->>ContentScript: window.postMessage subtitle-captured(url,data)

    ContentScript->>VideoManager: window message event
    VideoManager->>VideoManager: handleSubtitleData(url,data)
    VideoManager->>SubtitleParser: detectSubtitleFormat(url,data)
    SubtitleParser-->>VideoManager: format
    VideoManager->>SubtitleParser: parseYouTubeXML/parseYouTubeJSON3/parseVTT
    SubtitleParser-->>VideoManager: SubtitleCue[]

    VideoManager->>YouTubePage: findVideo()
    YouTubePage-->>VideoManager: HTMLVideoElement
    VideoManager->>YouTubePage: findMountTarget(video)
    YouTubePage-->>VideoManager: mountTarget

    VideoManager->>Overlay: mount(video,mountTarget)
    VideoManager->>Overlay: setCues(cues) with original text
    VideoManager->>YouTubePage: hideNativeSubtitle()
    VideoManager->>YouTubePage: mountQuickButton()

    loop Playback
        YouTubePage->>Overlay: video.currentTime via requestAnimationFrame
        Overlay->>Overlay: findCue(time) via binary search
        Overlay->>Overlay: render(cue) bilingual overlay
    end

    loop Batch translation
        VideoManager->>VideoManager: mergeByTimeGap(cues)
        VideoManager->>TranslateApi: translateText(batchWithContext,document.title)
        TranslateApi-->>VideoManager: translatedLines
        VideoManager->>VideoManager: Fill translatedText on SentenceGroup.cues
        VideoManager->>Overlay: setCues(updatedCues)
    end

    User->>YouTubePage: Click quick toggle button
    YouTubePage->>VideoManager: Toggle subtitleEnabled
    alt subtitleEnabled
        VideoManager->>YouTubePage: hideNativeSubtitle()
        VideoManager->>Overlay: show()
    else not subtitleEnabled
        VideoManager->>Overlay: hide()
        VideoManager->>YouTubePage: restoreNativeSubtitle()
    end

Loading

Updated class diagram for subtitle translation types and configuration

classDiagram
    class Config {
        +boolean on
        +boolean translationStatus
        +string inputBoxTranslationTrigger
        +string inputBoxTranslationTarget
        +boolean enableVideoSubtitle
        +Config()
    }

    class SubtitleCue {
        +number start
        +number end
        +string text
        +string translatedText
    }

    class SubtitleOverlay {
        -HTMLElement container
        -HTMLVideoElement video
        -SubtitleCue[] cues
        -number rafId
        -string lastCueKey
        -HTMLElement mountTarget
        -string originalMountPosition
        +mount(video, mountTarget)
        +setCues(cues)
        +show()
        +hide()
        +cleanup()
        -startLoop()
        -findCue(time)
        -render(cue)
    }

    class PlatformConfig {
        +string id
        +string[] matches
        +string[] subtitleUrlPatterns
        +string format
        +string videoSelector
        +string containerSelector
        +string hideNativeSelector
    }

    class PlatformsModule {
        +PlatformConfig[] platforms
        +detectPlatform(hostname)
        +getAllSubtitlePatterns()
    }

    class ParserModule {
        +parseYouTubeXML(xmlText) SubtitleCue[]
        +parseYouTubeJSON3(jsonText) SubtitleCue[]
        +parseVTT(vttText) SubtitleCue[]
        +detectSubtitleFormat(url, data) string
        -mergeOverlappingCues(cues) SubtitleCue[]
        -vttTimeToSeconds(t) number
        -stripVttTags(text) string
        -decodeEntities(text) string
    }

    class VideoSubtitleManager {
        -SubtitleOverlay overlay
        -boolean listenerAttached
        -string processingUrl
        -boolean subtitleEnabled
        +initVideoSubtitle()
        -sendConfig()
        -attachMessageListener()
        -handleSubtitleData(url, rawData)
        -mergeByTimeGap(cues) SentenceGroup[]
        -translateCuesBatched(cues, onProgress)
        -mountQuickButton()
        -buildBtnSvg(active) SVGElement
        -waitForElement(selector, callback, maxMs)
        -findVideo() HTMLVideoElement
        -findMountTarget(video) HTMLElement
        -hideNativeSubtitle()
        -restoreNativeSubtitle()
        -watchNavigation()
    }

    class SentenceGroup {
        +SubtitleCue[] cues
        +string text
    }

    Config <.. VideoSubtitleManager : reads
    SubtitleCue <.. SentenceGroup : element
    SubtitleOverlay o-- SubtitleCue : renders
    VideoSubtitleManager o-- SubtitleOverlay : owns
    VideoSubtitleManager ..> ParserModule : uses
    VideoSubtitleManager ..> PlatformsModule : uses
    PlatformsModule o-- PlatformConfig : aggregates
    ParserModule o-- SubtitleCue : creates

Loading

File-Level Changes

Change	Details	Files
Add a MAIN-world content script that hooks XHR/fetch to capture subtitle responses and forwards them to the extension via postMessage, configurable by regex-based URL patterns.	Define an IIFE that hooks XMLHttpRequest.open/send to record request URLs and, on successful responses, forwards subtitle responseText when the URL matches configured patterns. Wrap window.fetch to detect subtitle URLs, clone responses, and forward the text content while preserving normal response behavior. Maintain a lastCapture cache so captured subtitles can be resent when the content script becomes ready. Listen for configuration messages from the content script to update subtitle URL regex patterns and send any cached capture back; send an initial 'ready' message on init.	public/video-subtitle-inject.js
Introduce a video subtitle management module that receives captured subtitle data, parses it, groups cues into sentence-like units, batch-translates them, and drives a custom overlay plus a YouTube toolbar toggle button.	Expose initVideoSubtitle from the content script side, which checks the config flag, sends subtitle pattern config to the injected script, attaches a postMessage listener, sets up SPA navigation watching, and mounts a YouTube quick toggle button when applicable. Implement a postMessage listener that de-duplicates by URL, detects subtitle format, parses cues, mounts the overlay on the correct video/container, hides native subtitles, and then performs progressive batch translation with overlay updates. Add time-gap-based cue grouping (mergeByTimeGap) with a carry-over mechanism to avoid isolating short end fragments and to merge ASR fragments into sentence groups before translation. Implement translateCuesBatched to build a numbered, context-aware prompt, call translateText, map returned lines back to groups, and assign translatedText to each cue, falling back to original text on errors. Add a YouTube-specific quick toggle button (built via createElement/createElementNS) injected into .ytp-right-controls, which toggles subtitleEnabled, shows/hides the overlay, and hides/restores native subtitles; reset state on SPA navigation via yt-navigate-finish and a title MutationObserver.	entrypoints/video/manager.ts
Create a reusable subtitle overlay component that runs an rAF-driven timeline loop, uses binary search to pick the active cue, and renders bilingual lines using safe DOM APIs.	Define SubtitleOverlay with lifecycle methods mount, setCues, show, hide, and cleanup, tracking the associated video, container, mount target, and previous CSS position. On mount, create an absolutely positioned overlay div inside the video container, adjust the container to position:relative if needed, then start an rAF loop that queries video.currentTime and finds the active cue via binary search including overlapping cues. Render subtitles by clearing and rebuilding children using createElement + textContent, showing original and translated lines in bilingual mode based on config.display, with styling tuned for readability. Ensure cleanup cancels rAF, removes the overlay element, and restores the original container position to avoid layout side effects on navigation.	entrypoints/video/overlay.ts
Implement multi-format subtitle parsing utilities for YouTube XML, YouTube JSON3, and WebVTT formats with helper functions for time conversion and entity handling.	Define a common SubtitleCue interface with start/end times, original text, and optional translatedText. Implement parseYouTubeXML using DOMParser to read nodes, decode entities, and then merge overlapping cues (mergeOverlappingCues) to rebuild full lines from scrolling captions. Implement parseVTT that normalizes newlines, block-splits cues, parses time ranges, strips VTT markup tags, and joins cue text lines into a single string per cue. Implement parseYouTubeJSON3 that parses events, concatenates segs.utf8, and converts ms-based times into seconds, skipping empty lines. Add detectSubtitleFormat that uses content heuristics and URL hints to choose among YouTube XML, JSON3, and VTT, and helper utilities for VTT time parsing, entity decoding, and tag stripping.	entrypoints/video/parser.ts
Add platform configuration to map hostnames to video/subtitle selectors and subtitle URL patterns, and expose utilities to detect the platform and aggregate patterns for the injected script.	Define PlatformConfig with hostname matches, subtitle URL regex strings, expected format, video/container selectors, and optional native subtitle selectors to hide. Add a YouTube config that targets youtube.com/youtubekids.com, matches /api/timedtext, selects the HTML5 player video/container, and hides .ytp-caption-window-container. Add a generic VTT config that matches all hosts, looking for .vtt and common subtitle paths, selecting a generic Implement detectPlatform to prefer non-generic configs based on hostname substring, falling back to generic VTT, and getAllSubtitlePatterns to dedupe and aggregate all subtitle regexes for MAIN-world injection.	entrypoints/video/platforms.ts
Wire the new video subtitle feature into the extension’s configuration, content script initialization, and popup UI, and register the MAIN-world script in the extension manifest for supported domains only.	Extend the Config model with an enableVideoSubtitle boolean field, defaulting to true in the constructor, and persist it like other settings. In the main Vue UI, add a labeled section shown when the extension is on that explains the video subtitle translation feature and binds an el-switch to config.enableVideoSubtitle for user control. Update the main content script entrypoint to import initVideoSubtitle from the new manager module and call it during onMount to initialize video subtitle translation on supported pages. Update wxt.config.ts manifest to add a content_scripts entry that injects video-subtitle-inject.js in the MAIN world at document_start for a curated list of video platforms (YouTube, YouTube Kids, Udemy, Coursera, Khan Academy), with comments explaining CSP bypass and scope control.	entrypoints/utils/model.ts components/Main.vue entrypoints/content.ts wxt.config.ts

Possibly linked issues

• #: PR 实现 YouTube 字幕拦截、翻译和双语叠加显示，满足“添加 YouTube 双语字幕功能”需求。

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• The YouTube-specific behavior is scattered (e.g., hostname checks in both initVideoSubtitle and watchNavigation plus CSS selectors in platforms.ts); consider centralizing platform-specific logic (including whether to mount the quick button) into the PlatformConfig so that adding/removing platforms doesn’t require touching multiple files.
• In SubtitleOverlay.mount, you call cleanup() after assigning this.video but before this.mountTarget, and cleanup() removes #fr-subtitle-overlay globally; if multiple overlays are ever mounted (e.g., multiple videos or future features), this global removal could become surprising—consider scoping cleanup to the instance’s container instead of using document.getElementById.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The YouTube-specific behavior is scattered (e.g., hostname checks in both `initVideoSubtitle` and `watchNavigation` plus CSS selectors in `platforms.ts`); consider centralizing platform-specific logic (including whether to mount the quick button) into the `PlatformConfig` so that adding/removing platforms doesn’t require touching multiple files.
- In `SubtitleOverlay.mount`, you call `cleanup()` after assigning `this.video` but before `this.mountTarget`, and `cleanup()` removes `#fr-subtitle-overlay` globally; if multiple overlays are ever mounted (e.g., multiple videos or future features), this global removal could become surprising—consider scoping cleanup to the instance’s container instead of using `document.getElementById`.

## Individual Comments

### Comment 1
<location path="entrypoints/video/manager.ts" line_range="290-295" />
<code_context>
+    return (video.parentElement as HTMLElement) || document.body
+}
+
+function hideNativeSubtitle() {
+    const platform = detectPlatform(window.location.hostname)
+    if (!platform.hideNativeSelector) return
+    // 用 display:none 彻底隐藏，visibility:hidden 仍占位且有时被 YouTube 重置
+    document.querySelectorAll<HTMLElement>(platform.hideNativeSelector)
+        .forEach(el => el.style.setProperty('display', 'none', 'important'))
+}
+
</code_context>
<issue_to_address>
**issue (bug_risk):** Hiding native subtitles overwrites `display` without preserving original values, which can interfere with site styling.

Because `hideNativeSubtitle` sets `display: none !important` and the corresponding restore logic only calls `removeProperty('display')`, any pre-existing inline `display` value is lost after the first toggle, which can change how the page lays out those elements.

Consider storing the previous inline `display` value (e.g. in a `data-` attribute) before overriding it, and restoring from that when subtitles are re-enabled, so the page’s original layout is preserved.
</issue_to_address>

### Comment 2
<location path="entrypoints/video/overlay.ts" line_range="67" />
<code_context>
+            cancelAnimationFrame(this.rafId)
+            this.rafId = null
+        }
+        document.getElementById(OVERLAY_ID)?.remove()
+        if (this.mountTarget !== undefined && this.originalMountPosition !== undefined) {
+            this.mountTarget.style.position = this.originalMountPosition
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Cleanup removes any element with the overlay ID globally instead of just this instance’s container.

Using `document.getElementById(OVERLAY_ID)?.remove()` works now but risks removing an unrelated element if the host page reuses that ID, and it’s not tied to this instance. Calling `this.container?.remove()` would scope cleanup to the overlay created by this instance and better support multiple overlays or non-document mount points.

```suggestion
        this.container?.remove()
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[airhunter]

@Bistutu Hi, I've added support for YouTube subtitle translations.
Could you please review this PR when you have time? Thanks!