diff --git a/docs.json b/docs.json index bcd33f17..dd689acd 100644 --- a/docs.json +++ b/docs.json @@ -37,38 +37,24 @@ { "group": "Getting Started", "pages": [ - "docs/getting-started/intro", "docs/getting-started/about", + "docs/getting-started/quickstart", + "docs/getting-started/client-libraries" + ] + }, + { + "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 +66,28 @@ "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/client-libraries-reference", + "docs/getting-started/deepl-cli", + "docs/getting-started/deepl-mcp-server" + ] + }, { "group": "Best Practices", "pages": [ @@ -406,6 +411,14 @@ "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/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/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..8de7e2bf 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. [Hosted on GitHub](https://github.com/DeepLcom), these client libraries 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. + +This documentation site 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/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/intro.mdx b/docs/getting-started/quickstart.mdx similarity index 97% rename from docs/getting-started/intro.mdx rename to docs/getting-started/quickstart.mdx index 4e048fcc..20495e22 100644 --- a/docs/getting-started/intro.mdx +++ b/docs/getting-started/quickstart.mdx @@ -1,12 +1,9 @@ --- -title: "Introduction" -description: "Welcome to the developer home of DeepL API." +title: "Quickstart" 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. @@ -245,8 +242,8 @@ 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 - [Guides](/docs/learning-how-tos/examples-and-guides) - Discover in-depth explanations for API features and real-world applications 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" - } - ] - } - ``` - 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)