# tsinghua-lau/transgo architecture

> Architecture diagram of the GitHub repository tsinghua-lau/transgo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsinghua-lau/transgo
- Repository: https://github.com/tsinghua-lau/transgo

## Overview

1. **Project type and runtime**
   - This is a **VS Code extension** written in **TypeScript** and running in the **extension host**.
   - The repo is structured around editor integration, a side-panel UI, and multiple external translation/TTS providers rather than a standalone app.

2. **Entry point and orchestration**
   - `src/extension.ts` is the central bootstrap file.
   - It likely wires up activation, command registration, hover support, panel creation, configuration loading, and service initialization.
   - This file is the main boundary between VS Code APIs and the internal translation/audio subsystems.

3. **Editor-facing interaction surfaces**
   - There are two primary user interaction paths:
     - `src/hoverProvider.ts`: provides **mouse-hover translation** inside the editor.
     - `src/translationPanel.ts`: provides the **right-side translation panel** for typing, viewing results, replacing text, and triggering speech.
   - These are the UI-facing adapters that consume shared services rather than talking to APIs directly.

4. **Translation service layer**
   - `src/translationService.ts` is the main translation abstraction.
   - It likely routes requests to different providers based on configuration: Google, Baidu, Youdao, Tencent, and AI-model-based providers.
   - This layer is the core “business logic” boundary: UI components send text in, provider-specific translated text comes back out.

5. **Provider-specific translation adapters**
   - The repo separates translation backends from the generic service:
     - Traditional translator support is handled through the shared translation service.
     - AI model compatibility is driven by configurable **Base URL**, **model name**, and **prompt**.
   - The README indicates support for OpenAI-compatible endpoints such as DeepSeek, Kimi, Claude, OpenRouter, Groq, Ollama, and others, so the architecture is intentionally provider-agnostic.

6. **Text post-processing**
   - `src/textFormatter.ts` appears to normalize or enhance translation output.
   - The README mentions camelCase / underscore name conversion, so this module likely handles formatting-related transforms after translation or on selected text.
   - This is a separate step from translation itself, which keeps output shaping out of the provider layer.

7. **Speech synthesis subsystem**
   - `src/ttsService.ts` is the abstraction for read-aloud behavior.
   - Provider implementations are split into:
     - `src/tencentTtsService.ts`
     - `src/volcanoTtsService.ts`
   - This mirrors the translation architecture: one shared interface, multiple vendor-specific adapters.

8. **Security and secret management**
   - `src/configManager.ts` is a key architectural component because it handles configuration and secrets.
   - The README states API keys are stored using **system-level encrypted storage** instead of plain `settings.json`.
   - `src/utils/crypto.ts` and `src/utils/md5.ts` support security-related operations, likely signing, hashing, or migration logic for provider auth.
   - This creates a clear boundary between non-sensitive settings in VS Code configuration and sensitive credentials in OS-backed secure storage.

9. **Logging and diagnostics**
   - `src/logger.ts` centralizes logging.
   - This is important in a multi-provider extension because failures can come from VS Code APIs, network requests, or provider auth/config issues.
   - The logger acts as the diagnostic boundary for extension-wide troubleshooting.

10. **Data flow from user action to result**
   - Typical flow:
     - user opens the panel, hovers text, or runs a command;
     - `extension.ts` dispatches to `translationPanel.ts` or `hoverProvider.ts`;
     - these call `translationService.ts`;
     - the service reads config via `configManager.ts`;
     - a provider-specific request is made to an external translation API;
     - the translated text is optionally formatted by `textFormatter.ts`;
     - results are shown in the panel or hover tooltip, and may also drive replacement actions.

11. **Data flow for speech**
   - Speech follows a parallel path:
     - the panel or command triggers `ttsService.ts`;
     - the selected implementation (`tencentTtsService.ts` or `volcanoTtsService.ts`) sends text to the configured vendor;
     - audio is returned and played inside VS Code.
   - The README emphasizes language-aware voice selection, so the TTS layer must account for text language and voice compatibility.

12. **Repository boundaries and architecture style**
   - The codebase is organized as a **service-oriented extension**:
     - UI adapters on one side,
     - shared services in the middle,
     - provider-specific integrations on the other side.
   - External dependencies are primarily **translation APIs**, **TTS APIs**, and **OS secure storage**, all mediated through internal abstractions.
   - The `utils` folder contains low-level support code, while `src/images` holds UI assets for the extension experience.

13. **Key diagram takeaway**
   - The most important architectural boxes to draw are:
     - VS Code extension host,
     - editor interactions (hover, commands, panel),
     - translation service,
     - TTS service,
     - config/secret storage,
     - provider adapters for translation and speech,
     - external API endpoints.
   - The clean separation between UI, configuration, and provider adapters is the defining structure of this repo.

Main entry points: [`src/translationService.ts`](https://github.com/tsinghua-lau/transgo/blob/master/src/translationService.ts) (Translator), [`src/ttsService.ts`](https://github.com/tsinghua-lau/transgo/blob/master/src/ttsService.ts) (TTS core), [`src/extension.ts`](https://github.com/tsinghua-lau/transgo/blob/master/src/extension.ts) (Extension), [`src/translationPanel.ts`](https://github.com/tsinghua-lau/transgo/blob/master/src/translationPanel.ts) (Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["VS Code extension"]
  node_extension(("Extension<br/>bootstrap<br/>[extension.ts]"))
  node_hover["Hover<br/>editor UI<br/>[hoverProvider.ts]"]
  node_panel["Panel"]
end

subgraph group_g2["Core services"]
  node_translation["Translator"]
  node_tts["TTS core<br/>[ttsService.ts]"]
  node_config[("Config<br/>settings+secrets<br/>[configManager.ts]")]
  node_format["Formatter<br/>post-process<br/>[textFormatter.ts]"]
  node_logger["Logger<br/>diagnostics<br/>[logger.ts]"]
  node_crypto["Crypto<br/>security util<br/>[crypto.ts]"]
  node_md5["MD5<br/>hash util<br/>[md5.ts]"]
end

subgraph group_g3["Providers and externals"]
  node_tencent["Tencent TTS<br/>tts adapter"]
  node_volcano["Volcano TTS<br/>tts adapter"]
  node_google["Google<br/>translation provider"]
  node_baidu["Baidu<br/>translation provider"]
  node_youdao["Youdao<br/>translation provider"]
  node_tencent_tr["Tencent Translate<br/>translation provider"]
  node_ai_providers["AI endpoints<br/>openai-compatible translation"]
  node_vscode(("VS Code API<br/>runtime"))
  node_secure_storage[("Secure storage<br/>os secret store")]
  node_external_api["External APIs<br/>network services"]
end

node_extension -->|"registers"| node_vscode
node_extension -->|"creates"| node_hover
node_extension -->|"opens"| node_panel
node_extension -->|"wires"| node_translation
node_extension -->|"wires"| node_tts
node_hover -->|"requests"| node_translation
node_panel -->|"requests"| node_translation
node_panel -->|"plays"| node_tts
node_panel -->|"formats"| node_format
node_translation -->|"reads"| node_config
node_tts -->|"reads"| node_config
node_translation -->|"post-processes"| node_format
node_translation -->|"routes to"| node_google
node_translation -->|"routes to"| node_baidu
node_translation -->|"routes to"| node_youdao
node_translation -->|"routes to"| node_tencent_tr
node_translation -->|"routes to"| node_ai_providers
node_tts -->|"selects"| node_tencent
node_tts -->|"selects"| node_volcano
node_config -->|"stores secrets"| node_secure_storage
node_config -->|"uses"| node_crypto
node_crypto -->|"depends on"| node_md5
node_translation -->|"calls"| node_external_api
node_tts -->|"calls"| node_external_api
node_logger -.->|"observes"| node_extension
node_logger -.->|"observes"| node_translation
node_logger -.->|"observes"| node_tts

click node_extension "https://github.com/tsinghua-lau/transgo/blob/master/src/extension.ts"
click node_hover "https://github.com/tsinghua-lau/transgo/blob/master/src/hoverProvider.ts"
click node_panel "https://github.com/tsinghua-lau/transgo/blob/master/src/translationPanel.ts"
click node_translation "https://github.com/tsinghua-lau/transgo/blob/master/src/translationService.ts"
click node_tts "https://github.com/tsinghua-lau/transgo/blob/master/src/ttsService.ts"
click node_config "https://github.com/tsinghua-lau/transgo/blob/master/src/configManager.ts"
click node_format "https://github.com/tsinghua-lau/transgo/blob/master/src/textFormatter.ts"
click node_logger "https://github.com/tsinghua-lau/transgo/blob/master/src/logger.ts"
click node_crypto "https://github.com/tsinghua-lau/transgo/blob/master/src/utils/crypto.ts"
click node_md5 "https://github.com/tsinghua-lau/transgo/blob/master/src/utils/md5.ts"
click node_tencent "https://github.com/tsinghua-lau/transgo/blob/master/src/tencentTtsService.ts"
click node_volcano "https://github.com/tsinghua-lau/transgo/blob/master/src/volcanoTtsService.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_extension,node_hover,node_panel toneBlue
class node_translation,node_tts,node_config,node_format,node_logger,node_crypto,node_md5 toneAmber
class node_tencent,node_volcano,node_google,node_baidu,node_youdao,node_tencent_tr,node_ai_providers,node_vscode,node_secure_storage,node_external_api toneMint
```

## Components

### VS Code extension

Extension-host entrypoints and editor-facing surfaces

- [Extension](https://github.com/tsinghua-lau/transgo/blob/master/src/extension.ts): bootstrap · Activates the extension and wires commands, providers, and services. · `src/extension.ts`
- [Hover](https://github.com/tsinghua-lau/transgo/blob/master/src/hoverProvider.ts): editor UI · Provides hover-based translation inside the editor. · `src/hoverProvider.ts`
- [Panel](https://github.com/tsinghua-lau/transgo/blob/master/src/translationPanel.ts): side panel · Hosts the translation UI, replace actions, and speech triggers. · `src/translationPanel.ts`

### Core services

Shared orchestration, config, formatting, and support code

- [Translator](https://github.com/tsinghua-lau/transgo/blob/master/src/translationService.ts): service · Routes translation requests to the configured backend provider. · `src/translationService.ts`
- [TTS core](https://github.com/tsinghua-lau/transgo/blob/master/src/ttsService.ts): service · Abstraction for text-to-speech playback and provider selection. · `src/ttsService.ts`
- [Config](https://github.com/tsinghua-lau/transgo/blob/master/src/configManager.ts): settings+secrets · Loads settings and manages secure credential storage. · `src/configManager.ts`
- [Formatter](https://github.com/tsinghua-lau/transgo/blob/master/src/textFormatter.ts): post-process · Normalizes and reshapes translated text output. · `src/textFormatter.ts`
- [Logger](https://github.com/tsinghua-lau/transgo/blob/master/src/logger.ts): diagnostics · Central logging and troubleshooting boundary. · `src/logger.ts`
- [Crypto](https://github.com/tsinghua-lau/transgo/blob/master/src/utils/crypto.ts): security util · Supports secret handling and authentication-related operations. · `src/utils/crypto.ts`
- [MD5](https://github.com/tsinghua-lau/transgo/blob/master/src/utils/md5.ts): hash util · Hash helper used by security or provider-auth flows. · `src/utils/md5.ts`

### Providers and externals

Vendor adapters and external systems the extension talks to

- [Tencent TTS](https://github.com/tsinghua-lau/transgo/blob/master/src/tencentTtsService.ts): tts adapter · Vendor-specific text-to-speech implementation. · `src/tencentTtsService.ts`
- [Volcano TTS](https://github.com/tsinghua-lau/transgo/blob/master/src/volcanoTtsService.ts): tts adapter · Vendor-specific text-to-speech implementation. · `src/volcanoTtsService.ts`
- **Google**: translation provider · Traditional translation backend referenced by the shared translator.
- **Baidu**: translation provider · Traditional translation backend referenced by the shared translator.
- **Youdao**: translation provider · Traditional translation backend referenced by the shared translator.
- **Tencent Translate**: translation provider · Traditional translation backend referenced by the shared translator.
- **AI endpoints**: openai-compatible translation · OpenAI-compatible translation backends configured by base URL, model, and prompt.
- **VS Code API**: runtime · Extension host runtime and editor integration surface.
- **Secure storage**: os secret store · System-level encrypted storage for API keys and secrets.
- **External APIs**: network services · Remote translation and speech services.

## Connections

- Extension → VS Code API: registers · Hooks into activation, commands, and providers.
- Extension → Hover: creates · Installs the hover translation provider.
- Extension → Panel: opens · Creates and manages the translation panel.
- Extension → Translator: wires · Injects the shared translation service.
- Extension → TTS core: wires · Injects the shared speech service.
- Hover → Translator: requests · Translates hovered text through the service layer.
- Panel → Translator: requests · Translates typed or selected text.
- Panel → TTS core: plays · Triggers speech playback from the panel.
- Panel → Formatter: formats · Applies output shaping before display or replacement.
- Translator → Config: reads · Uses settings and provider credentials.
- TTS core → Config: reads · Uses speech provider settings and credentials.
- Translator → Formatter: post-processes · Normalizes translated text before returning results.
- Translator → Google: routes to · Can call Google translation backend.
- Translator → Baidu: routes to · Can call Baidu translation backend.
- Translator → Youdao: routes to · Can call Youdao translation backend.
- Translator → Tencent Translate: routes to · Can call Tencent translation backend.
- Translator → AI endpoints: routes to · Can call OpenAI-compatible model endpoints.
- TTS core → Tencent TTS: selects · Uses Tencent speech synthesis implementation.
- TTS core → Volcano TTS: selects · Uses Volcano speech synthesis implementation.
- Config → Secure storage: stores secrets · Persists API keys in encrypted OS-backed storage.
- Config → Crypto: uses · Relies on crypto helpers for secret handling.
- Crypto → MD5: depends on · Uses hashing helper for auth or migration logic.
- Translator → External APIs: calls · Sends requests to remote translation services.
- TTS core → External APIs: calls · Sends requests to remote TTS services.
- Logger → Extension: observes · Records extension lifecycle and runtime issues.
- Logger → Translator: observes · Logs translation failures and provider behavior.
- Logger → TTS core: observes · Logs speech synthesis failures and provider behavior.