Skip to main content
POST
/
v2
/
translate
Request Translation
curl --request POST \
  --url https://api.deepl.com/v2/translate \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "text": [
    "Hello, World!"
  ],
  "source_lang": "EN",
  "target_lang": "DE",
  "context": "This is context.",
  "show_billed_characters": true,
  "split_sentences": "1",
  "preserve_formatting": false,
  "formality": "formal",
  "model_type": "quality_optimized",
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "tag_handling": "html",
  "tag_handling_version": "v1",
  "outline_detection": true,
  "enable_beta_languages": false,
  "non_splitting_tags": [
    "non_splitting_tag"
  ],
  "splitting_tags": [
    "splitting_tag"
  ],
  "ignore_tags": [
    "ignore_tag"
  ]
}'
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Hallo, Welt!",
      "billed_characters": 42,
      "model_type_used": "quality_optimized"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Authentication with Authorization header and DeepL-Auth-Key authentication scheme. Example: DeepL-Auth-Key <api-key>

Body

​
text
string[]
required

Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified many times in a single request, within the request size limit (128KiB). Translations are returned in the same order as they are requested.

​
target_lang
enum<string>
required

The language into which the text should be translated.

Available options:
AR,
BG,
CS,
DA,
DE,
EL,
EN-GB,
EN-US,
ES,
ES-419,
ET,
FI,
FR,
HE,
HU,
ID,
IT,
JA,
KO,
LT,
LV,
NB,
NL,
PL,
PT-BR,
PT-PT,
RO,
RU,
SK,
SL,
SV,
TH,
TR,
UK,
VI,
ZH,
ZH-HANS,
ZH-HANT
Example:

"DE"

​
source_lang
enum<string>

Language of the text to be translated. If this parameter is omitted, the API will attempt to detect the language of the text and translate it.

Available options:
AR,
BG,
CS,
DA,
DE,
EL,
EN,
ES,
ET,
FI,
FR,
HU,
ID,
IT,
JA,
KO,
LT,
LV,
NB,
NL,
PL,
PT,
RO,
RU,
SK,
SL,
SV,
TR,
UK,
ZH
Example:

"EN"

​
context
string

Additional context that can influence a translation but is not translated itself.

Characters included in the context parameter will not be counted toward billing.

Example:

"This is context."

​
show_billed_characters
boolean

When true, the response will include the billed_characters parameter, giving the number of characters from the request that will be counted by DeepL for billing purposes.

​
split_sentences
enum<string>
default:1

Sets whether the translation engine should first split the input into sentences.

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
Available options:
0,
1,
nonewlines
Example:

"1"

​
preserve_formatting
boolean
default:false

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

​
formality
enum<string>
default:default

Sets whether the translated text should lean towards formal or informal language. Possible options are:

  • default - use the default formality for the target language
  • formal - for a more formal language
  • informal - for a more informal language
Available options:
default,
formal,
informal
Example:

"formal"

​
model_type
enum<string>

Specifies which DeepL model should be used for translation.

Available options:
quality_optimized,
prefer_quality_optimized,
latency_optimized
​
glossary_id
string

Specify the glossary to use for the translation. Important: This requires the source_lang parameter to be set. The language pair of the glossary has to match the language pair of the request.

Example:

"def3a26b-3e84-45b3-84ae-0c0aaf3525f7"

​
tag_handling
enum<string>

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

  • xml
  • html
Available options:
xml,
html
Example:

"html"

​
tag_handling_version
enum<string>

Sets which version of the tag handling algorithm should be used. Options currently available:

  • v1: Traditional algorithm (currently the default, will become deprecated in the future).
  • v2: Improved algorithm released in October 2025 (will become the default in the future).
Available options:
v1,
v2
​
outline_detection
boolean
default:true

Disable the automatic detection of XML structure 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.

​
enable_beta_languages
boolean
default:false

Enables 75 additional beta languages. See the full list. Note: Any request with the enable_beta_languages parameter enabled will use quality_optimized models. Requests combining enable_beta_languages: true and model_type: latency_optimized will be rejected. Beta languages do not support formality or glossaries.

​
non_splitting_tags
string[]

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

​
splitting_tags
string[]

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

​
ignore_tags
string[]

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

Response

The translate function returns a JSON representation of the translations in the order the text parameters have been specified.

​
translations
object[]
Minimum length: 1