From db84b28e0b7a9d23200479cf44c7c11a85cd093f Mon Sep 17 00:00:00 2001 From: Ming Gong Date: Fri, 13 Mar 2026 07:59:40 -0400 Subject: [PATCH 1/3] Add DeepL CLI documentation to Getting Started Group client libraries and CLI under a new "Developer Tools" nav section, add a dedicated CLI page with installation, quick start, and capabilities, and cross-reference from the client libraries page. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs.json | 12 +- docs/getting-started/client-libraries.mdx | 4 + docs/getting-started/deepl-cli.mdx | 134 ++++++++++++++++++++++ 3 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started/deepl-cli.mdx diff --git a/docs.json b/docs.json index 625264cf..b2b0def2 100644 --- a/docs.json +++ b/docs.json @@ -41,7 +41,13 @@ "docs/getting-started/about", "docs/getting-started/auth", "docs/getting-started/regional-endpoints", - "docs/getting-started/client-libraries", + { + "group": "Developer Tools", + "pages": [ + "docs/getting-started/client-libraries", + "docs/getting-started/deepl-cli" + ] + }, "docs/getting-started/managing-api-keys", "docs/getting-started/your-first-api-request", "docs/getting-started/test-your-api-requests-with-postman", @@ -393,6 +399,10 @@ "source": "/api-reference/client-libraries", "destination": "/docs/getting-started/client-libraries" }, + { + "source": "/docs/cli", + "destination": "/docs/getting-started/deepl-cli" + }, { "source": "/docs/resources/release-notes/rss.xml", "destination": "/docs/resources/roadmap-and-release-notes/rss.xml" diff --git a/docs/getting-started/client-libraries.mdx b/docs/getting-started/client-libraries.mdx index ce8acb6e..37bf7411 100644 --- a/docs/getting-started/client-libraries.mdx +++ b/docs/getting-started/client-libraries.mdx @@ -35,6 +35,10 @@ Features include: All officially supported client libraries are open-source under the MIT License. We welcome feedback in the form of issues and pull requests! +## Command-line interface + +For terminal-based workflows, scripting, and CI/CD pipelines, see the [DeepL CLI](/docs/getting-started/deepl-cli). + ## Community-created client libraries The DeepL community [maintains client libraries](https://github.com/DeepLcom/awesome-deepl?tab=readme-ov-file#community-libraries--sdks) for other languages, including [Dart](https://github.com/komape/deepl_dart), [Go](https://github.com/candy12t/go-deepl), [Rust](https://github.com/Avimitin/deepl-rs), and [Kotlin](https://github.com/SimplyMika/DeeplKt). diff --git a/docs/getting-started/deepl-cli.mdx b/docs/getting-started/deepl-cli.mdx new file mode 100644 index 00000000..39108ae8 --- /dev/null +++ b/docs/getting-started/deepl-cli.mdx @@ -0,0 +1,134 @@ +--- +title: "DeepL CLI" +public: true +--- + +The [DeepL CLI](https://github.com/DeepLcom/deepl-cli) is an open-source (MIT license) command-line tool for interacting with the DeepL API. It covers text translation, document translation, writing enhancement, voice translation, glossary management, and admin operations — all from your terminal. + + +The DeepL CLI is open-source under the [MIT License](https://github.com/DeepLcom/deepl-cli/blob/main/LICENSE). Contributions and feedback are welcome! + + +## Installation + +### From npm (coming soon) + +```bash +npm install -g deepl-cli +``` + +### From source + +```bash +git clone https://github.com/DeepLcom/deepl-cli.git +cd deepl-cli +npm install +npm run build +npm link + +deepl --version +``` + + +The CLI uses `better-sqlite3` for local caching, which requires native compilation. Ensure you have build tools installed: +- **macOS**: Xcode Command Line Tools (`xcode-select --install`) +- **Linux**: `python3`, `make`, `gcc` (`apt install python3 make gcc g++`) +- **Windows**: Visual Studio Build Tools + + +## Quick start + +### 1. Set up authentication + +Use the interactive setup wizard: + +```bash +deepl init +``` + +Or set your API key directly: + +```bash +deepl auth set-key YOUR_API_KEY +``` + +Or use an environment variable: + +```bash +export DEEPL_API_KEY=YOUR_API_KEY +``` + +### 2. Translate text + +```bash +deepl translate "Hello, world!" --to es +# ¡Hola, mundo! +``` + +### 3. Enhance your writing + +```bash +deepl write "Their going to the stor tommorow" --lang en-us +# They're going to the store tomorrow. +``` + +## Key capabilities + +| Command | Description | +|---------|-------------| +| `deepl translate` | Translate text with support for formality, context, and custom instructions | +| `deepl translate --file` | Translate text files (preserves code blocks and formatting) | +| `deepl document` | Translate documents (PDF, DOCX, PPTX, XLSX) with format preservation | +| `deepl write` | Grammar and style enhancement via DeepL Write | +| `deepl voice` | Real-time speech translation via WebSocket streaming | +| `deepl watch` | Monitor files and auto-translate on change | +| `deepl glossary` | Create, list, and manage glossaries | +| `deepl admin` | Manage API keys, usage limits, and team access | +| `deepl usage` | Check API usage and character quotas | +| `deepl config` | Configure defaults (target language, formality, model) | + +## Usage examples + +### Translate with context and formality + +```bash +deepl translate "Thank you for your patience" --to de --formality more \ + --context "Customer support email to a long-standing client" +``` + +### Translate a document + +```bash +deepl document translate report.pdf --to fr --output report-fr.pdf +``` + +### Batch translate a directory + +```bash +deepl translate --file src/locales/en/ --to de,fr,es --output src/locales/ +``` + +### Watch mode for development + +```bash +deepl watch ./content/en --to de,fr --output ./content/ +``` + +### Git hooks integration + +```bash +deepl hooks install --pre-commit --languages de,fr +``` + +## Developer workflow features + +- **Smart caching**: Local SQLite cache with LRU eviction avoids redundant API calls +- **Cost tracking**: Monitor billed characters for budget planning (`deepl usage`) +- **CI/CD ready**: `--quiet` and `--no-input` flags for non-interactive pipelines +- **Shell completion**: Generate completions for bash, zsh, fish, and PowerShell + +## Further reading + +- [DeepL CLI on GitHub](https://github.com/DeepLcom/deepl-cli) — full documentation, changelog, and source code +- [DeepL API authentication](/docs/getting-started/auth) — set up your API key +- [Client libraries](/docs/getting-started/client-libraries) — official SDKs for six languages From b440861166d73137092b8a21a851513cefe005e5 Mon Sep 17 00:00:00 2001 From: Ming Gong Date: Fri, 13 Mar 2026 11:26:02 -0400 Subject: [PATCH 2/3] Remove npm installation section per review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit npm package is not published yet — only show install-from-source. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/getting-started/deepl-cli.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/getting-started/deepl-cli.mdx b/docs/getting-started/deepl-cli.mdx index 39108ae8..1207c972 100644 --- a/docs/getting-started/deepl-cli.mdx +++ b/docs/getting-started/deepl-cli.mdx @@ -11,14 +11,6 @@ The DeepL CLI is open-source under the [MIT License](https://github.com/DeepLcom ## Installation -### From npm (coming soon) - -```bash -npm install -g deepl-cli -``` - -### From source - ```bash git clone https://github.com/DeepLcom/deepl-cli.git cd deepl-cli From 136338c063a71bdee045f9bff101dfbf5235dc7a Mon Sep 17 00:00:00 2001 From: Ming Gong Date: Fri, 13 Mar 2026 12:24:24 -0400 Subject: [PATCH 3/3] Apply docs-reviewer feedback to CLI page - Add description to frontmatter - Add "This page shows you" opening summary - Replace redundant MIT callout with Node.js prerequisite note - Make capabilities table verbs parallel (all imperative) - Remove bold-before-colon pattern in developer features - Add context line before git hooks example - Add cross-reference to "Your first API request" Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/getting-started/deepl-cli.mdx | 41 +++++++++++++++++------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/getting-started/deepl-cli.mdx b/docs/getting-started/deepl-cli.mdx index 1207c972..e2d72573 100644 --- a/docs/getting-started/deepl-cli.mdx +++ b/docs/getting-started/deepl-cli.mdx @@ -1,16 +1,25 @@ --- title: "DeepL CLI" +description: "Install and use the DeepL CLI to translate text, documents, and more from your terminal." public: true --- -The [DeepL CLI](https://github.com/DeepLcom/deepl-cli) is an open-source (MIT license) command-line tool for interacting with the DeepL API. It covers text translation, document translation, writing enhancement, voice translation, glossary management, and admin operations — all from your terminal. +**This page shows you:** +- How to install the DeepL CLI from source +- How to authenticate and run your first translation +- What commands are available for translation, writing, voice, and more - -The DeepL CLI is open-source under the [MIT License](https://github.com/DeepLcom/deepl-cli/blob/main/LICENSE). Contributions and feedback are welcome! - +The [DeepL CLI](https://github.com/DeepLcom/deepl-cli) is an open-source (MIT license) command-line tool for interacting with the DeepL API. It covers text translation, document translation, writing enhancement, voice translation, glossary management, and admin operations — all from your terminal. ## Installation + +The CLI requires [Node.js](https://nodejs.org/) (v18+) and build tools for native compilation: +- **macOS**: Xcode Command Line Tools (`xcode-select --install`) +- **Linux**: `python3`, `make`, `gcc` (`apt install python3 make gcc g++`) +- **Windows**: Visual Studio Build Tools + + ```bash git clone https://github.com/DeepLcom/deepl-cli.git cd deepl-cli @@ -21,13 +30,6 @@ npm link deepl --version ``` - -The CLI uses `better-sqlite3` for local caching, which requires native compilation. Ensure you have build tools installed: -- **macOS**: Xcode Command Line Tools (`xcode-select --install`) -- **Linux**: `python3`, `make`, `gcc` (`apt install python3 make gcc g++`) -- **Windows**: Visual Studio Build Tools - - ## Quick start ### 1. Set up authentication @@ -69,10 +71,10 @@ deepl write "Their going to the stor tommorow" --lang en-us | Command | Description | |---------|-------------| | `deepl translate` | Translate text with support for formality, context, and custom instructions | -| `deepl translate --file` | Translate text files (preserves code blocks and formatting) | +| `deepl translate --file` | Translate text files while preserving code blocks and formatting | | `deepl document` | Translate documents (PDF, DOCX, PPTX, XLSX) with format preservation | -| `deepl write` | Grammar and style enhancement via DeepL Write | -| `deepl voice` | Real-time speech translation via WebSocket streaming | +| `deepl write` | Enhance grammar and style via DeepL Write | +| `deepl voice` | Stream real-time speech translation via WebSocket | | `deepl watch` | Monitor files and auto-translate on change | | `deepl glossary` | Create, list, and manage glossaries | | `deepl admin` | Manage API keys, usage limits, and team access | @@ -108,19 +110,22 @@ deepl watch ./content/en --to de,fr --output ./content/ ### Git hooks integration +Automatically translate changed files before each commit: + ```bash deepl hooks install --pre-commit --languages de,fr ``` ## Developer workflow features -- **Smart caching**: Local SQLite cache with LRU eviction avoids redundant API calls -- **Cost tracking**: Monitor billed characters for budget planning (`deepl usage`) -- **CI/CD ready**: `--quiet` and `--no-input` flags for non-interactive pipelines -- **Shell completion**: Generate completions for bash, zsh, fish, and PowerShell +- Local SQLite cache with LRU eviction avoids redundant API calls +- Monitor billed characters for budget planning with `deepl usage` +- Use `--quiet` and `--no-input` flags for CI/CD pipelines +- Generate shell completions for bash, zsh, fish, and PowerShell ## Further reading - [DeepL CLI on GitHub](https://github.com/DeepLcom/deepl-cli) — full documentation, changelog, and source code - [DeepL API authentication](/docs/getting-started/auth) — set up your API key +- [Your first API request](/docs/getting-started/your-first-api-request) — understand how the API works - [Client libraries](/docs/getting-started/client-libraries) — official SDKs for six languages