Managing Glossaries

Glossaries let you specify exact translations for words and short phrases. During translation, DeepL intelligently flexes entries to account for case, gender, tense, and other grammar features when the target language has flexion. This guide shows how to manage glossaries programmatically with the v3 glossary endpoints and apply them in translations. A glossary contains one or more dictionaries. A dictionary maps source phrases to target phrases for a single language pair, in one direction:

French →	Spanish
belle	hermosa
delicieux	exquisito

To apply the same terminology in both directions, add a second dictionary with the reverse mapping (Spanish → French). You can create dictionaries for any language that supports glossaries; to check programmatically, call GET /v3/languages?resource=glossary.

If you’re new to glossaries, start with Glossaries in the Real World, a hands-on tutorial that builds one from scratch.

Entry formats

Glossary entries are formatted as CSV (comma-separated values) or TSV (tab-separated values), one entry per line, source phrase first:

CSV entries

hermosa,belle
exquisito,delicieux

You can also enclose each phrase in quotation marks. CSV entries follow standard CSV conventions:

Fields containing double quotes or commas must be enclosed in double quotes
A double quote inside a quoted field is escaped by doubling it ("")

TSV is identical except that a tab separates the source and target phrases. In CSV, you can optionally append the source and target language after the phrases; entries whose languages don’t match the dictionary’s language pair are ignored.

Create a glossary

Send POST /v3/glossaries an array of one or more dictionaries. This example creates a glossary with an English → German dictionary and its reverse:

Example request

curl -X POST https://api.deepl.com/v3/glossaries \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "My Glossary",
    "dictionaries": [
      {
        "source_lang": "en",
        "target_lang": "de",
        "entries": "Hello\tGuten Tag",
        "entries_format": "tsv"
      },
      {
        "source_lang": "de",
        "target_lang": "en",
        "entries": "Guten Tag\tHello",
        "entries_format": "tsv"
      }
    ]
}'

Example response

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "ready": true,
  "name": "My Glossary",
  "dictionaries": [
    { "source_lang": "en", "target_lang": "de", "entry_count": 1 },
    { "source_lang": "de", "target_lang": "en", "entry_count": 1 }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

To create a glossary from an existing CSV file on the command line, use jq to embed the file contents in the request body:

Create a glossary from a CSV file

curl -X POST https://api.deepl.com/v3/glossaries \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data "$(jq -Rs '{
    "name": "My Glossary",
    "dictionaries": [
      {
        "source_lang": "en",
        "target_lang": "de",
        "entries": .,
        "entries_format": "csv"
      }
    ]
  }' glossary.csv)"

Use a glossary in a translation

Include the glossary_id in a /v2/translate or /v2/document request, along with the source_lang of the text. To translate text without setting source_lang, see Use a glossary with automatic source language detection.

Example request

curl -X POST https://api.deepl.com/v2/translate \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": ["Hello"],
    "source_lang": "EN",
    "target_lang": "DE",
    "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
}'

Example response

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Guten Tag"
    }
  ]
}

Glossaries apply to root languages, not specific variants: a glossary with target language EN applies when translating into EN-US and EN-GB alike, and must be created with the root code. See How to Apply Customizations to Language Variants. The v3 endpoints handle glossary management only; translation itself stays on the v2 endpoints.

Use a glossary with automatic source language detection

On /v2/translate you can omit source_lang: DeepL detects the source language and applies the glossary’s dictionary for the detected language pair. This works through the REST API only. The DeepL client libraries currently require source_lang with a glossary, and so does document translation. This request has no source_lang:

Example request

curl -X POST https://api.deepl.com/v2/translate \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": ["Please send the invoice to the finance team."],
    "target_lang": "DE",
    "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
}'

This example assumes the glossary’s EN to DE dictionary also contains the entry finance team = Buchhaltung. The response reports which language DeepL detected:

Example response

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Bitte senden Sie die Rechnung an die Buchhaltung."
    }
  ]
}

If a request fails or detection picks the wrong language:

A 400 means the glossary has no dictionary for the detected source language and your target_lang. Add the dictionary, or set source_lang if detection picked the wrong language.
Short input, such as a single word, can be detected as the wrong language. Set source_lang for short text. See Language detection.

A multilingual glossary can hold a dictionary for each source language, and DeepL uses the one that matches the detected language. With glossary_ids, every listed glossary needs a dictionary for the detected language pair, otherwise the whole request returns a 400.

Edit a glossary

Two methods change an existing glossary, with different semantics:

Method	Scope	Behavior
`PUT /v3/glossaries/{id}/dictionaries`	One dictionary	Creates the dictionary for the given language pair, or replaces it entirely if it exists
`PATCH /v3/glossaries/{id}`	Whole glossary	Updates metadata like the name; entries passed for a language pair are merged into the existing dictionary

For example, this PATCH renames a glossary and adds one entry to its English → German dictionary, keeping existing entries:

Example request

curl -X PATCH https://api.deepl.com/v3/glossaries/def3a26b-3e84-45b3-84ae-0c0aaf3525f7 \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Gertrude the glossary",
    "dictionaries": [{
      "source_lang": "en",
      "target_lang": "de",
      "entries": "Goodbye\tTschüß",
      "entries_format": "tsv"
    }]
}'

A single PUT or PATCH can change one dictionary. To change the same source phrase across multiple language pairs, make one call per dictionary.

Retrieve glossaries

GET /v3/glossaries lists all your glossaries with per-dictionary metadata (no entries)
GET /v3/glossaries/{id} returns one glossary’s metadata
GET /v3/glossaries/{id}/entries returns the entries of a single dictionary, selected via source_lang and target_lang query parameters. Entries are currently returned in TSV format only.

To retrieve the contents of an entire glossary, iterate over its dictionaries and fetch each one’s entries.

Delete glossaries

DELETE /v3/glossaries/{id} deletes the whole glossary
DELETE /v3/glossaries/{id}/dictionaries?source_lang=...&target_lang=... deletes a single dictionary

Limits and restrictions

Each dictionary can contain up to 10 MB of entries; a glossary with five dictionaries can hold up to 50 MB in total
The glossary name, each source phrase, and each target phrase can contain up to 1024 UTF-8 bytes
Duplicate source entries are not allowed, and neither source nor target may be empty
Entries must not contain control characters (such as \t or \n inside a phrase), Unicode newlines, or leading/trailing whitespace
The number of glossaries per account is limited by your plan

Glossaries

Style Rules

Spoken Terms

Translation Memories

Style Profiles

Entry formats

Create a glossary

Use a glossary in a translation

Use a glossary with automatic source language detection

Edit a glossary

Retrieve glossaries

Delete glossaries

Limits and restrictions

​Entry formats

​Create a glossary

​Use a glossary in a translation

​Use a glossary with automatic source language detection

​Edit a glossary

​Retrieve glossaries

​Delete glossaries

​Limits and restrictions

Entry formats

Create a glossary

Use a glossary in a translation

Use a glossary with automatic source language detection

Edit a glossary

Retrieve glossaries

Delete glossaries

Limits and restrictions