Managing Glossaries - DeepL Documentation

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. You must also set source_lang: glossaries can’t yet be used 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.

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

​Entry formats

​Create a glossary

​Use a glossary in a translation

​Edit a glossary

​Retrieve glossaries

​Delete glossaries

​Limits and restrictions

Entry formats

Create a glossary

Use a glossary in a translation

Edit a glossary

Retrieve glossaries

Delete glossaries

Limits and restrictions