diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx deleted file mode 100644 index 3ec778c8..00000000 --- a/api-reference/translate.mdx +++ /dev/null @@ -1,537 +0,0 @@ ---- -title: "Translate Text" -sidebarTitle: "Overview" -description: "API reference for translating text with the DeepL API." -public: true ---- - -The text-translation API currently consists of a single endpoint, `translate`, which is described below. - -For details on model selection, see the [`model_type` parameter](#about-the-model_type-parameter). - -To learn more about context in DeepL API translations, see our [context parameter guide](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter). - -For more detail about request body parameters, see the [Request Body Descriptions](/api-reference/translate#request-body-descriptions) section further down on the page. - -See [Translation memories](/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories) for a guide on using translation memories in your translations. - -We also provide a spec that is auto-generated from DeepL's OpenAPI file. [You can find it here](/api-reference/translate/request-translation). - - -The total request body size for text translation requests must not exceed 128 KiB (128 · 1024 bytes). Please split up your text into multiple calls if it exceeds this limit. - - - - -The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - -```sh Example request: text translation (without glossary) -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" -}' -``` - -```sh Example request: text translation (with glossary) -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", - "source_lang": "EN", - "glossary_id": "[yourGlossaryId]" -}' -``` - -```json Example response -{ - "translations": [ - { - "detected_source_language": "EN", - "text": "Hallo, Welt!" - } - ] -} -``` - - -The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - -```http Example request: text translation (without glossary) -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"} -``` - -```http Example request: text translation (with glossary) -POST /v2/translate HTTP/2 -Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] -User-Agent: YourApp/1.2.3 -Content-Length: 97 -Content-Type: application/json - -{"text":["Hello, world!"],"target_lang":"DE","source_lang":"EN","glossary_id":"[yourGlossaryId]"} -``` - -```json Example response -{ - "translations": [ - { - "detected_source_language": "EN", - "text": "Hallo, Welt!" - } - ] -} -``` - - -```py Example request: text translation (without glossary) -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, le monde !" -``` - - -```php Example request: text translation (without glossary) -$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! -``` - - -```cs Example request: text translation (without glossary) -var authKey = "f63c02c5-f056-..."; // Replace with your key -var deeplClient = new DeepLClient(authKey); - -// Translate text into a target language, in this case, French: -var translatedText = await deeplClient.TranslateTextAsync( - "Hello, world!", - LanguageCode.English, - LanguageCode.French); -Console.WriteLine(translatedText); // "Bonjour, le monde !" -// Note: printing or converting the result to a string uses the output text. -``` - - -```javascript Example request: text translation (without glossary) -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, le monde ! -})(); -``` - - -```java Example request: text translation (without glossary) -import com.deepl.api.*; - -class Example { - DeepLClient deeplClient; - - public Example() throws Exception { - String authKey = "f63c02c5-f056-..."; // Replace with your key - deeplClient = new DeepLClient(authKey); - TextResult result = - deeplClient.translateText("Hello, world!", null, "fr"); - System.out.println(result.getText()); // "Bonjour, le monde !" - } -} -``` - - - -These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable. - -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. - - 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. - - -### Request Body Descriptions - - - Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified multiple times and translations are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences. Up to 50 texts can be sent for translation in one request. - - - Each text in the array is translated independently — texts do not share context with each other. If one text provides context that would help translate another (e.g. a headline and its article body), either combine them into a single text or use the context parameter to provide shared context. - - - - Language of the text to be translated. If omitted, the API will attempt to detect the language of the text and translate it. You can find supported source languages here. - - - The language into which the text should be translated. You can find supported target languages here. - - - The context parameter makes it possible to include additional context that can influence a translation but is not translated itself. This additional context can potentially improve translation quality when translating short, low-context source texts such as product names on an e-commerce website, article headlines on a news website, or UI elements. - -

For example:

- - -

For best results, we recommend sending a few complete sentences of context in the same language as the source text. There is no size limit for the context parameter itself, but the request body size limit of 128 KiB still applies to all text translation requests.

- -

If you send a request with multiple text parameters, the context parameter will be applied to each one.

- -

Characters included in the context parameter will not be counted toward billing (i.e., there is no additional cost for using the context parameter, and only characters sent in the text parameter(s) will be counted toward billing for text translation even when the context parameter is included in a request).

- -

See How to Use the Context Parameter Effectively for examples and best practices.

- - - Specifies which DeepL model should be used for translation. - - Possible values: - - `latency_optimized`: Optimizes for the lowest latency (default parameter value) - - `quality_optimized`: Optimizes for the highest translation quality - - `prefer_quality_optimized`: Same as `quality_optimized` - - When the `model_type` parameter is set, the response includes a `model_type_used` field indicating which model was used. - - See [About the model_type parameter](#about-the-model_type-parameter) for more details. - - - Sets whether the translation engine should first split the input into sentences. For text translations where tag_handling is not set to html, the default value is 1, meaning the engine splits on punctuation and on newlines. - -

For text translations where tag_handling=html, the default value is nonewlines, meaning the engine splits on punctuation only, ignoring newlines.

- -

The use of nonewlines as the default value for text translations where tag_handling=html is new behavior that was implemented in November 2022, when HTML handling was moved out of beta.

- -

Possible values are:

- - -

For applications that send one sentence per text parameter, we recommend setting split_sentences to 0, in order to prevent the engine from splitting the sentence unintentionally.

- -

Please note that newlines will split sentences when split_sentences=1. We recommend cleaning files so they don't contain breaking sentences or setting the parameter split_sentences to nonewlines.

- -

Please note that this value may be overridden by the translation engine. When overridden, a value of:

- - -

...as these settings yield the best quality.

- - - Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. -

The formatting aspects affected by this setting include:

- - - - Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0". - - - - 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:

- - - - Specify the glossary to use for the translation. - - 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. - - Cannot be used together with glossary_ids. - - 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 up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation. - - Important: This requires the source_lang parameter to be set, and every listed glossary must contain a dictionary for the requested language pair. - - Cannot be used together with glossary_id. - - - - 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. - - - - - 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. - - 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. - - - The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). Accepts values from 0 to 100. Default: `75`. - - - When true, the response will include an additional key-value pair with the key billed_characters and a value that is an integer showing the number of characters from the request that will be counted by DeepL for billing purposes. - -

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". - - - - Sets which kind of tags should be handled. Options currently available: - - 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. - - When `tag_handling` is set, the response includes a `tag_handling_version` field showing which version was applied, including the default when you don't specify one. - - - The automatic detection of the XML structure won't yield best results in all XML files. You can disable this automatic mechanism altogether by setting the outline_detection parameter to false and selecting the tags that should be considered structure tags. This will split sentences using the splitting_tags parameter. - -

In the example below, we achieve the same results as the automatic engine by disabling automatic detection with outline_detection=false and setting the parameters manually to tag_handling=xml, split_sentences=nonewlines, and splitting_tags=par,title.

- - ```markup Example request - - - A document's title - - - This is the first sentence. Followed by a second one. - This is the third sentence. - - - ``` - - ```markup Example response - - - Der Titel eines Dokuments - - - Das ist der erste Satz. Gefolgt von einem zweiten. - Dies ist der dritte Satz. - - - ``` - -

While this approach is slightly more complicated, it allows for greater control over the structure of the translation output.

- - - Note: For requests sent as URL-encoded forms, boolean values should be specified as "1" or "0". - - - - Comma-separated list of XML tags which never split sentences. Learn more - - - Comma-separated list of XML tags which always cause splits. Learn more - - - Comma-separated list of XML tags that indicate text not to be translated. Learn more - - - -### About the model\_type parameter - -The `model_type` parameter lets a user specify if they would like to optimize for speed until a request is served (latency) or translation quality. This is done on a best-effort basis by DeepL, not every language pair and feature must behave differently depending on this parameter. -Currently, the DeepL translation API defaults to `latency_optimized` if no `model_type` is included in the request. All features and language pairs are compatible with all `model_type` values. -Note that the API intentionally does not allow the user to specify a model, but rather their goal, so that the DeepL backend can choose the most suitable model for the user (this avoids users constantly having to update their code with new model versions and learning many different models name and their specifics). - -As of December 2025, all source and target languages are supported by next-gen models. Please note that DeepL reserves the right to quietly change which model serves e.g. a `model_type=quality_optimized` request, as long as we think it is a net benefit to the user (e.g. no significant latency increase, but a quality increase, or a significant latency reduction with no or only very slight decrease in quality). - -The `/languages` endpoint has not yet been updated to include information about `model_type` support, but we expect to make such a change in the future. - -### Multiple Sentences - -The translation function will (by default) try to split the text into sentences before translating. Splitting normally works on punctuation marks (e.g. "." or ";"), though you should not assume that every period will be handled as a sentence separator. This means that you can send multiple sentences as a value of the *text* parameter. The translation function will separate the sentences and return the whole translated paragraph. - -In some cases, the sentence splitting functionality may cause issues by splitting sentences where there is actually only one sentence. This is especially the case if you're using special/uncommon character sequences which contain punctuation. In this case, you can disable sentence splitting altogether by setting the parameter *split\_sentences* to *0*. Please note that this will cause overlong sentences to be cut off, as the DeepL API cannot translate overly long sentences. In this case, you should split the sentences manually before submitting them for translation. - - - -The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - -```sh Example request: multiple sentences -curl -X POST 'https://api.deepl.com/v2/translate' \ ---header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ ---header 'Content-Type: application/json' \ ---data '{ - "text": [ - "The table is green. The chair is black." - ], - "target_lang": "DE" -}' -``` - -```json Example response -{ - "translations": [ - { - "detected_source_language": "EN", - "text": "Der Tisch ist grün. Der Stuhl ist schwarz." - } - ] -} -``` - - - -The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - -```http Example request: multiple sentences -POST /v2/translate HTTP/2 -Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] -User-Agent: YourApp/1.2.3 -Content-Length: 71 -Content-Type: application/json - -{"text": ["The table is green. The chair is black."],"target_lang":"DE"} -``` - -```json Example response -{ - "translations": [ - { - "detected_source_language": "EN", - "text": "Der Tisch ist grün. Der Stuhl ist schwarz." - } - ] -} -``` - - - -### Translating Large Volumes of Text - -There are a few methods to translate larger volumes of text: - -* If your text is contiguous, you can submit whole paragraphs to be translated in one request and with one text parameter. Prior to translation, your text will be split into sentences and translated accordingly. -* The translate function can take several text parameters and will return translations of each such parameter separately in the same order as they are requested (see example below). Each of the parameter values may contain multiple sentences. Up to 50 texts can be sent for translation per request. -* You can make parallel requests by calling the translate function from several threads/processes. - - - -The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - -```sh Example request: large volumes of text -curl -X POST 'https://api.deepl.com/v2/translate' \ ---header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ ---header 'Content-Type: application/json' \ ---data '{ - "text": [ - "This is the first sentence.", - "This is the second sentence.", - "This is the third sentence." - ], - "target_lang": "DE" -}' -``` - -```json Example response -{ - "translations": [ - { - "detected_source_language": "EN", - "text": "Das ist der erste Satz." - }, - { - "detected_source_language": "EN", - "text": "Das ist der zweite Satz." - }, - { - "detected_source_language": "EN", - "text": "Dies ist der dritte Satz." - } - ] -} -``` - - - -The example below uses our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. - -```http Example request: large volumes of text -POST /v2/translate HTTP/2 -Host: api.deepl.com -Authorization: DeepL-Auth-Key [yourAuthKey] -User-Agent: YourApp/1.2.3 -Content-Length: 120 -Content-Type: application/json - -{"text":["This is the first sentence.","This is the second sentence.","This is the third sentence."],"target_lang":"DE"} -``` - -```json Example response -{ - "translations": [ - { - "detected_source_language": "EN", - "text": "Das ist der erste Satz." - }, - { - "detected_source_language": "EN", - "text": "Das ist der zweite Satz." - }, - { - "detected_source_language": "EN", - "text": "Dies ist der dritte Satz." - } - ] -} -``` - - - -### In-Text Markup - -You should take precaution with uncommon characters you may have embedded in your texts. Uncommon character sequences, which may be recognized markers within your system, might get translated or removed, resulting in a corrupted structure. In this case, it is advisable to either split the text so that there is no need to send markers, or to convert your markers to XML tags and enable [XML handling](/docs/xml-and-html-handling/xml) or [HTML handling](/docs/xml-and-html-handling/html). diff --git a/api-reference/translate/request-translation.mdx b/api-reference/translate/request-translation.mdx index 88270858..a58724d1 100644 --- a/api-reference/translate/request-translation.mdx +++ b/api-reference/translate/request-translation.mdx @@ -1,5 +1,5 @@ --- openapi: post /v2/translate title: "Translate text" -description: "" +description: "Translate one or more text strings into a target language." --- \ No newline at end of file diff --git a/docs.json b/docs.json index fbf6e412..5e142e97 100644 --- a/docs.json +++ b/docs.json @@ -55,6 +55,7 @@ { "group": "Text Translation", "pages": [ + "docs/learning-how-tos/examples-and-guides/translating-text", "docs/learning-how-tos/examples-and-guides/translation-beginners-guide", "docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter", "docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags", @@ -159,7 +160,6 @@ { "group": "Translate Text", "pages": [ - "api-reference/translate", "api-reference/translate/request-translation" ], "drilldown": false @@ -345,8 +345,14 @@ { "title": "Resources", "items": [ - { "label": "API Status", "href": "https://api-status.deepl.com" }, - { "label": "DeepL Status", "href": "https://www.deeplstatus.com" } + { + "label": "API Status", + "href": "https://api-status.deepl.com" + }, + { + "label": "DeepL Status", + "href": "https://www.deeplstatus.com" + } ] } ], @@ -359,7 +365,9 @@ }, "api": { "examples": { - "languages": ["curl"], + "languages": [ + "curl" + ], "defaults": "required" }, "playground": { @@ -535,6 +543,10 @@ { "source": "/docs/learning-how-tos/cookbook/context-parameter-examples", "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter" + }, + { + "source": "/api-reference/translate", + "destination": "/docs/learning-how-tos/examples-and-guides/translating-text" } ], "integrations": { @@ -576,4 +588,4 @@ } } ] -} \ No newline at end of file +} diff --git a/docs/learning-how-tos/examples-and-guides/translating-text.mdx b/docs/learning-how-tos/examples-and-guides/translating-text.mdx new file mode 100644 index 00000000..114b6b34 --- /dev/null +++ b/docs/learning-how-tos/examples-and-guides/translating-text.mdx @@ -0,0 +1,575 @@ +--- +title: "How to Translate Text" +description: "Send text translation requests to the DeepL API, with examples for glossaries, multiple sentences, large volumes, and in-text markup." +public: true +--- + +The `/v2/translate` endpoint translates one or more text strings into a target language. The examples below use the API Pro endpoint `https://api.deepl.com`. If you're on the API Free plan, use `https://api-free.deepl.com` instead. + +Requests where the source and target language are the same are still counted toward billing. + +For the full parameter reference, see the [Translate text API reference](/api-reference/translate/request-translation). + +## Basic translation + +The examples below show a minimal translation request — with and without a glossary. Use the tabs to switch between cURL, HTTP, and SDK examples. + +In production, load your auth key from an environment variable rather than hard-coding it. + + + +Example request: text translation (without glossary) + +```curl +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key f63c02c5-f056-...' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": [ + "Hello, world!" + ], + "target_lang": "DE" +}' +``` + +Example request: text translation (with glossary) + +```curl +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key f63c02c5-f056-...' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": [ + "Hello, world!" + ], + "target_lang": "DE", + "source_lang": "EN", + "glossary_id": "[yourGlossaryId]" +}' +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Hallo, Welt!" + } + ] +} +``` + + +Example request: text translation (without glossary) + +```http +POST /v2/translate HTTP/2 +Host: api.deepl.com +Authorization: DeepL-Auth-Key f63c02c5-f056-... +User-Agent: YourApp/1.2.3 +Content-Length: 45 +Content-Type: application/json + +{"text":["Hello, world!"],"target_lang":"DE"} +``` + +Example request: text translation (with glossary) + +```http +POST /v2/translate HTTP/2 +Host: api.deepl.com +Authorization: DeepL-Auth-Key f63c02c5-f056-... +User-Agent: YourApp/1.2.3 +Content-Length: 97 +Content-Type: application/json + +{"text":["Hello, world!"],"target_lang":"DE","source_lang":"EN","glossary_id":"[yourGlossaryId]"} +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Hallo, Welt!" + } + ] +} +``` + + +Example request: text translation (without glossary) + +```py +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="DE") +print(result.text) # Output: Hallo, Welt! +``` + +`translate_text()` returns a `TextResult` object. The key fields are: + +- `result.text` — the translated string +- `result.detected_source_lang` — the source language detected by the API (e.g., `"EN"`) + + +Example request: text translation (without glossary) + +```php +$authKey = "f63c02c5-f056-..."; // Replace with your key +$deeplClient = new DeepL\DeepLClient($authKey); + +$result = $deeplClient->translateText('Hello, world!', null, 'de'); +echo $result->text; // Output: Hallo, Welt! +``` + +`translateText()` returns a `TextResult` object. The key fields are: + +- `$result->text` — the translated string +- `$result->detectedSourceLang` — the source language detected by the API (e.g., `"EN"`) + + +Example request: text translation (without glossary) + +```cs +var authKey = "f63c02c5-f056-..."; // Replace with your key +var deeplClient = new DeepLClient(authKey); + +var translatedText = await deeplClient.TranslateTextAsync( + "Hello, world!", + LanguageCode.English, + LanguageCode.German); +Console.WriteLine(translatedText); // Output: Hallo, Welt! +``` + +`TranslateTextAsync()` returns a `TextResult` object. The key fields are: + +- `translatedText.Text` — the translated string +- `translatedText.DetectedSourceLanguageCode` — the source language detected by the API (e.g., `"EN"`) + + +Example request: text translation (without glossary) + +```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, 'de'); + console.log(result.text); // Output: Hallo, Welt! +})(); +``` + +`translateText()` returns a `TextResult` object. The key fields are: + +- `result.text` — the translated string +- `result.detectedSourceLang` — the source language detected by the API (e.g., `"en"`) + + +Example request: text translation (without glossary) + +```java +import com.deepl.api.*; + +class Example { + DeepLClient deeplClient; + + public Example() throws Exception { + String authKey = "f63c02c5-f056-..."; // Replace with your key + deeplClient = new DeepLClient(authKey); + TextResult result = + deeplClient.translateText("Hello, world!", null, "de"); + System.out.println(result.getText()); // Output: Hallo, Welt! + } +} +``` + +`translateText()` returns a `TextResult` object. The key fields are: + +- `result.getText()` — the translated string +- `result.getDetectedSourceLanguage()` — the source language detected by the API (e.g., `"en"`) + + + +For SDK-specific glossary usage, see the [using glossaries guide](/docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world). + +## Optimizing for speed or quality + +Set `model_type` to `latency_optimized` for real-time applications or `quality_optimized` for high-quality batch jobs. This is handled on a best-effort basis — not every language pair or feature will behave differently depending on this setting. When `model_type` is set, the response includes a `model_type_used` field indicating which model was actually used. + + + +Example request: quality-optimized translation + +```curl +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", + "model_type": "quality_optimized" +}' +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Hallo, Welt!", + "model_type_used": "quality_optimized" + } + ] +} +``` + + +Example request: quality-optimized translation + +```http +POST /v2/translate HTTP/2 +Host: api.deepl.com +Authorization: DeepL-Auth-Key [yourAuthKey] +User-Agent: YourApp/1.2.3 +Content-Length: 79 +Content-Type: application/json + +{"text":["Hello, world!"],"target_lang":"DE","model_type":"quality_optimized"} +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Hallo, Welt!", + "model_type_used": "quality_optimized" + } + ] +} +``` + + + + + `prefer_quality_optimized` is a legacy alias for `quality_optimized` and behaves identically. For new integrations, use `quality_optimized` instead. For the full list of accepted values, see the [Translate text API reference](/api-reference/translate/request-translation). + + +## Multiple sentences + +By default, the translation engine splits input text into sentences before translating, using punctuation marks as delimiters. You can send a full paragraph as a single `text` value and the engine will split, translate, and reassemble it automatically. + +In some cases, sentence splitting may produce incorrect results — for example, if your text contains unusual character sequences that include punctuation. You can disable splitting by setting `split_sentences` to `0`. Note that disabling splitting may cause very long sentences to be cut off; if this is a concern, split the sentences manually before sending them. + +To convert between language variants (for example, EN-US to EN-GB), see [Translating Between Language Variants](/docs/learning-how-tos/examples-and-guides/translating-between-variants). Note that translating between variants of the same language returns the text unchanged. + + + +Example request: multiple sentences + +```curl +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": [ + "The table is green. The chair is black." + ], + "target_lang": "DE" +}' +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Der Tisch ist grün. Der Stuhl ist schwarz." + } + ] +} +``` + + +Example request: multiple sentences + +```http +POST /v2/translate HTTP/2 +Host: api.deepl.com +Authorization: DeepL-Auth-Key [yourAuthKey] +User-Agent: YourApp/1.2.3 +Content-Length: 71 +Content-Type: application/json + +{"text": ["The table is green. The chair is black."],"target_lang":"DE"} +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Der Tisch ist grün. Der Stuhl ist schwarz." + } + ] +} +``` + + +Example request: multiple sentences + +```py +import deepl + +auth_key = "f63c02c5-f056-..." # Replace with your key +deepl_client = deepl.DeepLClient(auth_key) + +result = deepl_client.translate_text( + "The table is green. The chair is black.", target_lang="DE" +) +print(result.text) # Output: Der Tisch ist grün. Der Stuhl ist schwarz. +``` + +`translate_text()` returns a `TextResult` object. The key fields are: + +- `result.text` — the translated string +- `result.detected_source_lang` — the source language detected by the API (e.g., `"EN"`) + + +Example request: multiple sentences + +```php +$authKey = "f63c02c5-f056-..."; // Replace with your key +$deeplClient = new DeepL\DeepLClient($authKey); + +$result = $deeplClient->translateText( + 'The table is green. The chair is black.', null, 'de' +); +echo $result->text; // Output: Der Tisch ist grün. Der Stuhl ist schwarz. +``` + + +Example request: multiple sentences + +```cs +var authKey = "f63c02c5-f056-..."; // Replace with your key +var deeplClient = new DeepLClient(authKey); + +var translatedText = await deeplClient.TranslateTextAsync( + "The table is green. The chair is black.", + LanguageCode.English, + LanguageCode.German); +Console.WriteLine(translatedText.Text); +// Output: Der Tisch ist grün. Der Stuhl ist schwarz. +``` + + +Example request: multiple sentences + +```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( + 'The table is green. The chair is black.', null, 'de' + ); + console.log(result.text); + // Output: Der Tisch ist grün. Der Stuhl ist schwarz. +})(); +``` + + +Example request: multiple sentences + +```java +import com.deepl.api.*; + +class Example { + DeepLClient deeplClient; + + public Example() throws Exception { + String authKey = "f63c02c5-f056-..."; // Replace with your key + deeplClient = new DeepLClient(authKey); + TextResult result = deeplClient.translateText( + "The table is green. The chair is black.", null, "de"); + System.out.println(result.getText()); + // Output: Der Tisch ist grün. Der Stuhl ist schwarz. + } +} +``` + + + +## Translating large volumes of text + +There are three strategies for translating larger volumes of text: + +- **Submit whole paragraphs.** If your text is contiguous, send it as a single `text` value. The engine splits it into sentences, translates them, and returns the complete translated paragraph. +- **Use multiple `text` values per request.** A single request can include up to 50 text strings. The API returns translations in the same order they were sent. +- **Make parallel requests.** Call the translate function from multiple threads or processes simultaneously. + +Each request body must not exceed 128 KiB; see the [API reference](/api-reference/translate/request-translation) for full limits. + + + +Example request: multiple text strings + +```curl +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": [ + "This is the first sentence.", + "This is the second sentence.", + "This is the third sentence." + ], + "target_lang": "DE" +}' +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Das ist der erste Satz." + }, + { + "detected_source_language": "EN", + "text": "Das ist der zweite Satz." + }, + { + "detected_source_language": "EN", + "text": "Dies ist der dritte Satz." + } + ] +} +``` + + +Example request: multiple text strings + +```http +POST /v2/translate HTTP/2 +Host: api.deepl.com +Authorization: DeepL-Auth-Key [yourAuthKey] +User-Agent: YourApp/1.2.3 +Content-Length: 120 +Content-Type: application/json + +{"text":["This is the first sentence.","This is the second sentence.","This is the third sentence."],"target_lang":"DE"} +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Das ist der erste Satz." + }, + { + "detected_source_language": "EN", + "text": "Das ist der zweite Satz." + }, + { + "detected_source_language": "EN", + "text": "Dies ist der dritte Satz." + } + ] +} +``` + + +Example request: multiple text strings + +```py +import deepl + +auth_key = "f63c02c5-f056-..." # Replace with your key +deepl_client = deepl.DeepLClient(auth_key) + +results = deepl_client.translate_text( + [ + "This is the first sentence.", + "This is the second sentence.", + "This is the third sentence.", + ], + target_lang="DE", +) +for result in results: + print(result.text) +# Output: +# Das ist der erste Satz. +# Das ist der zweite Satz. +# Dies ist der dritte Satz. +``` + +When a list is passed, `translate_text()` returns a list of `TextResult` objects in the same order as the input strings. + + + +## In-text markup + +Take care with custom markers or delimiters embedded in your text. Unusual character sequences that contain punctuation or symbols may be translated or removed by the engine, corrupting your markup structure. + +If your text contains embedded markers, either strip them out before sending, or convert them to XML or HTML tags and enable [XML handling](/docs/xml-and-html-handling/xml) or [HTML handling](/docs/xml-and-html-handling/html) so the engine preserves them during translation. + +The following example shows how to wrap an embedded marker as an XML tag and use `tag_handling`: `xml` so the engine leaves it untouched. + +Example request: text with embedded marker sent using XML tag handling + +```curl +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": [ + "Please click to continue." + ], + "target_lang": "DE", + "tag_handling": "xml" +}' +``` + +Example response + +```json +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Bitte klicken Sie auf , um fortzufahren." + } + ] +} +``` + +The `` marker is preserved exactly in the translated output. Without `tag_handling`, the engine may translate or drop the marker text entirely. For full details on controlling tag behavior, see the [XML handling](/docs/xml-and-html-handling/xml) and [HTML handling](/docs/xml-and-html-handling/html) pages. \ No newline at end of file