# rockbenben/subtitle-translator architecture

> Architecture diagram of the GitHub repository rockbenben/subtitle-translator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rockbenben/subtitle-translator
- Repository: https://github.com/rockbenben/subtitle-translator

## Overview

Subtitle Translator is a browser-based batch subtitle translation product, with a CLI also documented as using the same engine. The main web flow accepts subtitle files, manages translation settings and state, translates dialogue through configured services, and presents and exports results. README-documented format conversion, bilingual output, glossary/context controls, multi-language runs, and local caching are preserved as capability branches. The translation implementation directory is absent from the supplied tree, so its internal stages are represented only at the enclosing `src/app/lib` path; API-route wiring is uncertain.

Main entry points: [`src/app/[locale]/SubtitleTranslator.tsx`](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/SubtitleTranslator.tsx) (Subtitle workspace), [`src/app/hooks/useTranslationState.tsx`](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useTranslationState.tsx) (Translation state), [`src/app/lib`](https://github.com/rockbenben/subtitle-translator/tree/main/src/app/lib) (Translation engine), [`src/app/[locale]/client.tsx`](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/client.tsx) (Tool page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_client["Tool page<br/>[client.tsx]"]
  node_translator["Subtitle workspace"]
  node_upload["File upload<br/>[useFileUpload.ts]"]
  node_results["Live results"]
  node_review["Bilingual review"]
  node_export["File export<br/>[useFileExport.ts]"]
end

subgraph group_translate["Translation workflow"]
  node_state["Translation state"]
  node_progress["Run progress"]
  node_engine["Translation engine"]
  node_formats["Subtitle formats<br/>[subtitleCues.ts]"]
  node_glossary["Glossary controls"]
  node_context["Context controls"]
end

subgraph group_prefs["Settings and persistence"]
  node_settings["API settings"]
  node_languages["Language selection"]
  node_presets["Translation presets"]
  node_preferences["Browser preferences<br/>[useLocalStorage.ts]"]
  node_cache[("Translation cache")]
end

subgraph group_integrations["Translation services"]
  node_mt{{"Translation providers"}}
  node_deepl["DeepL relay route<br/>[route.ts]"]
  node_nvidia["Nvidia relay route<br/>[route.ts]"]
end

node_user(("Subtitle user"))

node_user -->|"opens tool"| node_client
node_client -->|"renders"| node_translator
node_translator -->|"accepts files"| node_upload
node_translator -->|"uses state"| node_state
node_state -->|"runs translation"| node_engine
node_engine -->|"requests translation"| node_mt
node_state -->|"tracks run"| node_progress
node_translator -->|"shows results"| node_results
node_translator -->|"offers review"| node_review
node_review -->|"exports output"| node_export
node_translator -->|"supports formats"| node_formats
node_engine -->|"converts formats"| node_formats
node_state -->|"reads and writes"| node_cache
node_translator -->|"configures service"| node_settings
node_translator -->|"chooses languages"| node_languages
node_settings -.->|"manages presets"| node_presets
node_state -->|"persists settings"| node_preferences
node_translator -.->|"offers glossary"| node_glossary
node_translator -->|"offers context"| node_context
node_mt -.->|"may relay"| node_deepl
node_mt -.->|"may relay"| node_nvidia

click node_client "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/client.tsx"
click node_translator "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/SubtitleTranslator.tsx"
click node_upload "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useFileUpload.ts"
click node_results "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/LiveTranslationResults.tsx"
click node_review "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/BilingualReviewPanel.tsx"
click node_export "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useFileExport.ts"
click node_state "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useTranslationState.tsx"
click node_progress "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useTranslationProgress.ts"
click node_engine "https://github.com/rockbenben/subtitle-translator/tree/main/src/app/lib"
click node_formats "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/subtitleCues.ts"
click node_glossary "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/glossaryManager/GlossaryManager.tsx"
click node_context "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/ContextTranslationBlock.tsx"
click node_settings "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/TranslationSettings.tsx"
click node_languages "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/LanguageSelector.tsx"
click node_presets "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/usePresetCollection.ts"
click node_preferences "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useLocalStorage.ts"
click node_cache "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/lib/storage/indexedDBStorage.ts"
click node_deepl "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/api/deepl/route.ts"
click node_nvidia "https://github.com/rockbenben/subtitle-translator/blob/main/src/app/api/nvidia/route.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_client,node_translator,node_upload,node_results,node_review,node_export,node_user toneBlue
class node_state,node_progress,node_engine,node_formats,node_glossary,node_context toneAmber
class node_settings,node_languages,node_presets,node_preferences,node_cache toneMint
class node_mt,node_deepl,node_nvidia toneRose
```

## Components

### Web experience

- [Tool page](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/client.tsx): `src/app/[locale]/client.tsx`
- [Subtitle workspace](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/SubtitleTranslator.tsx): `src/app/[locale]/SubtitleTranslator.tsx`
- [File upload](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useFileUpload.ts): `src/app/hooks/useFileUpload.ts`
- [Live results](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/LiveTranslationResults.tsx): `src/app/[locale]/LiveTranslationResults.tsx`
- [Bilingual review](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/BilingualReviewPanel.tsx): `src/app/[locale]/BilingualReviewPanel.tsx`
- [File export](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useFileExport.ts): `src/app/hooks/useFileExport.ts`

### Translation workflow

- [Translation state](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useTranslationState.tsx): `src/app/hooks/useTranslationState.tsx`
- [Run progress](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useTranslationProgress.ts): `src/app/hooks/useTranslationProgress.ts`
- [Translation engine](https://github.com/rockbenben/subtitle-translator/tree/main/src/app/lib): `src/app/lib`
- [Subtitle formats](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/%5Blocale%5D/subtitleCues.ts): `src/app/[locale]/subtitleCues.ts`
- [Glossary controls](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/glossaryManager/GlossaryManager.tsx): `src/app/components/glossaryManager/GlossaryManager.tsx`
- [Context controls](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/ContextTranslationBlock.tsx): `src/app/components/ContextTranslationBlock.tsx`

### Settings and persistence

- [API settings](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/TranslationSettings.tsx): `src/app/components/TranslationSettings.tsx`
- [Language selection](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/components/LanguageSelector.tsx): `src/app/components/LanguageSelector.tsx`
- [Translation presets](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/usePresetCollection.ts): `src/app/hooks/usePresetCollection.ts`
- [Browser preferences](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/hooks/useLocalStorage.ts): `src/app/hooks/useLocalStorage.ts`
- [Translation cache](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/lib/storage/indexedDBStorage.ts): `src/app/lib/storage/indexedDBStorage.ts`

### Translation services

- **Translation providers**
- [DeepL relay route](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/api/deepl/route.ts): `src/app/api/deepl/route.ts`
- [Nvidia relay route](https://github.com/rockbenben/subtitle-translator/blob/main/src/app/api/nvidia/route.ts): `src/app/api/nvidia/route.ts`

### Other components

- **Subtitle user**

## Connections

- Subtitle user → Tool page: opens tool
- Tool page → Subtitle workspace: renders (evidence: `src/app/[locale]/client.tsx`)
- Subtitle workspace → File upload: accepts files (evidence: `src/app/[locale]/SubtitleTranslator.tsx`)
- Subtitle workspace → Translation state: uses state (evidence: `src/app/[locale]/SubtitleTranslator.tsx`)
- Translation state → Translation engine: runs translation (evidence: `src/app/hooks/useTranslationState.tsx`)
- Translation engine → Translation providers: requests translation
- Translation state → Run progress: tracks run (evidence: `src/app/hooks/useTranslationState.tsx`)
- Subtitle workspace → Live results: shows results (evidence: `src/app/[locale]/SubtitleTranslator.tsx`)
- Subtitle workspace → Bilingual review: offers review (evidence: `src/app/[locale]/SubtitleTranslator.tsx`)
- Bilingual review → File export: exports output (evidence: `src/app/[locale]/BilingualReviewPanel.tsx`)
- Subtitle workspace → Subtitle formats: supports formats
- Translation engine → Subtitle formats: converts formats (evidence: `src/app/[locale]/subtitleCues.ts`)
- Translation state → Translation cache: reads and writes (evidence: `src/app/hooks/useTranslationState.tsx`)
- Subtitle workspace → API settings: configures service
- Subtitle workspace → Language selection: chooses languages (evidence: `src/app/[locale]/SubtitleTranslator.tsx`)
- API settings → Translation presets: manages presets
- Translation state → Browser preferences: persists settings (evidence: `src/app/hooks/useTranslationState.tsx`)
- Subtitle workspace → Glossary controls: offers glossary
- Subtitle workspace → Context controls: offers context (evidence: `src/app/[locale]/SubtitleTranslator.tsx`)
- Translation providers → DeepL relay route: may relay
- Translation providers → Nvidia relay route: may relay
