Français
DeepL Web TranslatorCreate Free API AccountContact Us

Manage glossaries

API reference for managing glossaries with the DeepL API.

The glossary functions allow you to create, inspect, and delete glossaries. Glossaries created with the glossary function can be used in translate requests by specifying the glossary_id parameter.

The DeepL API supports glossaries in any combination of two languages from the following list, enabling a total of 120 possible glossary language pairs:

  • DA (Danish)

  • DE (German)

  • EN (English)

  • ES (Spanish)

  • FR (French)

  • IT (Italian)

  • JA (Japanese)

  • KO (Korean)

  • NB (Norwegian Bokmål)

  • NL (Dutch)

  • PL (Polish)

  • PT (Portuguese)

  • RO (Romanian)

  • RU (Russian)

  • SV (Swedish)

  • ZH (Chinese)

The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text, as well as the name of the glossary, is limited to 1024 UTF-8 bytes. A total of 1000 glossaries are allowed per account.

When creating a glossary with target language EN or PT, it's not necessary to specify a variant (e.g. EN-US, EN-GB, PT-PT or PT-BR). Glossaries with target language EN can be used in translations with either English variant. Similarly, PT glossaries can be used in translations with either Portuguese variant.

We also provide a spec that is auto-generated from DeepL's OpenAPI file. You can find it here.

Glossaries created via the DeepL API are distinct from glossaries created via the DeepL website and DeepL apps. This means API glossaries cannot be used on the website and vice versa.

Note that glossaries are immutable: once created, the glossary entries for a given glossary ID cannot be modified.

As a workaround for effectively editable glossaries, we suggest to identify glossaries by name instead of ID in your application and then use the following procedure for modifications:

List supported glossary language pairs

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: get glossary language pairs
curl -X GET 'https://api.deepl.com/v2/glossary-language-pairs' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response (partial—one language pair)
{
  "supported_languages": [
    {
      "source_lang": "de",
      "target_lang": "en"
    },
    {
      "source_lang": "en",
      "target_lang": "de"
    }
  ]
}

Create a glossary

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: create a glossary
curl -X POST 'https://api.deepl.com/v2/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My Glossary",
  "source_lang": "en",
  "target_lang": "de",
  "entries": "Hello\tGuten Tag",
  "entries_format": "tsv"
}'
Example response
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "ready": true,
  "name": "My Glossary",
  "source_lang": "en",
  "target_lang": "de",
  "creation_time": "2021-08-03T14:16:18.329Z",
  "entry_count": 1
}

List all glossaries

List all glossaries and their meta-information, but not the glossary entries.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: list all glossaries
curl -X GET 'https://api.deepl.com/v2/glossaries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response
{
  "glossaries": [
    {
      "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
      "name": "My Glossary",
      "ready": true,
      "source_lang": "EN",
      "target_lang": "DE",
      "creation_time": "2021-08-03T14:16:18.329Z",
      "entry_count": 1
    }
  ]
}

Retrieve glossary details

Retrieve meta information for a single glossary, omitting the glossary entries.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: retrieve glossary details
curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
Example response
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "ready": true,
  "name": "My Glossary",
  "source_lang": "en",
  "target_lang": "de",
  "creation_time": "2021-08-03T14:16:18.329Z",
  "entry_count": 1
}

Retrieve glossary entries

List the entries of a single glossary in the format specified by the Accept header.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: retrieve glossary entries
curl -X GET 'https://api.deepl.com/v2/glossaries/{glossary_id}/entries' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Accept: text/tab-separated-values'
Example response
Hello!	Guten Tag!

Delete a glossary

Deletes the specified glossary.

The example below uses our API Pro endpoint https://api.deepl.com. If you're an API Free user, remember to update your requests to use https://api-free.deepl.com instead.

Example request: delete a glossary
curl -X DELETE 'https://api.deepl.com/v2/glossaries/{glossary_id}' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'

Supported Glossary Formats

Common Restrictions for All Glossary Formats

  • duplicate source entries are not allowed,

  • neither source nor target entry may be empty,

  • source and target entries must not contain any C0 or C1 control characters (including, e.g., "\t" or "\n") or any Unicode newline,

  • source and target entries must not contain any leading or trailing Unicode whitespace character.

TSV (Tab-Separated Values)

Entries in TSV format have to be specified as tab-separated values with the "source entry" being the text in the source language of the glossary and the "target entry" being the text in the target language of the glossary.

In addition the following restrictions apply:

  • source/target entry pairs are separated by a newline,

  • source entries and target entries are separated by a tab.

In a programming language with backslash escape sequences (e.g. Python, JavaScript, etc.), valid glossary entries in the TSV format could be created as follows:

"sourceEntry1\ttargetEntry1\nsourceEntry2\ttargetEntry2"

CSV (Comma-Separated Values)

Entries in CSV format have to be specified as comma-separated values in one of the two following ways:

  • source entry,target entry

  • source entry,target entry,source language,target language

with source entry being the text in the source language of the glossary and target entry being the text in the target language of the glossary. If source language and/or target language in the second format do not match the source and/or target language of the glossary, the entry will be ignored.

In addition, the following restrictions apply:

  • Only , (comma) is allowed as a value separator,

  • each field may optionally be enclosed in double quotes,

  • fields containing double quotes or commas must be enclosed in double quotes,

  • if double quotes are used to enclose fields, then a double quote appearing inside a field must be escaped by preceding it with another double quote.

Currently it is not possible to obtain entries in the CSV format. Only the upload of a glossary supports the CSV format.

The example below shows how valid glossary entries in CSV format (using the four-column variant) could be created in a programming language with backslash escape sequences (e.g. Python, JavaScript, etc.):

"sourceEntry1,targetEntry1,en,de\n\"source\"\"Entry\",\"target,Entry\",en,de"

Last updated

Logo

Company

Privacy PolicyPublisher