Manage and use DeepL glossaries
glossaries
endpoints let you work with DeepL glossaries, which let you specify specific translations for words or short phrases. Each glossary contains a mapping of source phrases to target phrases. During translation, DeepL intelligently flexes entries to account for case, gender, tense, and other grammar features (if the target language has flexion).
Currently you can create glossaries with any of the languages DeepL supports. Any updates will be noted here, as well as in the /languages endpoint and documentation.
A glossary contains (several) dictionaries. A dictionary is a mapping of source phrases to target phrases for a single language pair, like this:
French -> | Spanish | |
---|---|---|
belle | hermosa | |
delicieux | exquisito | |
mouse | mouse |
Spanish -> | French | |
---|---|---|
hermosa | belle | |
exquisito | delicieux | |
mouse | mouse |
POST /v3/glossaries
To create a glossary, send the API an array that contains one or more dictionaries. (As described above, a dictionary is a collection of mappings from source phrases in one language to target phrases in another.)
This example creates a modest glossary with two dictionaries. One maps “Hello” in English to “Guten Tag” in German. The other contains the reverse mapping.
POST /v2/translate
To use a glossary in a translation request, include its glossary_id
. You must also specify both the source and target languages, like this:
v3
endpoints only handle glossary methods. Use v2
for all other functionality, including translation.GET /v3/glossaries
Use this endpoint to list all your glossaries, basic information about each glossary’s dictionaries, and each glossary’s name and creation time. The response will not include any dictionary entries.
GET /v3/glossaries/{glossary_id}
Use this endpoint to retrieve basic information about a given glossary’s dictionaries, plus the glossary’s name and creation time.
GET /v3/glossaries/{glossaryId}/entries?source_lang={language}&target_lang={language}
Use this endpoint to retrieve the contents of a single glossary dictionary by specifying the dictionary’s language pair.
Currently you can only retrieve glossary contents in TSV format.
PUT /v3/glossaries/{glossaryId}/dictionaries
The PUT
method acts on a single dictionary of a glossary. It creates a new dictionary in that glossary, or replaces an existing one, without regard to whether that dictionary already exists. If the glossary has no dictionary for a given language pair, add the dictionary to the glossary with the entries provided. If the dictionary already exists, replace it.
Use this method to add a new dictionary to a glossary or replace an existing one. To instead merge a set of entries with an existing dictionary, use the PATCH
method.
PATCH /v3/glossaries/{glossaryId}
While the PUT
method operates on a single dictionary, PATCH
affects an element of an entire glossary. This element could be a piece of metadata - like the glossary’s name - or a dictionary for a particular language pair.
This method returns the glossary’s name and metadata on each of its dictionaries.
For example, this PATCH
changes a glossary’s name.
PATCH
to change the contents of a glossary’s dictionary for a language pair while taking any existing dictionary for that language pair into account. If the glossary already has a dictionary for the specified language pair, the entries passed here will be merged with the existing dictionary.
Use this method to make changes to an existing dictionary. To replace a dictionary outright, use the PUT method.
This example makes two changes. It changes the glossary’s name, and it adds a new entry to its German → English dictionary.
PUT
and PATCH
can make changes to a single dictionary. To change the target phrase for a given source phrase for multiple languages, you need to make multiple API calls. While we work to support multiple dictionaries in future updates, your feedback here is valuable as we work to improve our API.DELETE /v3/glossaries/{glossary_id}
This method deletes the specified glossary in its entirety.
DELETE /v3/glossaries/{glossary_id}/dictionaries?source_lang={source_lang}&target_lang={target_lang}
Use this method to delete a dictionary for a specific language pair.
EN
, that glossary will apply to EN-US
and EN-GB
. A glossary with target language PR
will apply to PT-PT
and PT-BR
.
\t
or \n
) or any Unicode newline.