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

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

​
text
array[string]
required

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.

​
source_lang
string

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.

​
target_lang
string
required

The language into which the text should be translated. You can find supported target languages here.

​
context
string

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:

  • When translating a product name, you might pass the product description as context.
  • When translating a news article headline, you might pass the first few sentences or a summary of the article as context.

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

​
model_type
enum

Specifies which DeepL model should be used for translation. The quality_optimized value is supported only in the Pro v2 API at this time (https://api.deepl.com/v2/translate).

Possible values are:

  • latency_optimized (uses lower latency “classic” translation models, which support all language pairs; default value)
  • quality_optimized (uses higher latency, improved quality “next-gen” translation models, which support only a subset of language pairs; if a language pair that is not supported by next-gen models is included in the request, it will fail. Consider using prefer_quality_optimized instead.)
  • prefer_quality_optimized (prioritizes use of higher latency, improved quality “next-gen” translation models, which support only a subset of DeepL languages; if a request includes a language pair not supported by next-gen models, the request will fall back to latency_optimized classic models)

Requests with the model_type parameter will include an additional response field model_type_used to specify whether DeepL’s latency_optimized or quality_optimized model was used for translation.

Note: In the future, if DeepL’s quality optimized models achieve language pair and latency performance parity with classic models, it’s possible that next-gen models will be used regardless of the value passed in the model_type parameter.

Language pairs supported by DeepL’s next-gen models are documented below.

​
split_sentences
string

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:

  • 0 - no splitting at all; whole input is treated as one sentence
  • 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines
  • nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines

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 will be ignored when using next-gen models (model_type_used=quality_optimized) and a value of:

  • 0 will be used if tag_handling is not enabled
  • nonewlines will be used if tag_handling is enabled

…as these settings yield the best quality.

​
preserve_formatting
boolean

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:

  • Punctuation at the beginning and end of the sentence
  • Upper/lower case at the beginning of the sentence

Note: for requests sent as URL-encoded forms, boolean values should be specified as “1” or “0”.

​
formality
string

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:

  • default (default)
  • more - for a more formal language
  • less - for a more informal language
  • prefer_more - for a more formal language if available, otherwise fallback to default formality
  • prefer_less - for a more informal language if available, otherwise fallback to default formality
​
glossary_id
string

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.

​
show_billed_characters
boolean

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”.

​
tag_handling
string

Sets which kind of tags should be handled. Options currently available:

​
outline_detection
boolean

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.

Example request
  <document>
    <meta>
      <title>A document's title</title>
    </meta>
    <content>
      <par>This is the first sentence. Followed by a second one.</par>
      <par>This is the third sentence.</par>
    </content>
  </document>
Example response
  <document>
    <meta>
      <title>Der Titel eines Dokuments</title>
    </meta>
    <content>
      <par>Das ist der erste Satz. Gefolgt von einem zweiten.</par>
      <par>Dies ist der dritte Satz.</par>
    </content>
  </document>

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”.

​
non_splitting_tags
array[string]

Comma-separated list of XML tags which never split sentences. Learn more

​
splitting_tags
array[string]

Comma-separated list of XML tags which always cause splits. Learn more

​
ignore_tags
array[string]

Comma-separated list of XML tags that indicate text not to be translated. Learn more

​
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, all source and target languages are supported by next-gen models. In the future, if we add language pairs that are not supported by next-gen models, 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 the chosen language pair does not support next-gen models.

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.

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

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

​
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.

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

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

​
text
array[string]
required

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.

​
source_lang
string

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.

​
target_lang
string
required

The language into which the text should be translated. You can find supported target languages here.

​
context
string

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:

  • When translating a product name, you might pass the product description as context.
  • When translating a news article headline, you might pass the first few sentences or a summary of the article as context.

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

​
model_type
enum

Specifies which DeepL model should be used for translation. The quality_optimized value is supported only in the Pro v2 API at this time (https://api.deepl.com/v2/translate).

Possible values are:

  • latency_optimized (uses lower latency “classic” translation models, which support all language pairs; default value)
  • quality_optimized (uses higher latency, improved quality “next-gen” translation models, which support only a subset of language pairs; if a language pair that is not supported by next-gen models is included in the request, it will fail. Consider using prefer_quality_optimized instead.)
  • prefer_quality_optimized (prioritizes use of higher latency, improved quality “next-gen” translation models, which support only a subset of DeepL languages; if a request includes a language pair not supported by next-gen models, the request will fall back to latency_optimized classic models)

Requests with the model_type parameter will include an additional response field model_type_used to specify whether DeepL’s latency_optimized or quality_optimized model was used for translation.

Note: In the future, if DeepL’s quality optimized models achieve language pair and latency performance parity with classic models, it’s possible that next-gen models will be used regardless of the value passed in the model_type parameter.

Language pairs supported by DeepL’s next-gen models are documented below.

​
split_sentences
string

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:

  • 0 - no splitting at all; whole input is treated as one sentence
  • 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines
  • nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines

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 will be ignored when using next-gen models (model_type_used=quality_optimized) and a value of:

  • 0 will be used if tag_handling is not enabled
  • nonewlines will be used if tag_handling is enabled

…as these settings yield the best quality.

​
preserve_formatting
boolean

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:

  • Punctuation at the beginning and end of the sentence
  • Upper/lower case at the beginning of the sentence

Note: for requests sent as URL-encoded forms, boolean values should be specified as “1” or “0”.

​
formality
string

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:

  • default (default)
  • more - for a more formal language
  • less - for a more informal language
  • prefer_more - for a more formal language if available, otherwise fallback to default formality
  • prefer_less - for a more informal language if available, otherwise fallback to default formality
​
glossary_id
string

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.

​
show_billed_characters
boolean

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”.

​
tag_handling
string

Sets which kind of tags should be handled. Options currently available:

​
outline_detection
boolean

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.

Example request
  <document>
    <meta>
      <title>A document's title</title>
    </meta>
    <content>
      <par>This is the first sentence. Followed by a second one.</par>
      <par>This is the third sentence.</par>
    </content>
  </document>
Example response
  <document>
    <meta>
      <title>Der Titel eines Dokuments</title>
    </meta>
    <content>
      <par>Das ist der erste Satz. Gefolgt von einem zweiten.</par>
      <par>Dies ist der dritte Satz.</par>
    </content>
  </document>

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”.

​
non_splitting_tags
array[string]

Comma-separated list of XML tags which never split sentences. Learn more

​
splitting_tags
array[string]

Comma-separated list of XML tags which always cause splits. Learn more

​
ignore_tags
array[string]

Comma-separated list of XML tags that indicate text not to be translated. Learn more

​
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, all source and target languages are supported by next-gen models. In the future, if we add language pairs that are not supported by next-gen models, 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 the chosen language pair does not support next-gen models.

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.

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

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

​
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.