Translate Text

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

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.

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.

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

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

For example: “billed_characters”: 42

• xml: Enable XML tag handling; see XML handling.
• html: Enable HTML tag handling; see HTML handling.

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.

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

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