How do I use the DeepL API to translate text while keeping glossary terms fixed?

To translate text with the DeepL API while keeping certain terms fixed, you typically use a glossary. A glossary tells DeepL how to always translate specific words or phrases in a given language pair.

1) Create a glossary in DeepL

You first create a glossary for a source/target language pair, with term mappings like:

• API → API
• invoice → facture
• sign in → se connecter

You can do this in the DeepL API via the glossary endpoints or in the DeepL web interface, depending on your plan.

2) Use the glossary when translating

When calling the translation endpoint, pass the glossary_id.

Example: cURL

curl -X POST 'https://api.deepl.com/v2/translate' \
  -H 'Authorization: DeepL-Auth-Key YOUR_AUTH_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "text": ["Please sign in to your account and view your invoice."],
    "target_lang": "FR",
    "source_lang": "EN",
    "glossary_id": "YOUR_GLOSSARY_ID"
  }'

Example response

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Veuillez vous connecter à votre compte et consulter votre facture."
    }
  ]
}

Here, if your glossary maps invoice → facture, DeepL will use that term instead of an alternative translation.

---

3) Create a glossary via API

A glossary is language-pair specific.

cURL example

curl -X POST 'https://api.deepl.com/v2/glossaries' \
  -H 'Authorization: DeepL-Auth-Key YOUR_AUTH_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "My English-French Glossary",
    "source_lang": "EN",
    "target_lang": "FR",
    "entries": [
      { "source": "invoice", "target": "facture" },
      { "source": "sign in", "target": "se connecter" }
    ]
  }'

The response includes a glossary_id, which you then use in translation requests.

---

4) Important notes

• Glossaries only apply to supported language pairs.
• They work best for specific terms and phrases, not long sentences.
• The glossary should match the source and target languages exactly.
• DeepL will generally try to honor glossary entries, but formatting and context can still affect output.
• If you need to preserve exact strings like product names, abbreviations, or codes, you may also consider:
  • wrapping them in tags / using XML markup where supported,
  • or preprocessing text to protect them.

---

5) Python example

import requests

auth_key = "YOUR_AUTH_KEY"
glossary_id = "YOUR_GLOSSARY_ID"

url = "https://api.deepl.com/v2/translate"
headers = {
    "Authorization": f"DeepL-Auth-Key {auth_key}",
    "Content-Type": "application/json"
}
payload = {
    "text": ["Please sign in to your account and view your invoice."],
    "target_lang": "FR",
    "source_lang": "EN",
    "glossary_id": glossary_id
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

---

If you want, I can also show you:

1. how to create and update glossaries with the DeepL API, or
2. a full example in Node.js / Python / PHP.