How tsinghua-lau/transgo works
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: translationService.ts Translator · ttsService.ts TTS core · extension.ts Extension · translationPanel.ts Panel
Components 20
VS Code extension
Extension-host entrypoints and editor-facing surfaces
Core services
Shared orchestration, config, formatting, and support code
- Translator · Routes translation requests to the configured backend provider.
src/translationService.ts - TTS core · Abstraction for text-to-speech playback and provider selection.
src/ttsService.ts - Config · Loads settings and manages secure credential storage.
src/configManager.ts - Formatter · Normalizes and reshapes translated text output.
src/textFormatter.ts - Logger · Central logging and troubleshooting boundary.
src/logger.ts - Crypto · Supports secret handling and authentication-related operations.
src/utils/crypto.ts - MD5 · 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 · Vendor-specific text-to-speech implementation.
src/tencentTtsService.ts - Volcano TTS · Vendor-specific text-to-speech implementation.
src/volcanoTtsService.ts - Google · Traditional translation backend referenced by the shared translator.
- Baidu · Traditional translation backend referenced by the shared translator.
- Youdao · Traditional translation backend referenced by the shared translator.
- Tencent Translate · Traditional translation backend referenced by the shared translator.
- AI endpoints · OpenAI-compatible translation backends configured by base URL, model, and prompt.
- VS Code API · Extension host runtime and editor integration surface.
- Secure storage · System-level encrypted storage for API keys and secrets.
- External APIs · Remote translation and speech services.
Connections 27
- 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.