From ed99359dc6076fe3281f2ae46ca8ac6c157d6f2f Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Wed, 6 May 2026 10:45:36 +0200 Subject: [PATCH 1/3] style(endpoint-docs): fix trailing whitespace Co-Authored-By: Claude Sonnet 4.6 --- api-reference/document.mdx | 26 +++++++-------- api-reference/glossaries.mdx | 18 +++++------ api-reference/improve-text.mdx | 2 +- api-reference/multilingual-glossaries.mdx | 34 ++++++++++---------- api-reference/translate.mdx | 18 +++++------ docs/resources/roadmap-and-release-notes.mdx | 2 +- 6 files changed, 50 insertions(+), 50 deletions(-) diff --git a/api-reference/document.mdx b/api-reference/document.mdx index 4a15569..edb4753 100644 --- a/api-reference/document.mdx +++ b/api-reference/document.mdx @@ -55,7 +55,7 @@ curl -X POST 'https://api.deepl.com/v2/document' \ --form 'source_lang=EN' \ --form 'target_lang=DE' \ --form 'file=@document.docx' \ ---form 'glossary_id=[yourGlossaryId]' +--form 'glossary_id=[yourGlossaryId]' ``` ```json Example response @@ -71,38 +71,38 @@ The examples below use our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: document upload (no glossary) POST /v2/document HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: [length] Content-Type: multipart/form-data;boundary="boundary" --boundary,Content-Disposition: form-data; name=target_lang - + DE --boundary,Content-Disposition: form-data; name=file - + @document.docx ``` ```http Example request: document upload (with glossary) POST /v2/document HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: [length] Content-Type: multipart/form-data;boundary="boundary" --boundary,Content-Disposition: form-data; name=source_lang - + EN --boundary,Content-Disposition: form-data; name=target_lang - + DE --boundary,Content-Disposition: form-data; name=file - + @document.docx --boundary,Content-Disposition: form-data; name=glossary_id - + [yourGlossaryId] ``` @@ -156,7 +156,7 @@ These examples are for demonstration purposes only. In production code, the auth - A unique ID assigned to a glossary. + A unique ID assigned to a glossary. File extension of desired format of translated file, for example: `pdf`. If unspecified, by default the translated file will be in the same format as the input file. @@ -219,7 +219,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: check document status POST /v2/document/{document_id} HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 83 Content-Type: application/json @@ -285,7 +285,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: download translated document POST /v2/document/{document_id}/result HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 83 Content-Type: application/json @@ -312,4 +312,4 @@ The range of alternative output formats you can select are indicated in the tabl | Input document format | Alternative output document formats | | --- | --- | | PDF | `docx` - Microsoft Word Document | -| Others | None | +| Others | None | diff --git a/api-reference/glossaries.mdx b/api-reference/glossaries.mdx index 994bd03..0da4043 100644 --- a/api-reference/glossaries.mdx +++ b/api-reference/glossaries.mdx @@ -11,7 +11,7 @@ This page documents `v2` glossary endpoints, legacy endpoints that let you creat [See here](/api-reference/multilingual-glossaries) for information on current `v3` endpoints. Using `v3` allows you to create, manage, and edit glossaries with entries in multiple language pairs, while still supporting monolingual functionality. [See here](/api-reference/glossaries/v2-vs-v3-endpoints) for an overview of the difference. -This page describes how to use the `v2` endpoints to work with _monolingual_ glossaries - glossaries that map phrases in one language to phrases in another language. If you're new to glossaries, we suggest you use `v3` instead. +This page describes how to use the `v2` endpoints to work with _monolingual_ glossaries - glossaries that map phrases in one language to phrases in another language. If you're new to glossaries, we suggest you use `v3` instead. ### Create a glossary @@ -49,7 +49,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: create a glossary POST /v2/glossaries HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 112 Content-Type: application/json @@ -113,7 +113,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: create a glossary POST /v2/glossaries HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 112 Content-Type: application/json @@ -145,7 +145,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```sh Example request: list all glossaries curl -X GET 'https://api.deepl.com/v2/glossaries' \ ---header 'Authorization: DeepL-Auth-Key [yourAuthKey]' +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' ``` ```json Example response @@ -170,7 +170,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: list all glossaries GET /v2/glossaries HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` ```json Example response @@ -220,7 +220,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: retrieve glossary details GET /v2/glossaries/{glossary_id} HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` ```json Example response @@ -260,7 +260,7 @@ Hello! Guten Tag! ```http Example request: retrieve glossary entries GET /v2/glossaries/{glossary_id}/entries HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] 'Accept: text/tab-separated-values' User-Agent: YourApp/1.2.3 ``` @@ -289,7 +289,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: delete a glossary DELETE /v2/glossaries/{glossary_id} HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` @@ -333,7 +333,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: get glossary language pairs GET /v2/glossary-language-pairs HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` ```json Example response (partial—one language pair) diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx index 159628f..c26ef60 100644 --- a/api-reference/improve-text.mdx +++ b/api-reference/improve-text.mdx @@ -179,6 +179,6 @@ We've added a new column to the [API key-level usage report](/docs/getting-start #### Is "Corrections Only" mode available in the API? -No. "Corrections Only" is a mode that fixes spelling and grammatical errors only without broader rephrasing. It is currently only available in the DeepL Translator UI. +No. "Corrections Only" is a mode that fixes spelling and grammatical errors only without broader rephrasing. It is currently only available in the DeepL Translator UI. If you make an API request to `/write/rephrase` and omit both `writing_style` and `tone`, the API uses its default improvement mode. This corrects grammar and spelling but may also make broader changes than the "Corrections Only" mode in the UI. diff --git a/api-reference/multilingual-glossaries.mdx b/api-reference/multilingual-glossaries.mdx index 2070b79..3728a1b 100644 --- a/api-reference/multilingual-glossaries.mdx +++ b/api-reference/multilingual-glossaries.mdx @@ -6,10 +6,10 @@ description: "Manage and use DeepL glossaries" --- - This page documents `v3` glossary endpoints, which let you **edit** glossaries and allow for **multilingual** functionality. - + This page documents `v3` glossary endpoints, which let you **edit** glossaries and allow for **multilingual** functionality. + The current`v3` endpoints are used for working with **both multilingual and monolingual** glossaries. Thus, we recommend you start using the `v3` endpoints described below for all glossary needs. - + The previously used [v2 glossary endpoints](/api-reference/glossaries) can only be used with **monolingual** glossaries. [See here](/api-reference/glossaries/v2-vs-v3-endpoints) for more on the difference between `v2` and `v3` glossary endpoints. @@ -34,7 +34,7 @@ Note that this mapping occurs only in one direction, which is all you need durin | exquisito | delicieux | | mouse | mouse | -Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time. +Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time. ## Creating glossaries @@ -132,11 +132,11 @@ This example creates a modest glossary with two dictionaries. One maps "Hello" i ```http Example request: create a glossary POST /v3/glossaries HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 1234 Content-Type: application/json - + { "name": "My Glossary", "dictionaries": [ @@ -199,11 +199,11 @@ To use a glossary in a translation request, include its `glossary_id` . You must ```http Example request: translate including glossary POST /v2/translate HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 111 Content-Type: application/json - + { "text": [ "Hello there" @@ -245,7 +245,7 @@ Use this endpoint to list all your glossaries, basic information about each glos ```sh Example request: list glossaries curl -X GET 'https://api.deepl.com/v3/glossaries' \ - --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' ``` ```json Example response @@ -276,7 +276,7 @@ Use this endpoint to list all your glossaries, basic information about each glos ```http Example request: list all glossaries GET /v3/glossaries HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` @@ -345,7 +345,7 @@ Use this endpoint to retrieve basic information about a given glossary's diction ```http Example request: retrieve glossary details GET /v3/glossaries/{glossary_id} HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` @@ -406,7 +406,7 @@ Currently you can only retrieve glossary contents in TSV format. ```http Example request: get glossary entries GET /v3/glossaries/{glossary_id}/entries HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` @@ -467,7 +467,7 @@ Use this method to add a new dictionary to a glossary or replace an existing one ```http Example request: replace a dictionary PUT /v3/glossaries/{glossaryId}/dictionaries HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 210 Content-Type: application/json @@ -529,7 +529,7 @@ For example, this `PATCH` changes a glossary's name. ```http Example request: update glossary entries PATCH /v3/glossaries/{glossaryId} HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 147 Content-Type: application/json @@ -600,7 +600,7 @@ This example makes two changes. It changes the glossary's name, and it adds a ne ```http Example request: update glossary entries PATCH /v3/glossaries/{glossaryId} HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 147 Content-Type: application/json @@ -652,7 +652,7 @@ This method deletes the specified glossary in its entirety. ```http Example request: delete a glossary DELETE /v3/glossaries/{glossary_id} HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` @@ -679,7 +679,7 @@ Use this method to delete a dictionary for a specific language pair. ```http Example request: delete a dictionary DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang} HTTP/2 Host: api.deepl.com - Authorization: DeepL-Auth-Key [yourAuthKey] + Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 ``` diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 90ce22e..950f1a7 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -68,7 +68,7 @@ The examples below use our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: text translation (without glossary) POST /v2/translate HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 45 Content-Type: application/json @@ -79,7 +79,7 @@ Content-Type: application/json ```http Example request: text translation (with glossary) POST /v2/translate HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 97 Content-Type: application/json @@ -169,8 +169,8 @@ These examples are for demonstration purposes only. In production code, the auth Note that we do not include examples for our client libraries in every single section of this reference, but our client libraries *do* support all use cases shown on this page. - Please note that the Translate API is intended to be used for translation between different languages, but requests with the same source and target language are still counted toward billing. - + Please note that the Translate API is intended to be used for translation between different languages, but requests with the same source and target language are still counted toward billing. + If trying to convert between variants of the same language (e.g. `EN-US` to `EN-GB`), please refer to [this guide](/docs/learning-how-tos/examples-and-guides/translating-between-variants). Translating between variants of the same language will result in no change to the text. @@ -287,7 +287,7 @@ error. Specify the style rule list to use for the translation which can be used to customize translations according to the selected formatting and style conventions. - The target language has to match the language of the style rule list. + The target language has to match the language of the style rule list. Additionally, any request with the `style_id` parameter enabled will default to use the `quality_optimized` model type. Requests combining `style_id` and `model_type: latency_optimized` will be rejected. @@ -295,7 +295,7 @@ error. Specify a list of instructions to customize the translation behavior. Up to 10 custom instructions can be specified, each with a maximum of 300 characters. - + The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages. Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/best-practices/custom-instructions). @@ -316,7 +316,7 @@ error.

For example: "billed_characters": 42

At some point in the future, we intend to include billed_characters in the API response by default, at which point it will be necessary to set show_billed_characters to false in order for an API response not to include billed_characters. We will notify users in advance of making this change. - + For requests sent as URL-encoded forms, boolean values should be specified as "1" or "0". @@ -430,7 +430,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: multiple sentences POST /v2/translate HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 71 Content-Type: application/json @@ -503,7 +503,7 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a ```http Example request: large volumes of text POST /v2/translate HTTP/2 Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] +Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 Content-Length: 120 Content-Type: application/json diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index c65c082..ad48e8a 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -73,7 +73,7 @@ Use the `DeepL-Auth-Key` header instead. ## January 8 - 81 New Languages in GA - Promoted all 81 beta languages to standard language support. These languages are now part of the main source and target language lists. - Note that these languages only work with `quality_optimized` model or when no model is specified, and are not compatible with `latency_optimized` requests. -- The `enable_beta_languages` parameter is maintained for backward compatibility but has no effect. +- The `enable_beta_languages` parameter is maintained for backward compatibility but has no effect. See [here](../getting-started/supported-languages) for the complete language list. From 03c7e3391b056527d58ddffb94f0407789428ec6 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Wed, 6 May 2026 10:58:29 +0200 Subject: [PATCH 2/3] refactor(v3-languages): rename retrieve-products to retrieve-resources Matches the /v3/languages/resources endpoint name. Updates nav entry in docs.json, self-link in overview page, and adds a redirect. Co-Authored-By: Claude Sonnet 4.6 --- .../{retrieve-products.mdx => retrieve-resources.mdx} | 0 .../languages/retrieve-supported-languages-by-resource.mdx | 2 +- docs.json | 6 +++++- 3 files changed, 6 insertions(+), 2 deletions(-) rename api-reference/languages/{retrieve-products.mdx => retrieve-resources.mdx} (100%) diff --git a/api-reference/languages/retrieve-products.mdx b/api-reference/languages/retrieve-resources.mdx similarity index 100% rename from api-reference/languages/retrieve-products.mdx rename to api-reference/languages/retrieve-resources.mdx diff --git a/api-reference/languages/retrieve-supported-languages-by-resource.mdx b/api-reference/languages/retrieve-supported-languages-by-resource.mdx index 55f3f7c..e29e89b 100644 --- a/api-reference/languages/retrieve-supported-languages-by-resource.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-resource.mdx @@ -13,7 +13,7 @@ Get information about all currently supported languages across all DeepL API res We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools: - [Retrieve languages](/api-reference/languages/retrieve-languages-by-resource) -- [Retrieve resources](/api-reference/languages/retrieve-products) +- [Retrieve resources](/api-reference/languages/retrieve-resources) To understand how we'll update these endpoints when we add translation support for a new language or language variant, please see [this article](/docs/resources/language-release-process). diff --git a/docs.json b/docs.json index ab18222..dc4edb5 100644 --- a/docs.json +++ b/docs.json @@ -256,7 +256,7 @@ "api-reference/languages/retrieve-supported-languages-by-resource", "api-reference/languages/language-feature-use-cases", "api-reference/languages/retrieve-languages-by-resource", - "api-reference/languages/retrieve-products", + "api-reference/languages/retrieve-resources", "api-reference/languages/migrate-from-v2-languages", "api-reference/languages/v3-languages-changelog" ], @@ -347,6 +347,10 @@ "source": "/api-reference/languages/retrieve-supported-languages-by-product", "destination": "/api-reference/languages/retrieve-supported-languages-by-resource" }, + { + "source": "/api-reference/languages/retrieve-products", + "destination": "/api-reference/languages/retrieve-resources" + }, { "source": "/api-reference/languages/retrieve-languages-by-product", "destination": "/api-reference/languages/retrieve-languages-by-resource" From c73552914a8a36459a5315e547d8cd9c4670c3f0 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Wed, 6 May 2026 11:00:47 +0200 Subject: [PATCH 3/3] docs: add v3/languages cross-references to endpoint docs Co-Authored-By: Claude Sonnet 4.6 --- api-reference/document.mdx | 4 ++-- api-reference/improve-text.mdx | 8 ++++++-- api-reference/multilingual-glossaries.mdx | 2 ++ api-reference/translate.mdx | 5 ++++- api-reference/voice.mdx | 2 ++ docs/getting-started/supported-languages.mdx | 2 +- 6 files changed, 17 insertions(+), 6 deletions(-) diff --git a/api-reference/document.mdx b/api-reference/document.mdx index edb4753..29162a2 100644 --- a/api-reference/document.mdx +++ b/api-reference/document.mdx @@ -146,7 +146,7 @@ These examples are for demonstration purposes only. In production code, the auth The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition. - Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages `DE` (German), `FR` (French), `IT` (Italian), `ES` (Spanish), `NL` (Dutch), `PL` (Polish), `PT-BR` and `PT-PT` (Portuguese), `JA` (Japanese), and `RU` (Russian). Learn more about the plain/polite feature for Japanese here. Setting this parameter with a target language that does not support formality will fail, unless one of the `prefer_...` options are used. Possible options are: + Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages `DE` (German), `FR` (French), `IT` (Italian), `ES` (Spanish), `NL` (Dutch), `PL` (Polish), `PT-BR` and `PT-PT` (Portuguese), `JA` (Japanese), and `RU` (Russian). Learn more about the plain/polite feature for Japanese here. Setting this parameter with a target language that does not support formality will fail, unless one of the `prefer_...` options are used. To check formality support dynamically, call GET /v3/languages?resource=translate_document and look for the formality feature key on the target language. Possible options are:
  • `default` (default)
  • `more` - for a more formal language
    • @@ -156,7 +156,7 @@ These examples are for demonstration purposes only. In production code, the auth
- A unique ID assigned to a glossary. + A unique ID assigned to a glossary. To check glossary support for a language pair, call GET /v3/languages?resource=translate_document and verify the glossary feature key is present on both the source and target language. File extension of desired format of translated file, for example: `pdf`. If unspecified, by default the translated file will be in the same format as the input file. diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx index c26ef60..6fd60bf 100644 --- a/api-reference/improve-text.mdx +++ b/api-reference/improve-text.mdx @@ -62,7 +62,7 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \ Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences. - The language of the improved text. A list of supported languages have not yet been added to the `/languages` endpoint. Currently, the following languages are supported: + The language of the improved text. Currently, the following languages are supported: * `de` (German) * `en-GB` (British English) @@ -76,6 +76,8 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \ * `pt-PT` (Portuguese) * `zh`/`zh-Hans` (simplified Chinese) + You can also retrieve supported languages programmatically via GET /v3/languages?resource=write. + The language of the source texts sent in the `text` parameter must match the target language (translating and improving text simultaneously is not yet supported). Note that it is possible to convert text from one variant to another within a language. For example, if American English is sent in an API request with `target_lang` set to `EN-GB`, the submitted text will be improved and also converted to British English. @@ -111,6 +113,8 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \ Styles prefixed with `prefer_` will fall back to the `default` style when used with a language that does not support styles (this is recommended for cases where no `target_lang` is set), the non-prefixed writing styles (except `default`) will return a HTTP 400 error in that case. It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included. + + To check writing style support dynamically, call GET /v3/languages?resource=write and look for the writing_style feature key on the target language. Changes the tone of your improvements. @@ -142,7 +146,7 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \ Tones prefixed with `prefer_` will fall back to the `default` tone when used with a language that does not support tones (this is recommended for cases where no `target_lang` is set), the non-prefixed tones (except `default`) will return a HTTP 400 error in that case. - It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included. + It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included. To check tone support dynamically, call GET /v3/languages?resource=write and look for the tone feature key on the target language. ### Response body descriptions diff --git a/api-reference/multilingual-glossaries.mdx b/api-reference/multilingual-glossaries.mdx index 3728a1b..1a51d00 100644 --- a/api-reference/multilingual-glossaries.mdx +++ b/api-reference/multilingual-glossaries.mdx @@ -691,6 +691,8 @@ Use this method to delete a dictionary for a specific language pair. The DeepL API supports [these languages for glossaries](/docs/getting-started/supported-languages). +To retrieve supported glossary languages programmatically, call [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-resource). + ### Language variants Glossaries apply to languages, not specific language variants. A glossary for a language applies to any variant of that language. diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 950f1a7..0f99ac3 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -267,7 +267,7 @@ error. - Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages DE (German), FR (French), IT (Italian), ES (Spanish), ES-419 (Latin American Spanish), NL (Dutch), PL (Polish), PT-BR and PT-PT (Portuguese), JA (Japanese), and RU (Russian). Learn more about the plain/polite feature for Japanese ↗️. + Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages DE (German), FR (French), IT (Italian), ES (Spanish), ES-419 (Latin American Spanish), NL (Dutch), PL (Polish), PT-BR and PT-PT (Portuguese), JA (Japanese), and RU (Russian). Learn more about the plain/polite feature for Japanese ↗️. To check formality support dynamically, call GET /v3/languages?resource=translate_text and look for the formality feature key on the target language.

Setting this parameter with a target language that does not support formality will fail, unless one of the prefer_... options are used. Possible options are:

    @@ -283,6 +283,7 @@ error. Important: This requires the source_lang parameter to be set and the language pair of the glossary has to match the language pair of the request. + To check glossary support for a language pair, call GET /v3/languages?resource=translate_text and verify the glossary feature key is present on both the source and target language. Specify the style rule list to use for the translation which can be used to customize translations according to the selected formatting and style conventions. @@ -300,6 +301,7 @@ error. Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/best-practices/custom-instructions). + To check language support dynamically, call GET /v3/languages?resource=translate_text and check for the style_rules feature key on the target language. The [translation memory](/api-reference/translation-memory/list-translation-memories) to use for the translation. The value should be the UUID of a translation memory associated with your account. @@ -326,6 +328,7 @@ error.
  • xml: Enable XML tag handling; see XML handling.
  • html: Enable HTML tag handling; see HTML handling.
+ To check tag handling support for a language pair, call GET /v3/languages?resource=translate_text and check the tag_handling feature key is present on both the source and target language. Select which version of the tag handling algorithm should be used. See tag handling v2. diff --git a/api-reference/voice.mdx b/api-reference/voice.mdx index de01713..316b51d 100644 --- a/api-reference/voice.mdx +++ b/api-reference/voice.mdx @@ -96,6 +96,8 @@ All source languages can be translated into any target language. you must explicitly specify the source language. +To retrieve supported languages and feature availability programmatically, call [`GET /v3/languages?resource=voice`](/api-reference/languages/retrieve-supported-languages-by-resource) and check for the `transcription` and `translated_speech` feature keys. The external flag on these features indicates if they are provided by an external service partner. + ## Supported Audio Formats The API supports various common combinations of streaming codecs and containers with a single channel (mono) audio stream. diff --git a/docs/getting-started/supported-languages.mdx b/docs/getting-started/supported-languages.mdx index 4196926..3d30bb1 100644 --- a/docs/getting-started/supported-languages.mdx +++ b/docs/getting-started/supported-languages.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Languages supported" mode: "wide" --- -The DeepL API supports the following languages. These can also be retrieved programmatically via the [`/languages` endpoint](/api-reference/languages/retrieve-supported-languages). +The DeepL API supports the following languages. These can also be retrieved programmatically via the [`/v3/languages` endpoint](/api-reference/languages/retrieve-supported-languages-by-resource), which returns language support per resource along with feature availability (e.g. formality, glossary, auto-detection). The legacy [`/v2/languages` endpoint](/api-reference/languages/retrieve-supported-languages) is also available but deprecated. ## API Supported Languages