# ymcwiki/open-immersive-translate architecture

> Architecture diagram of the GitHub repository ymcwiki/open-immersive-translate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ymcwiki/open-immersive-translate
- Repository: https://github.com/ymcwiki/open-immersive-translate

## Overview

This is an auditable browser-based bilingual translation product, delivered as a Chromium/Firefox extension and a userscript. The main path scans page text, sends translation requests through the extension background scheduler and configured service adapters, then inserts translated content into the page. Separate workflows cover PDF reading/export, video and subtitle-file translation, assistant features, and configuration. Edges use README statements or SOURCE INDEX references; unsampled subsystem internals and some wiring are therefore represented only where documented.

Main entry points: [`src/background/index.ts`](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/index.ts) (Background worker), [`src/content/controller/translation-controller.ts`](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/controller/translation-controller.ts) (Translation controller), [`src/background/scheduler.ts`](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/scheduler.ts) (Translation scheduler), [`src/background/services/index.ts`](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/index.ts) (Translation adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_page["Webpage translation"]
  node_content["Content entry<br/>[index.ts]"]
  node_controller["Translation controller"]
  node_scanner["Text extraction<br/>[scanner.ts]"]
  node_placeholders["Rich-text placeholders<br/>[placeholder.ts]"]
  node_renderer["Page rendering<br/>[inject.ts]"]
  node_userscript["Userscript runtime<br/>[page.ts]"]
end

subgraph group_runtime["Extension runtime"]
  node_background["Background worker<br/>[index.ts]"]
  node_scheduler["Translation scheduler<br/>[scheduler.ts]"]
  node_rules["Site rules<br/>[match.ts]"]
  node_cache[("Translation cache<br/>[cache.ts]")]
end

subgraph group_services["Translation services"]
  node_servicebase["Service contract<br/>[base.ts]"]
  node_adapters["Translation adapters<br/>[index.ts]"]
  node_oauth["ChatGPT OAuth<br/>[auth.ts]"]
  node_assistant["Assistant service<br/>[assistant.ts]"]
end

subgraph group_experiences["Other translation experiences"]
  node_pdf["PDF reader and export<br/>[index.tsx]"]
  node_pdfpage["PDF page extraction<br/>[page.tsx]"]
  node_subtitle["Video subtitles<br/>[engine.ts]"]
  node_subtitlefile["Subtitle-file workflow<br/>[index.tsx]"]
  node_sidepanel["Assistant side panel<br/>[index.tsx]"]
  node_aiwriting["AI writing<br/>[index.ts]"]
  node_search["Search enhancement"]
end

subgraph group_configuration["Configuration and controls"]
  node_options["Settings page<br/>[index.tsx]"]
  node_popup["Popup controls<br/>[index.tsx]"]
  node_config["Shared configuration<br/>[config.ts]"]
end

node_user(("Browser user"))
node_webpage["Web page"]
node_translationproviders{{"Translation providers"}}

node_user -->|"opens"| node_webpage
node_webpage -->|"loads script"| node_content
node_content -.->|"starts translation"| node_controller
node_controller -->|"scans text"| node_scanner
node_scanner -->|"preserves markup"| node_placeholders
node_controller -->|"requests translation"| node_background
node_background -->|"matches site"| node_rules
node_background -->|"dispatches work"| node_scheduler
node_scheduler -.->|"uses cache"| node_cache
node_scheduler -.->|"selects service"| node_adapters
node_adapters -->|"creates services"| node_servicebase
node_adapters -.->|"sends requests"| node_translationproviders
node_controller -->|"renders translations"| node_renderer
node_options -->|"configures services"| node_background
node_popup -->|"controls translation"| node_background
node_background -->|"loads settings"| node_config
node_options -->|"edits site rules"| node_rules
node_oauth -->|"authenticates requests"| node_translationproviders
node_user -->|"opens PDF"| node_pdf
node_pdf -->|"renders pages"| node_pdfpage
node_user -->|"imports subtitles"| node_subtitlefile
node_user -->|"views video"| node_subtitle
node_user -->|"opens panel"| node_sidepanel
node_sidepanel -.->|"requests assistant"| node_assistant
node_user -->|"requests writing help"| node_aiwriting
node_user -->|"uses search"| node_search
node_user -->|"installs userscript"| node_userscript
node_userscript -->|"scans page text"| node_scanner

click node_content "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/index.ts"
click node_controller "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/controller/translation-controller.ts"
click node_scanner "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/extract/scanner.ts"
click node_placeholders "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/extract/placeholder.ts"
click node_renderer "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/render/inject.ts"
click node_background "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/index.ts"
click node_scheduler "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/scheduler.ts"
click node_rules "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/rules/match.ts"
click node_cache "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/cache.ts"
click node_servicebase "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/base.ts"
click node_adapters "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/index.ts"
click node_oauth "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/chatgpt-oauth/auth.ts"
click node_options "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/ui/options/index.tsx"
click node_popup "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/ui/popup/index.tsx"
click node_config "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/shared/config.ts"
click node_pdf "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/pdf/index.tsx"
click node_pdfpage "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/pdf/page.tsx"
click node_subtitle "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/features/subtitle/engine.ts"
click node_subtitlefile "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/subtitle-file/index.tsx"
click node_sidepanel "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/ui/sidepanel/index.tsx"
click node_assistant "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/assistant.ts"
click node_aiwriting "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/features/ai-writing/index.ts"
click node_search "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/features/search-enhancement.ts"
click node_userscript "https://github.com/ymcwiki/open-immersive-translate/blob/main/src/userscript/page.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_content,node_controller,node_scanner,node_placeholders,node_renderer,node_userscript,node_user toneBlue
class node_background,node_scheduler,node_rules,node_cache toneAmber
class node_servicebase,node_adapters,node_oauth,node_assistant toneMint
class node_pdf,node_pdfpage,node_subtitle,node_subtitlefile,node_sidepanel,node_aiwriting,node_search toneRose
class node_options,node_popup,node_config,node_webpage,node_translationproviders toneIndigo
```

## Components

### Webpage translation

- [Content entry](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/index.ts): `src/content/index.ts`
- [Translation controller](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/controller/translation-controller.ts): `src/content/controller/translation-controller.ts`
- [Text extraction](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/extract/scanner.ts): `src/content/extract/scanner.ts`
- [Rich-text placeholders](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/extract/placeholder.ts): `src/content/extract/placeholder.ts`
- [Page rendering](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/render/inject.ts): `src/content/render/inject.ts`
- [Userscript runtime](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/userscript/page.ts): `src/userscript/page.ts`

### Extension runtime

- [Background worker](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/index.ts): `src/background/index.ts`
- [Translation scheduler](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/scheduler.ts): `src/background/scheduler.ts`
- [Site rules](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/rules/match.ts): `src/background/rules/match.ts`
- [Translation cache](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/cache.ts): `src/background/cache.ts`

### Translation services

- [Service contract](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/base.ts): `src/background/services/base.ts`
- [Translation adapters](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/index.ts): `src/background/services/index.ts`
- [ChatGPT OAuth](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/chatgpt-oauth/auth.ts): `src/background/services/chatgpt-oauth/auth.ts`
- [Assistant service](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/background/services/assistant.ts): `src/background/services/assistant.ts`

### Other translation experiences

- [PDF reader and export](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/pdf/index.tsx): `src/pdf/index.tsx`
- [PDF page extraction](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/pdf/page.tsx): `src/pdf/page.tsx`
- [Video subtitles](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/features/subtitle/engine.ts): `src/content/features/subtitle/engine.ts`
- [Subtitle-file workflow](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/subtitle-file/index.tsx): `src/subtitle-file/index.tsx`
- [Assistant side panel](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/ui/sidepanel/index.tsx): `src/ui/sidepanel/index.tsx`
- [AI writing](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/features/ai-writing/index.ts): `src/content/features/ai-writing/index.ts`
- [Search enhancement](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/content/features/search-enhancement.ts): `src/content/features/search-enhancement.ts`

### Configuration and controls

- [Settings page](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/ui/options/index.tsx): `src/ui/options/index.tsx`
- [Popup controls](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/ui/popup/index.tsx): `src/ui/popup/index.tsx`
- [Shared configuration](https://github.com/ymcwiki/open-immersive-translate/blob/main/src/shared/config.ts): `src/shared/config.ts`

### Other components

- **Browser user**
- **Web page**
- **Translation providers**

## Connections

- Browser user → Web page: opens (evidence: `README.md`)
- Web page → Content entry: loads script (evidence: `README.md`)
- Content entry → Translation controller: starts translation
- Translation controller → Text extraction: scans text (evidence: `src/content/controller/translation-controller.ts`)
- Text extraction → Rich-text placeholders: preserves markup (evidence: `src/content/extract/scanner.ts`)
- Translation controller → Background worker: requests translation (evidence: `README.md`)
- Background worker → Site rules: matches site (evidence: `src/background/index.ts`)
- Background worker → Translation scheduler: dispatches work (evidence: `src/background/index.ts`)
- Translation scheduler → Translation cache: uses cache
- Translation scheduler → Translation adapters: selects service
- Translation adapters → Service contract: creates services (evidence: `src/background/services/index.ts`)
- Translation adapters → Translation providers: sends requests
- Translation controller → Page rendering: renders translations (evidence: `src/content/controller/translation-controller.ts`)
- Settings page → Background worker: configures services (evidence: `src/ui/options/index.tsx`)
- Popup controls → Background worker: controls translation (evidence: `README.md`)
- Background worker → Shared configuration: loads settings (evidence: `src/background/index.ts`)
- Settings page → Site rules: edits site rules (evidence: `src/ui/options/index.tsx`)
- ChatGPT OAuth → Translation providers: authenticates requests
- Browser user → PDF reader and export: opens PDF (evidence: `README.md`)
- PDF reader and export → PDF page extraction: renders pages (evidence: `src/pdf/index.tsx`)
- Browser user → Subtitle-file workflow: imports subtitles (evidence: `README.md`)
- Browser user → Video subtitles: views video (evidence: `README.md`)
- Browser user → Assistant side panel: opens panel (evidence: `README.md`)
- Assistant side panel → Assistant service: requests assistant
- Browser user → AI writing: requests writing help (evidence: `README.md`)
- Browser user → Search enhancement: uses search (evidence: `README.md`)
- Browser user → Userscript runtime: installs userscript (evidence: `README.md`)
- Userscript runtime → Text extraction: scans page text (evidence: `src/userscript/page.ts`)