From b21889678c78606af18ac5d46c867e9abc39e1af Mon Sep 17 00:00:00 2001 From: Ben Morss Date: Thu, 2 Apr 2026 20:07:53 -0400 Subject: [PATCH 1/3] Refactor top of sidebar Changed "intro" to "quickstart", added redirect Made "Getting started" area only about getting started, for new users Made new "Essentials" and "Developer tools" areas for other things Made some links that opened a new tab, not open a new tab --- docs.json | 55 +++++++++++-------- .../{intro.mdx => quickstart.mdx} | 4 +- .../translation-beginners-guide.mdx | 6 +- 3 files changed, 37 insertions(+), 28 deletions(-) rename docs/getting-started/{intro.mdx => quickstart.mdx} (98%) diff --git a/docs.json b/docs.json index bcd33f17..8ba93c63 100644 --- a/docs.json +++ b/docs.json @@ -37,38 +37,25 @@ { "group": "Getting Started", "pages": [ - "docs/getting-started/intro", "docs/getting-started/about", + "docs/getting-started/quickstart", + "docs/getting-started/client-libraries", + "docs/getting-started/your-first-api-request" + ] + }, + { + "group": "Essentials", + "pages": [ + "docs/getting-started/supported-languages", "docs/getting-started/auth", - "docs/getting-started/regional-endpoints", - { - "group": "Developer Tools", - "pages": [ - "docs/getting-started/client-libraries", - "docs/getting-started/deepl-cli", - "docs/getting-started/deepl-mcp-server" - ] - }, "docs/getting-started/managing-api-keys", - "docs/getting-started/your-first-api-request", "docs/getting-started/test-your-api-requests-with-postman", - "docs/getting-started/supported-languages" + "docs/getting-started/regional-endpoints" ] }, { "group": "Learning & How Tos", "pages": [ - { - "group": "Cookbook", - "pages": [ - "docs/learning-how-tos/cookbook", - "docs/learning-how-tos/cookbook/google-sheets", - "docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot", - "docs/learning-how-tos/cookbook/java-document-translator", - "docs/learning-how-tos/cookbook/usage-analytics-dashboard", - "docs/learning-how-tos/cookbook/nodejs-proxy" - ] - }, { "group": "Guides", "pages": [ @@ -80,9 +67,27 @@ "docs/learning-how-tos/examples-and-guides/placeholder-tags", "docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications" ] + }, + { + "group": "Cookbook", + "pages": [ + "docs/learning-how-tos/cookbook", + "docs/learning-how-tos/cookbook/google-sheets", + "docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot", + "docs/learning-how-tos/cookbook/java-document-translator", + "docs/learning-how-tos/cookbook/usage-analytics-dashboard", + "docs/learning-how-tos/cookbook/nodejs-proxy" + ] } ] }, + { + "group": "Developer Tools", + "pages": [ + "docs/getting-started/deepl-cli", + "docs/getting-started/deepl-mcp-server" + ] + }, { "group": "Best Practices", "pages": [ @@ -406,6 +411,10 @@ "source": "/docs/getting-started/alpha-and-beta-features", "destination": "/docs/resources/alpha-and-beta-features" }, + { + "source": "/docs/getting-started/intro", + "destination": "/docs/getting-started/quickstart" + }, { "source": "/docs/resources/release-notes", "destination": "/docs/resources/roadmap-and-release-notes" diff --git a/docs/getting-started/intro.mdx b/docs/getting-started/quickstart.mdx similarity index 98% rename from docs/getting-started/intro.mdx rename to docs/getting-started/quickstart.mdx index 4e048fcc..3d8547cb 100644 --- a/docs/getting-started/intro.mdx +++ b/docs/getting-started/quickstart.mdx @@ -1,6 +1,5 @@ --- -title: "Introduction" -description: "Welcome to the developer home of DeepL API." +title: "Quickstart" public: true mode: "wide" --- @@ -247,6 +246,7 @@ New user? Follow these quick steps to get started with the DeepL API. - [Your first API request](/docs/getting-started/your-first-api-request) - With just a few lines of code, make your first request to the DeepL Translate or Write API - [**DeepL 101**](/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api) - A quick guide to text and document translation, using Postman to play with the API, client libraries for your favorite programming language, and joining our developer community +- [Translation: a beginner's guide](/docs/learning-how-tos/examples-and-guides/translation-beginners-guide) - A detailed guide to fundamental translation features - [Cookbook](/docs/learning-how-tos/cookbook) - Explore short tutorials, examples, projects, and use cases - [Guides](/docs/learning-how-tos/examples-and-guides) - Discover in-depth explanations for API features and real-world applications diff --git a/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx b/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx index 5c825413..0a054430 100644 --- a/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx +++ b/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx @@ -845,8 +845,8 @@ Congratulations! Now you know how to send the DeepL API a translation request in Here are some possible next steps: * Play with translation requests using these parameters and other options in [our playground](https://developers.deepl.com/api-reference/translate/request-translation?playground=open) or [Postman](/docs/getting-started/test-your-api-requests-with-postman). -* For complete information on the `/translate` endpoint, see [the /translate reference](https://developers.deepl.com/api-reference/translate/request-translation) +* For complete information on the `/translate` endpoint, see [the `/translate` reference](/api-reference/translate/request-translation) * See this [introduction to DeepL glossaries](/docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world) -* To learn how to translate text in files - PDFs, presentations, powerpoints, HTML, images, and more - see [the /document reference](https://developers.deepl.com/api-reference/document) -* To translate audio, see [the /voice endpoint](https://developers.deepl.com/api-reference/voice) +* To learn how to translate text in files - PDFs, presentations, powerpoints, HTML, images, and more - see [the `/document` reference](/api-reference/document) +* To translate audio, see [the `/voice` reference](/api-reference/voice) From 7ee079c1e4984d02519fa7d15372c28d1087e3eb Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Thu, 9 Apr 2026 13:42:24 -0400 Subject: [PATCH 2/3] Remove "Your first API request" page and redirect to quickstart The page didn't provide additional value beyond the quickstart. Adds a redirect from its URL to the quickstart page and removes references from the sidebar, quickstart, and CLI pages. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs.json | 7 +- docs/getting-started/deepl-cli.mdx | 1 - docs/getting-started/quickstart.mdx | 1 - .../your-first-api-request.mdx | 205 ------------------ 4 files changed, 5 insertions(+), 209 deletions(-) delete mode 100644 docs/getting-started/your-first-api-request.mdx diff --git a/docs.json b/docs.json index 8ba93c63..a5b15440 100644 --- a/docs.json +++ b/docs.json @@ -39,8 +39,7 @@ "pages": [ "docs/getting-started/about", "docs/getting-started/quickstart", - "docs/getting-started/client-libraries", - "docs/getting-started/your-first-api-request" + "docs/getting-started/client-libraries" ] }, { @@ -415,6 +414,10 @@ "source": "/docs/getting-started/intro", "destination": "/docs/getting-started/quickstart" }, + { + "source": "/docs/getting-started/your-first-api-request", + "destination": "/docs/getting-started/quickstart" + }, { "source": "/docs/resources/release-notes", "destination": "/docs/resources/roadmap-and-release-notes" diff --git a/docs/getting-started/deepl-cli.mdx b/docs/getting-started/deepl-cli.mdx index e2d72573..1e8dfa4d 100644 --- a/docs/getting-started/deepl-cli.mdx +++ b/docs/getting-started/deepl-cli.mdx @@ -127,5 +127,4 @@ deepl hooks install --pre-commit --languages de,fr - [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 diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index 3d8547cb..d12fefa9 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -244,7 +244,6 @@ New user? Follow these quick steps to get started with the DeepL API. ## Keep exploring -- [Your first API request](/docs/getting-started/your-first-api-request) - With just a few lines of code, make your first request to the DeepL Translate or Write API - [**DeepL 101**](/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api) - A quick guide to text and document translation, using Postman to play with the API, client libraries for your favorite programming language, and joining our developer community - [Translation: a beginner's guide](/docs/learning-how-tos/examples-and-guides/translation-beginners-guide) - A detailed guide to fundamental translation features - [Cookbook](/docs/learning-how-tos/cookbook) - Explore short tutorials, examples, projects, and use cases diff --git a/docs/getting-started/your-first-api-request.mdx b/docs/getting-started/your-first-api-request.mdx deleted file mode 100644 index e88c5ca7..00000000 --- a/docs/getting-started/your-first-api-request.mdx +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: "Your first API request" -description: "Make your first API requests to translate and improve text with the DeepL API." -mode: "wide" -public: true ---- - -Once you've created a DeepL API account and located your authentication key, you're ready to make your first requests. - -### Text translation - -To [translate text](/api-reference/translate), you can use the `/translate` endpoint, which also supports translation of [XML and HTML content](/api-reference/translate#in-text-markup). - -We included text translation examples for our [client libraries](/docs/getting-started/client-libraries), too, just to give you an idea of what they look like. - - - - - If you chose a free API plan, replace `https://api.deepl.com` with `https://api-free.deepl.com`. - - - ```http Example request - POST /v2/translate HTTP/2 - Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] - User-Agent: YourApp/1.2.3 - Content-Length: 45 - Content-Type: application/json - - {"text":["Hello, world!"],"target_lang":"DE"} - ``` - - ```json Example response - { - "translations": [ - { - "detected_source_language": "EN", - "text": "Hallo, Welt!" - } - ] - } - ``` - - - - If you chose a free API plan, replace `https://api.deepl.com` with `https://api-free.deepl.com`. - - - ```bash Example request - curl -X POST 'https://api.deepl.com/v2/translate' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ - --header 'Content-Type: application/json' \ - --data '{ - "text": [ - "Hello, world!" - ], - "target_lang": "DE" - }' - ``` - - ```json Example response - { - "translations": [ - { - "detected_source_language": "EN", - "text": "Hallo, Welt!" - } - ] - } - ``` - - - ```python - import deepl - - auth_key = "f63c02c5-f056-..." # replace with your key - deepl_client = deepl.DeepLClient(auth_key) - - result = deepl_client.translate_text("Hello, world!", target_lang="FR") - print(result.text) # "Bonjour à tous !" - ``` - - - In production code, it's safer to store your API key in an environment variable. - - - - ```javascript - import * as deepl from 'deepl-node'; - - const authKey = "f63c02c5-f056-..."; // Replace with your key - const deeplClient = new deepl.DeepLClient(authKey); - - (async () => { - const result = await deeplClient.translateText('Hello, world!', null, 'fr'); - console.log(result.text); // Bonjour à tous ! - })(); - ``` - - - In production code, it's safer to store your API key in an environment variable. - - - - ```php - require_once 'vendor/autoload.php'; - use DeepL\Client; - - $authKey = "f63c02c5-f056-..."; // Replace with your key - $deeplClient = new DeepL\DeepLClient($authKey); - - $result = $deeplClient->translateText('Hello, world!', null, 'fr'); - echo $result->text; // Bonjour, le monde! - ``` - - - In production code, it's safer to store your API key in an environment variable. - - - - ```csharp - using DeepL; // this imports the DeepL namespace. Use the code below in your main program. - - var authKey = "f63c02c5-f056-..."; // replace with your key - var client = new DeepLClient(authKey); - - var translatedText = await client.TranslateTextAsync( - "Hello, world!", - null, - LanguageCode.French); - Console.WriteLine(translatedText); // "Bonjour à tous !" - ``` - - - In production code, it's safer to store your API key in an environment variable. - - - - ```java - import com.deepl.api.*; - - public class Main { - public static void main(String[] args) throws DeepLException, InterruptedException { - String authKey = "{YOUR_API_KEY}"; // replace with your key - DeepLClient client = new DeepLClient(authKey); - - TextResult result = client.translateText("Hello, world!", null, "fr"); - System.out.println(result.getText()); // "Bonjour à tous !" - } - } - ``` - - - In production code, it's safer to store your API key in an environment variable. - - - - ```ruby - require 'deepl' - - DeepL.configure do |config| - config.auth_key = '{YOUR_API_KEY}' # replace with your key - end - - translation = DeepL.translate 'Hello, world!', nil, 'fr' - puts translation.text // "Bonjour à tous !" - ``` - - - In production code, it's safer to store your API key in an environment variable. - - - - -### Text improvement - -To [improve text](/docs/getting-started/your-first-api-request#text-improvement), you can use the `/write/rephrase` endpoint. We included an example below. - -The text improvement endpoint (DeepL API for Write) is currently only available to **Pro API** subscribers via the v2 endpoint. - - - ```bash Example cURL request - curl -X POST 'https://api.deepl.com/v2/write/rephrase' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ - --header 'Content-Type: application/json' \ - --data '{ - "text": [ - "Its never to late too fix you'\''re grammer & speling!" - ], - "target_lang": "en-GB" - }' - ``` - - ```json Example response - { - "improvements": [ - { - "text": "It's never too late to fix your grammar and spelling!", - "detected_source_language": "en", - "target_language": "en-GB" - } - ] - } - ``` - From 1237d0c5f59571edfc58e57e6a5894ff8f819504 Mon Sep 17 00:00:00 2001 From: Ben Morss Date: Thu, 9 Apr 2026 16:58:46 -0400 Subject: [PATCH 3/3] Left sidebar followup * moved existing client libraries page back to "Developer Tools" * wrote new client libraries page suitable for "Getting Started" section * Since "About" is now the home page, moved our banner there, and tweaked the vertical margins to avoid extra unsightly blank space --- docs.json | 1 + docs/getting-started/about.mdx | 8 ++-- .../client-libraries-reference.mdx | 45 +++++++++++++++++++ docs/getting-started/client-libraries.mdx | 40 ++++++++--------- docs/getting-started/quickstart.mdx | 2 - 5 files changed, 71 insertions(+), 25 deletions(-) create mode 100644 docs/getting-started/client-libraries-reference.mdx diff --git a/docs.json b/docs.json index a5b15440..dd689acd 100644 --- a/docs.json +++ b/docs.json @@ -83,6 +83,7 @@ { "group": "Developer Tools", "pages": [ + "docs/getting-started/client-libraries-reference", "docs/getting-started/deepl-cli", "docs/getting-started/deepl-mcp-server" ] diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx index 7aaf1bc9..2cfdd7a3 100644 --- a/docs/getting-started/about.mdx +++ b/docs/getting-started/about.mdx @@ -3,9 +3,11 @@ title: "About" public: false --- - - For information about API updates and improvements, please refer to our [release notes](/docs/resources/release-notes). - +Animated DeepL banner The DeepL API provides programmatic access to DeepL’s language AI technology, making it possible to bring high quality translation capabilities directly to your websites and applications. diff --git a/docs/getting-started/client-libraries-reference.mdx b/docs/getting-started/client-libraries-reference.mdx new file mode 100644 index 00000000..19bf4890 --- /dev/null +++ b/docs/getting-started/client-libraries-reference.mdx @@ -0,0 +1,45 @@ +--- +title: "Client libraries" +public: true +--- +## Official client libraries + +DeepL develops and supports client libraries for six popular languages: + + + + deeplcom\deepl-dotnet + + + deeplcom\deepl-java + + + deeplcom\deepl-node + + + deeplcom\deepl-php + + + deeplcom\deepl-python + + + deeplcom\deepl-rb + + + +Features include: + +* Out-of-the-box retries with exponential backoff for correct handling of 429 and 500 errors +* Persistent HTTP connection (keep-alive) enabled by default +* All document translation steps (upload, check status, and download) consolidated into a single convenience function + +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/client-libraries.mdx b/docs/getting-started/client-libraries.mdx index 37bf7411..642b2cb8 100644 --- a/docs/getting-started/client-libraries.mdx +++ b/docs/getting-started/client-libraries.mdx @@ -1,45 +1,45 @@ --- title: "Client libraries" +description: "Using your favorite programming language with the DeepL API" public: true --- -## Official client libraries -DeepL develops and supports client libraries for six popular languages: +## Overview +You can use many popular programming languages to access the DeepL API. + +DeepL enables this through six official client libraries which handle API requests and help parse responses so you can focus on building your application. For example, [the JavaScript library's `translateDocument()` function](https://github.com/DeepLcom/deepl-node?tab=readme-ov-file#translating-documents) handles the document translation workflow - uploading a document, polling for completion, and downloading the result. + +The client libraries are hosted on [GitHub](https://github.com/DeepLcom). This documentation frequently includes code samples in the six programming languages DeepL supports and maintains. But for complete information, setup instructions, installation steps, and code samples, see these GitHub repositories: - + deeplcom\deepl-dotnet - - deeplcom\deepl-php + + deeplcom\deepl-java - + deeplcom\deepl-node + + deeplcom\deepl-php + deeplcom\deepl-python deeplcom\deepl-rb - - deeplcom\deepl-java - -Features include: - -* Out-of-the-box retries with exponential backoff for correct handling of 429 and 500 errors -* Persistent HTTP connection (keep-alive) enabled by default -* All document translation steps (upload, check status, and download) consolidated into a single convenience function - -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). +## Next steps +Now that you've found your client library, here are a few ways to keep learning about the DeepL API: + +* try sample requests [in our playground](https://developers.deepl.com/api-reference/translate/request-translation?playground=open) +* [DeepL 101](/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api) - a quick guide to text and document translation +* [Translation: a beginner's guide](/docs/learning-how-tos/examples-and-guides/translation-beginners-guide) - a detailed guide to fundamental translation features diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index d12fefa9..20495e22 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -4,8 +4,6 @@ public: true mode: "wide" --- -![](/_assets/images/intro/banner.gif) - ## Get an API key and get started New user? Follow these quick steps to get started with the DeepL API.