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..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/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)