Translate text

API reference for translating text with the DeepL API.

The text-translation API currently consists of a single endpoint, translate, which is described below.

To learn more about context in DeepL API translations, we recommend this article.

For more detail about request body parameters, see the Request Body Descriptions section further down on the page.

We also provide a spec that is auto-generated from DeepL's OpenAPI file. You can find it here.

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.

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"
}'

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]"
}'

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.

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"}

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]"}

Example response

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Hallo, Welt!"
    }
  ]
}

Example request: text translation (without glossary)

import deepl

auth_key = "f63c02c5-f056-..."  # Replace with your key
translator = deepl.Translator(auth_key)

result = translator.translate_text("Hello, world!", target_lang="FR")
print(result.text)  # "Bonjour, le monde !"

Example request: text translation (without glossary)

$authKey = "f63c02c5-f056-..."; // Replace with your key
$translator = new \DeepL\Translator($authKey);

$result = $translator->translateText('Hello, world!', null, 'fr');
echo $result->text; // Bonjour, le monde!

Example request: text translation (without glossary)

var authKey = "f63c02c5-f056-..."; // Replace with your key
var translator = new Translator(authKey);

// Translate text into a target language, in this case, French:
var translatedText = await translator.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.

Example request: text translation (without glossary)

import * as deepl from 'deepl-node';

const authKey = "f63c02c5-f056-..."; // Replace with your key
const translator = new deepl.Translator(authKey);

(async () => {
    const result = await translator.translateText('Hello, world!', null, 'fr');
    console.log(result.text); // Bonjour, le monde !
})();

Example request: text translation (without glossary)

import com.deepl.api.*;

class Example {
    Translator translator;

    public Example() throws Exception {
        String authKey = "f63c02c5-f056-...";  // Replace with your key
        translator = new Translator(authKey);
        TextResult result =
                translator.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 for text translation, characters are still counted toward billing when the source and target languages are equal.

Request Body Descriptions

Body parameter

Description

About the model_type parameter

Note that the quality_optimized value for the model_type parameter is currently supported only in the Pro v2 API (https://api.deepl.com/v2/translate).

The behavior of the model_type parameter when the quality_optimized or prefer_quality_optimized values are sent in a request depends on language pairs that are supported by DeepL’s next-gen translation models.

Currently, the following language pairs are supported by next-gen models, and a request will fail (if model_type is set to quality_optimized) or fall back to classic models (if model_type is set to prefer_quality_optimized) if a language pair not on this list is used in the request.

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.

Source languages:

English (EN, all English variants)
German (DE)
Japanese (JA)
Chinese (ZH, all Chinese variants)

Target languages (please note traditional Chinese is not yet supported as a target language):

English (EN-US, EN-GB)
German (DE)
Japanese (JA)
Simplified Chinese (ZH-HANS)

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.

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"
}'

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.

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"}

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.

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"
}'

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.

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"}

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 or HTML handling.

Last updated 4 days ago