Skip to main content
This guide shows you:
  • When to use context (and when not to)
  • How to use context to resolve ambiguous words, genders, or transliterations
  • How to choose between context, Glossaries, and Style Rules

​
What the context parameter is for

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

​
What the context parameter is NOT for

Common Misconception: Many users try to use context like ChatGPT system prompts. This does not work reliably.
The context parameter is not designed for:
  • LLM-style instructions: “Translate with a friendly, casual tone”
  • Translation rules: “Always translate ‘Tor’ as ‘gate’”
  • Cultural context: “Adapt for German cultural norms”
Using context like this will produce unpredictable results. The parameter is optimized for document content, not commands. Instead, try:

​
How to use context for ambiguous words

When a word has multiple meanings, surrounding context helps the translation engine choose the correct interpretation.

​
Example

“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."
}'
Output with context: 
"The person was standing in front of the goal."

​
When to use this approach

  • You’re translating short snippets that lack built-in context
  • The text contains words with multiple meanings
  • The surrounding content makes the intended meaning clear

​
How to use context for grammatical gender

When grammatical gender isn’t clear from the source text, context can provide the necessary clues.

​
Example

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

​
When to use this approach

  • Translating into languages with grammatical gender
  • The source text doesn’t specify gender
  • You have surrounding sentences that contain gender clues

​
How to use context for consistent name translation

When translating names in headlines or short snippets, the same name might be transliterated differently unless additional context is provided.

​
Example

Content is not shared between text parameters. 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."
        }
    ]
}

​
When to use this approach

  • Translating news headlines separately from article bodies
  • Transliterating names with multiple possible spellings in your target language

​
Choosing the right feature for your needs

Different DeepL features solve different problems. Use this table to decide which best suits your use case.
Use CaseContext ParameterGlossariesStyle Rules
Ambiguous words✅❌❌
Consistent gender or spelling✅❌❌
Consistent domain-specific terminology❌✅❌
Brand names❌✅❌
Tone and style❌❌✅
Formatting rules❌❌✅
Translation instructions❌❌✅

​
Technical details

​
Cost

Characters in the context parameter do not count toward billing. Only characters sent in the text parameter are billed.

​
Size limit

There is no size limit for the context parameter itself, but the request body size limit of 128 KiB applies to all text translation requests.

​
Multi-text requests

Content is not shared between multiple text parameters sent in one request. Each text parameter is translated independently. 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.

​
Document translation

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.

​
Tag handling

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.

​
Next steps

Now that you understand the context parameter:
  • Try it yourself: Review the text translation API reference for complete context parameter specifications
  • Enforce terminology: Learn how to use glossaries for consistent translations across all content
  • Control style and tone: Explore style rules for formatting and tone instructions
  • Translate full documents: Understand how document translation automatically handles context