The context parameter helps DeepL’s API translate ambiguous words and short text snippets more accurately by providing the surrounding content. Think of it like showing a human translator the paragraphs before and after the sentence being translated.The context parameter can help with:
Picking the correct translation for ambiguous words
Providing grammatical clues for gender, number, or case that isn’t clear from the text alone
Improving translations of short snippets such as headlines or product names
“Tor” could mean “gate” or “goal” in German. Without context, DeepL may not know which meaning you intend:
curl -X POST 'https://api.deepl.com/v2/translate' \--header 'Authorization: DeepL-Auth-Key [your key]' \--header 'Content-Type: application/json' \--data '{ "text": [ "Die Person stand vor dem Tor." ], "target_lang": "EN-US"}'
Output without context:
"The person was standing in front of the gate."
If you’re writing about a football game, provide context to clarify:
curl -X POST 'https://api.deepl.com/v2/translate' \--header 'Authorization: DeepL-Auth-Key [your key]' \--header 'Content-Type: application/json' \--data '{ "text": [ "Die Person stand vor dem Tor." ], "target_lang": "EN-US", "context": "Es war ein Fußballspiel."}'
Without context, DeepL may not use the desired gender when translating:
curl -X POST 'https://api.deepl.com/v2/translate' \--header 'Authorization: DeepL-Auth-Key [your key]' \--header 'Content-Type: application/json' \--data '{ "text": [ "The teacher asked the class to tidy up after they finished the lesson." ], "target_lang": "DE"}'
Output without context: (uses masculine form “Lehrer”)
"Der Lehrer bat die Klasse, nach der Stunde aufzuräumen."
You can provide context from the surrounding text that clarifies the teacher’s gender:
curl -X POST 'https://api.deepl.com/v2/translate' \--header 'Authorization: DeepL-Auth-Key [your key]' \--header 'Content-Type: application/json' \--data '{ "text": [ "The teacher asked the class to tidy up after they finished the lesson." ], "target_lang": "DE", "context": "She did not want to tidy up herself."}'
Output with context: (uses feminine form “Lehrerin”)
"Die Lehrerin bat die Klasse, nach der Stunde aufzuräumen."
As noted in the text field reference, each text in the array is translated independently and texts do not share context with each other. This results in different transliterations for the name “Sergej”.
curl -X POST 'https://api.deepl.com/v2/translate' \--header 'Authorization: DeepL-Auth-Key [your key]' \--header 'Content-Type: application/json' \--data '{ "text": [ "Sergej gibt Stellungnahme ab", "Sergej Zhivkov erklärte gestern, dass neue Maßnahmen ergriffen werden." ], "source_lang": "DE", "target_lang": "EN-US"}'
Output without context:
{ "translations": [ { "detected_source_language": "DE", "text": "Sergej makes a statement" }, { "detected_source_language": "DE", "text": "Sergei Zhivkov explained yesterday that new measures will be taken." } ]}
Providing a longer snippet of context containing the complete name results in consistent transliteration:
curl -X POST 'https://api.deepl.com/v2/translate' \--header 'Authorization: DeepL-Auth-Key [your key]' \--header 'Content-Type: application/json' \--data '{ "text": [ "Sergej gibt Stellungnahme ab", "Sergej Zhivkov erklärte gestern, dass neue Maßnahmen ergriffen werden." ], "source_lang": "DE", "target_lang": "EN-US", "context": "Sergej Zhivkov erklärte gestern, dass neue Maßnahmen ergriffen werden."}'
Output with context:
{ "translations": [ { "detected_source_language": "DE", "text": "Sergei issues statement" }, { "detected_source_language": "DE", "text": "Sergei Zhivkov declared yesterday that new measures will be taken." } ]}
The context parameter is one of several ways to influence translation output. For a comparison of context with glossaries, style rules, custom instructions, and translation memories, see Choosing the right feature.
As noted in the text field reference, each text in the array is translated independently — they do not share context with each other.In this example, “Tor” might be translated as “gate” instead of “goal” because the first text doesn’t have access to the second one’s content.
{ "text": [ "Die Person stand vor dem Tor.", "Es war ein Fußballspiel." ], "target_lang": "EN-US"}
To ensure “Tor” is translated as “goal”, you can add additional sentences into the context parameter, or keep related content together in one text parameter.If you send a request with both context and multiple text parameters, the context parameter will be applied to each one.
When using the document translation endpoint, the engine automatically uses the broader document context. You don’t need to provide explicit context for full documents.
When using tag_handling=xml or tag_handling=html, tags are not used as a context boundary. The translation engine automatically looks across all content provided in each text parameter. As with other types of texts, you may need to provide additional context when translating single tags without surrounding content.
