Skip to content

docs: glossaries without source_lang on /v2/translate #478

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kabraham13 merged 2 commits into from
Oct 28, 2026
Merged

docs: glossaries without source_lang on /v2/translate #478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30a80c8
docs: glossaries without source_lang on /v2/translate
Aug 12, 2026
393256f
docs: address review feedback on glossary detection docs
Oct 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
},
{
"name": "ManageMultilingualGlossaries",
"description": "The *glossary* functions allow you to create, inspect, edit and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter. A glossary contains (several) dictionaries.\nA dictionary is a mapping of source phrases to target phrases for a single language pair.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nCurrently you can create glossaries with any of the languages DeepL supports (with the exception of Thai).\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\nWhen creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant\n(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).\nDictionaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.\n(When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.)\n\nGlossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.\nPlease only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website."
"description": "The *glossary* functions allow you to create, inspect, edit and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter. A glossary contains (several) dictionaries.\nA dictionary is a mapping of source phrases to target phrases for a single language pair.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nCurrently you can create glossaries with any of the languages DeepL supports (with the exception of Thai).\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\nWhen creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant\n(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).\nDictionaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.\n(When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied.)\n\nFor text translation, if you omit `source_lang`, DeepL detects the source language and applies the dictionary for the detected language pair. Document translation with a glossary requires `source_lang`.\n\nGlossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.\nPlease only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website."
},
{
"name": "ManageGlossaries",
Expand Down Expand Up @@ -813,12 +813,12 @@
"$ref": "#/components/schemas/ModelType"
},
"glossary_id": {
"description": "Specify the glossary to use for the translation. **Important:** This requires the `source_lang`\nparameter to be set. The language pair of the glossary has to match the language pair of the\nrequest.\n\nCannot be used together with `glossary_ids`.",
"description": "Specify the glossary to use for the translation. The glossary needs a dictionary for the\nlanguage pair of the request.\n\nIf `source_lang` is omitted, DeepL detects the source language and uses the dictionary for\nthe detected language pair. The request returns a `400` if the glossary has no dictionary\nfor that pair.\n\nCannot be used together with `glossary_ids`.",
"type": "string",
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
},
"glossary_ids": {
"description": "Specify up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation.\n\n**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.\n\nCannot be used together with `glossary_id`.",
"description": "Specify up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation.\n\nEvery listed glossary must contain a dictionary for the requested language pair.\n\nIf `source_lang` is omitted, DeepL detects the source language and every listed glossary must\ncontain a dictionary for the detected language pair. A single glossary without a matching\ndictionary returns a `400` for the whole request.\n\nCannot be used together with `glossary_id`.",
"type": "array",
"maxItems": 5,
"items": {
Expand Down Expand Up @@ -934,12 +934,12 @@
"$ref": "#/components/schemas/ModelType"
},
"glossary_id": {
"description": "Specify the glossary to use for the translation. **Important:** This requires the `source_lang`\nparameter to be set. The language pair of the glossary has to match the language pair of the\nrequest.\n\nCannot be used together with `glossary_ids`.",
"description": "Specify the glossary to use for the translation. The glossary needs a dictionary for the\nlanguage pair of the request.\n\nIf `source_lang` is omitted, DeepL detects the source language and uses the dictionary for\nthe detected language pair. The request returns a `400` if the glossary has no dictionary\nfor that pair.\n\nCannot be used together with `glossary_ids`.",
"type": "string",
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
},
"glossary_ids": {
"description": "Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translation. May also be sent as a repeated parameter.\n\n**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.\n\nCannot be used together with `glossary_id`.",
"description": "Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translation. May also be sent as a repeated parameter.\n\nEvery listed glossary must contain a dictionary for the requested language pair.\n\nIf `source_lang` is omitted, DeepL detects the source language and every listed glossary must\ncontain a dictionary for the detected language pair. A single glossary without a matching\ndictionary returns a `400` for the whole request.\n\nCannot be used together with `glossary_id`.",
"type": "array",
"maxItems": 5,
"items": {
Expand Down Expand Up @@ -1218,12 +1218,12 @@
"$ref": "#/components/schemas/Formality"
},
"glossary_id": {
"description": "A unique ID assigned to a glossary. To check glossary support for a language pair, call `GET /v3/languages?resource=translate_document` and verify the `glossary` feature key is present on both the source and target language.\n\nCannot be used together with `glossary_ids`.",
"description": "A unique ID assigned to a glossary. To check glossary support for a language pair, call `GET /v3/languages?resource=translate_document` and verify the `glossary` feature key is present on both the source and target language.\n\nRequires the `source_lang` parameter. The request returns a `400` if `source_lang` is omitted.\n\nCannot be used together with `glossary_ids`.",
"type": "string",
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
},
"glossary_ids": {
"description": "Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translated document. May also be sent as a repeated parameter.\n\n**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.\n\nCannot be used together with `glossary_id`.",
"description": "Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translated document. May also be sent as a repeated parameter.\n\nEvery listed glossary must contain a dictionary for the requested language pair.\n\nRequires the `source_lang` parameter. The request returns a `400` if `source_lang` is omitted.\n\nCannot be used together with `glossary_id`.",
"type": "array",
"maxItems": 5,
"items": {
Expand Down
40 changes: 30 additions & 10 deletions api-reference/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,9 @@ tags:
(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).
Dictionaries with target language `EN` can be used in translations with either English variant.
Similarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.
(When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.)
(When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied.)

For text translation, if you omit `source_lang`, DeepL detects the source language and applies the dictionary for the detected language pair. Document translation with a glossary requires `source_lang`.

Glossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.
Please only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website.
Expand Down Expand Up @@ -650,9 +652,12 @@ paths:
$ref: '#/components/schemas/ModelType'
glossary_id:
description: |-
Specify the glossary to use for the translation. **Important:** This requires the `source_lang`
parameter to be set. The language pair of the glossary has to match the language pair of the
request.
Specify the glossary to use for the translation. The glossary needs a dictionary for the
language pair of the request.

If `source_lang` is omitted, DeepL detects the source language and uses the dictionary for
the detected language pair. The request returns a `400` if the glossary has no dictionary
for that pair.

Cannot be used together with `glossary_ids`.
type: string
Expand All @@ -661,7 +666,11 @@ paths:
description: |-
Specify up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation.

**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.
Every listed glossary must contain a dictionary for the requested language pair.

If `source_lang` is omitted, DeepL detects the source language and every listed glossary must
contain a dictionary for the detected language pair. A single glossary without a matching
dictionary returns a `400` for the whole request.

Cannot be used together with `glossary_id`.
type: array
Expand Down Expand Up @@ -772,9 +781,12 @@ paths:
$ref: '#/components/schemas/ModelType'
glossary_id:
description: |-
Specify the glossary to use for the translation. **Important:** This requires the `source_lang`
parameter to be set. The language pair of the glossary has to match the language pair of the
request.
Specify the glossary to use for the translation. The glossary needs a dictionary for the
language pair of the request.

If `source_lang` is omitted, DeepL detects the source language and uses the dictionary for
the detected language pair. The request returns a `400` if the glossary has no dictionary
for that pair.

Cannot be used together with `glossary_ids`.
type: string
Expand All @@ -783,7 +795,11 @@ paths:
description: |-
Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translation. May also be sent as a repeated parameter.

**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.
Every listed glossary must contain a dictionary for the requested language pair.

If `source_lang` is omitted, DeepL detects the source language and every listed glossary must
contain a dictionary for the detected language pair. A single glossary without a matching
dictionary returns a `400` for the whole request.

Cannot be used together with `glossary_id`.
type: array
Expand Down Expand Up @@ -1047,14 +1063,18 @@ paths:
description: |-
A unique ID assigned to a glossary. To check glossary support for a language pair, call `GET /v3/languages?resource=translate_document` and verify the `glossary` feature key is present on both the source and target language.

Requires the `source_lang` parameter. The request returns a `400` if `source_lang` is omitted.

Cannot be used together with `glossary_ids`.
type: string
example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
glossary_ids:
description: |-
Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translated document. May also be sent as a repeated parameter.

**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.
Every listed glossary must contain a dictionary for the requested language pair.

Requires the `source_lang` parameter. The request returns a `400` if `source_lang` is omitted.

Cannot be used together with `glossary_id`.
type: array
Expand Down
2 changes: 1 addition & 1 deletion docs/best-practices/document-translations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ Each supported format has behaviors and constraints worth knowing before you upl
Translation time depends on document size and server load: small documents typically finish in seconds, larger ones in 1-2 minutes once translation has started. Poll the [status endpoint](/api-reference/document/check-document-status) at regular intervals or with exponential backoff. Treat the `seconds_remaining` field as a rough estimate only; it can be unreliable and occasionally returns implausible values (e.g. 2^27).

### Using glossaries with documents
You can apply a glossary to a document translation with the `glossary_id` parameter (or up to 5 glossaries with `glossary_ids`). This requires the `source_lang` parameter to be set, and the glossary's language pair has to match the language pair of the request.
You can apply a glossary to a document translation with the `glossary_id` parameter (or up to 5 glossaries with `glossary_ids`). Document translation requires the `source_lang` parameter when you use a glossary, and the glossary's language pair has to match the language pair of the request. Text translation doesn't require it. See [Use a glossary with automatic source language detection](/docs/customize/managing-glossaries#use-a-glossary-with-automatic-source-language-detection).

### Requesting a quality evaluation
A quality evaluation is a report on the translation DeepL just produced: for each segment of the document it lists the issues it detected, such as mistranslations, omissions, and fluency or style problems, with a severity and the character range each issue applies to. Use it to target human review at the segments that need it instead of reviewing the whole document. For a product overview, see [About quality evaluation for file translations](https://support.deepl.com/hc/en-us/articles/26360433777436-About-quality-evaluation-for-file-translations).
Expand Down
2 changes: 1 addition & 1 deletion docs/customize/glossaries-in-the-real-world.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ acme_glossary = translator.create_glossary(
print(acme_glossary.glossary_id) # "def3a26b-3e84..."
```

Running `glossary.py` will give us a response containing `glossary_id`, which we can add to our initial translation in `main.py`. Also be aware that when using a glossary, you will also need to include `source_lang` as part of your request:
Running `glossary.py` will give us a response containing `glossary_id`, which we can add to our initial translation in `main.py`. The DeepL client libraries currently require `source_lang` when you use a glossary, so we include it in the request:

```python main.py
import deepl
Expand Down
Loading
Loading