# deepl/deepl-cli architecture

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

- Interactive diagram: https://gitdiagram.com/deepl/deepl-cli
- Repository: https://github.com/deepl/deepl-cli

## Overview

DeepL CLI takes user commands and local text or localization files, then returns translations, writing improvements, or localization updates. The main translation path runs from CLI handlers through services and API clients to DeepL; the separate sync workflow parses and compares project files, coordinates translation and glossary support, and writes updated files. The README documents additional capabilities whose wiring is not fully visible in the sampled source; those branches are represented without asserting unsampled internal call chains.

Main entry points: [`src/cli/index.ts`](https://github.com/deepl/deepl-cli/blob/main/src/cli/index.ts) (CLI entry), [`src/sync/sync-service.ts`](https://github.com/deepl/deepl-cli/blob/main/src/sync/sync-service.ts) (Sync service), [`src/services/translation.ts`](https://github.com/deepl/deepl-cli/blob/main/src/services/translation.ts) (Translation service), [`src/api/deepl-client.ts`](https://github.com/deepl/deepl-cli/blob/main/src/api/deepl-client.ts) (DeepL client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and setup"]
  node_cli["CLI entry<br/>[index.ts]"]
  node_factory["Service factory<br/>[service-factory.ts]"]
end

subgraph group_translation["Translation workflows"]
  node_translate_cmd["Translate command<br/>[translate.ts]"]
  node_text_handler["Text handler"]
  node_file_handler["File handler"]
  node_translation_service["Translation service<br/>[translation.ts]"]
  node_document_service["Document service"]
end

subgraph group_localization["Localization sync"]
  node_formats["Format registry<br/>[index.ts]"]
  node_sync_cmd["Sync command<br/>[sync-command.ts]"]
  node_sync_service["Sync service<br/>[sync-service.ts]"]
  node_sync_tms["TMS client<br/>[tms-client.ts]"]
end

subgraph group_capabilities["Additional capabilities"]
  node_watch_service["Watch service<br/>[watch.ts]"]
  node_write_service["Write service<br/>[write.ts]"]
  node_voice_service["Voice service<br/>[voice.ts]"]
  node_voice_session["Voice stream session"]
  node_glossary_service["Glossary service<br/>[glossary.ts]"]
  node_tm_service["Translation memory"]
end

subgraph group_runtime["Runtime services"]
  node_deepl["DeepL client<br/>[deepl-client.ts]"]
  node_translation_api["Translation API client"]
  node_http["HTTP client<br/>[http-client.ts]"]
  node_cache[("Local cache<br/>[cache.ts]")]
  node_config[("Configuration<br/>[config.ts]")]
end

node_user(("CLI user"))
node_local_files["Project files"]
node_deepl_api{{"DeepL API"}}
node_voice_api{{"Voice API"}}
node_tms_server{{"TMS server"}}

node_user -->|"runs command"| node_cli
node_cli -->|"reads settings"| node_config
node_cli -->|"creates services"| node_factory
node_factory -->|"creates"| node_translation_service
node_factory -->|"creates"| node_document_service
node_cli -->|"dispatches"| node_translate_cmd
node_translate_cmd -->|"handles text"| node_text_handler
node_translate_cmd -->|"handles files"| node_file_handler
node_text_handler -->|"requests translation"| node_translation_service
node_file_handler -->|"requests translation"| node_translation_service
node_file_handler -->|"uses document API"| node_document_service
node_translation_service -->|"calls"| node_deepl
node_document_service -->|"calls"| node_deepl
node_deepl -->|"delegates translation"| node_translation_api
node_translation_api -->|"sends requests"| node_http
node_http -->|"HTTP requests"| node_deepl_api
node_cli -->|"dispatches"| node_sync_cmd
node_sync_cmd -->|"runs sync"| node_sync_service
node_sync_service -->|"scans and updates"| node_local_files
node_sync_service -->|"uses parsers"| node_formats
node_sync_service -->|"requests translations"| node_translation_service
node_sync_service -->|"resolves glossary"| node_glossary_service
node_sync_service -->|"resolves memory"| node_tm_service
node_sync_service -.->|"uses TMS"| node_sync_tms
node_sync_tms -.->|"exchanges data"| node_tms_server
node_cli -->|"dispatches watch"| node_watch_service
node_watch_service -->|"auto-translates"| node_translation_service
node_cli -->|"dispatches writing"| node_write_service
node_write_service -->|"calls"| node_deepl
node_cli -->|"dispatches voice"| node_voice_service
node_voice_service -->|"manages stream"| node_voice_session
node_voice_session -->|"streams audio"| node_voice_api
node_cli -->|"dispatches glossary"| node_glossary_service
node_glossary_service -->|"calls"| node_deepl
node_cli -->|"dispatches memory"| node_tm_service
node_tm_service -->|"calls"| node_deepl
node_translation_service -->|"uses cache"| node_cache

click node_cli "https://github.com/deepl/deepl-cli/blob/main/src/cli/index.ts"
click node_factory "https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/service-factory.ts"
click node_translate_cmd "https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/translate.ts"
click node_text_handler "https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/translate/text-translation-handler.ts"
click node_file_handler "https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/translate/file-translation-handler.ts"
click node_translation_service "https://github.com/deepl/deepl-cli/blob/main/src/services/translation.ts"
click node_document_service "https://github.com/deepl/deepl-cli/blob/main/src/services/document-translation.ts"
click node_formats "https://github.com/deepl/deepl-cli/blob/main/src/formats/index.ts"
click node_sync_cmd "https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/sync-command.ts"
click node_sync_service "https://github.com/deepl/deepl-cli/blob/main/src/sync/sync-service.ts"
click node_sync_tms "https://github.com/deepl/deepl-cli/blob/main/src/sync/tms-client.ts"
click node_watch_service "https://github.com/deepl/deepl-cli/blob/main/src/services/watch.ts"
click node_write_service "https://github.com/deepl/deepl-cli/blob/main/src/services/write.ts"
click node_voice_service "https://github.com/deepl/deepl-cli/blob/main/src/services/voice.ts"
click node_voice_session "https://github.com/deepl/deepl-cli/blob/main/src/services/voice-stream-session.ts"
click node_glossary_service "https://github.com/deepl/deepl-cli/blob/main/src/services/glossary.ts"
click node_tm_service "https://github.com/deepl/deepl-cli/blob/main/src/services/translation-memory.ts"
click node_deepl "https://github.com/deepl/deepl-cli/blob/main/src/api/deepl-client.ts"
click node_translation_api "https://github.com/deepl/deepl-cli/blob/main/src/api/translation-client.ts"
click node_http "https://github.com/deepl/deepl-cli/blob/main/src/api/http-client.ts"
click node_cache "https://github.com/deepl/deepl-cli/blob/main/src/storage/cache.ts"
click node_config "https://github.com/deepl/deepl-cli/blob/main/src/storage/config.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_cli,node_factory,node_user toneBlue
class node_translate_cmd,node_text_handler,node_file_handler,node_translation_service,node_document_service toneAmber
class node_formats,node_sync_cmd,node_sync_service,node_sync_tms,node_deepl_api,node_voice_api,node_tms_server toneMint
class node_watch_service,node_write_service,node_voice_service,node_voice_session,node_glossary_service,node_tm_service toneRose
class node_deepl,node_translation_api,node_http,node_cache,node_config,node_local_files toneIndigo
```

## Components

### CLI and setup

- [CLI entry](https://github.com/deepl/deepl-cli/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [Service factory](https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/service-factory.ts): `src/cli/commands/service-factory.ts`

### Translation workflows

- [Translate command](https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/translate.ts): `src/cli/commands/translate.ts`
- [Text handler](https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/translate/text-translation-handler.ts): `src/cli/commands/translate/text-translation-handler.ts`
- [File handler](https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/translate/file-translation-handler.ts): `src/cli/commands/translate/file-translation-handler.ts`
- [Translation service](https://github.com/deepl/deepl-cli/blob/main/src/services/translation.ts): `src/services/translation.ts`
- [Document service](https://github.com/deepl/deepl-cli/blob/main/src/services/document-translation.ts): `src/services/document-translation.ts`

### Localization sync

- [Format registry](https://github.com/deepl/deepl-cli/blob/main/src/formats/index.ts): `src/formats/index.ts`
- [Sync command](https://github.com/deepl/deepl-cli/blob/main/src/cli/commands/sync-command.ts): `src/cli/commands/sync-command.ts`
- [Sync service](https://github.com/deepl/deepl-cli/blob/main/src/sync/sync-service.ts): `src/sync/sync-service.ts`
- [TMS client](https://github.com/deepl/deepl-cli/blob/main/src/sync/tms-client.ts): `src/sync/tms-client.ts`

### Additional capabilities

- [Watch service](https://github.com/deepl/deepl-cli/blob/main/src/services/watch.ts): `src/services/watch.ts`
- [Write service](https://github.com/deepl/deepl-cli/blob/main/src/services/write.ts): `src/services/write.ts`
- [Voice service](https://github.com/deepl/deepl-cli/blob/main/src/services/voice.ts): `src/services/voice.ts`
- [Voice stream session](https://github.com/deepl/deepl-cli/blob/main/src/services/voice-stream-session.ts): `src/services/voice-stream-session.ts`
- [Glossary service](https://github.com/deepl/deepl-cli/blob/main/src/services/glossary.ts): `src/services/glossary.ts`
- [Translation memory](https://github.com/deepl/deepl-cli/blob/main/src/services/translation-memory.ts): `src/services/translation-memory.ts`

### Runtime services

- [DeepL client](https://github.com/deepl/deepl-cli/blob/main/src/api/deepl-client.ts): `src/api/deepl-client.ts`
- [Translation API client](https://github.com/deepl/deepl-cli/blob/main/src/api/translation-client.ts): `src/api/translation-client.ts`
- [HTTP client](https://github.com/deepl/deepl-cli/blob/main/src/api/http-client.ts): `src/api/http-client.ts`
- [Local cache](https://github.com/deepl/deepl-cli/blob/main/src/storage/cache.ts): `src/storage/cache.ts`
- [Configuration](https://github.com/deepl/deepl-cli/blob/main/src/storage/config.ts): `src/storage/config.ts`

### Other components

- **CLI user**
- **Project files**
- **DeepL API**
- **Voice API**
- **TMS server**

## Connections

- CLI user → CLI entry: runs command
- CLI entry → Configuration: reads settings
- CLI entry → Service factory: creates services
- Service factory → Translation service: creates
- Service factory → Document service: creates
- CLI entry → Translate command: dispatches
- Translate command → Text handler: handles text
- Translate command → File handler: handles files
- Text handler → Translation service: requests translation
- File handler → Translation service: requests translation
- File handler → Document service: uses document API
- Translation service → DeepL client: calls
- Document service → DeepL client: calls
- DeepL client → Translation API client: delegates translation
- Translation API client → HTTP client: sends requests
- HTTP client → DeepL API: HTTP requests
- CLI entry → Sync command: dispatches
- Sync command → Sync service: runs sync
- Sync service → Project files: scans and updates
- Sync service → Format registry: uses parsers
- Sync service → Translation service: requests translations
- Sync service → Glossary service: resolves glossary
- Sync service → Translation memory: resolves memory
- Sync service → TMS client: uses TMS
- TMS client → TMS server: exchanges data
- CLI entry → Watch service: dispatches watch
- Watch service → Translation service: auto-translates
- CLI entry → Write service: dispatches writing
- Write service → DeepL client: calls
- CLI entry → Voice service: dispatches voice
- Voice service → Voice stream session: manages stream
- Voice stream session → Voice API: streams audio
- CLI entry → Glossary service: dispatches glossary
- Glossary service → DeepL client: calls
- CLI entry → Translation memory: dispatches memory
- Translation memory → DeepL client: calls
- Translation service → Local cache: uses cache