Skip to content

Commit 2225892

Browse files
kabraham13Kevin Abrahamclaude
authored
docs: glossaries without source_lang on /v2/translate (#478)
* docs: glossaries without source_lang on /v2/translate Text translation accepts glossary_id or glossary_ids without source_lang. DeepL detects the source language and applies the glossary's dictionary for the detected language pair. Document translation still requires source_lang with a glossary. - managing-glossaries: new "Use a glossary without a source language" section with a request and response, the 400 when the detected pair has no dictionary, short-text detection, and using one multilingual glossary - openapi.yaml: update glossary_id and glossary_ids on /v2/translate and the Glossaries tag description; document the 400 for a missing source_lang on the /v2/document glossary_id - document-translations, glossaries-in-the-real-world: align wording - changelog: October 28 entry - openapi.json regenerated from the YAML 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: address review feedback on glossary detection docs - managing-glossaries: rename the section to "Use a glossary with automatic source language detection", state the REST-only, client library and document limits up front instead of in a trailing note, and turn the caveats into a troubleshooting list - state the example's assumption about the glossary entry so it no longer conflicts with the earlier example on the page - openapi.yaml: describe the glossary_id requirement as a dictionary for the language pair of the request (correct for multilingual glossaries), scope the Glossaries tag sentence to documents with a glossary, and document the 400 for glossary_ids on /v2/document - changelog: trim the entry to three bullets and link to the guide - update the anchor in the document translation and changelog links - openapi.json regenerated from the YAML 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Kevin Abraham <kevin.abraham@deepl.com> Co-authored-by: Claude <noreply@anthropic.com>
1 parent bd6584c commit 2225892

6 files changed

Lines changed: 82 additions & 20 deletions

File tree

‎api-reference/openapi.json‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
},
5252
{
5353
"name": "ManageMultilingualGlossaries",
54-
"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."
54+
"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."
5555
},
5656
{
5757
"name": "ManageGlossaries",
@@ -813,12 +813,12 @@
813813
"$ref": "#/components/schemas/ModelType"
814814
},
815815
"glossary_id": {
816-
"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`.",
816+
"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`.",
817817
"type": "string",
818818
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
819819
},
820820
"glossary_ids": {
821-
"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`.",
821+
"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`.",
822822
"type": "array",
823823
"maxItems": 5,
824824
"items": {
@@ -934,12 +934,12 @@
934934
"$ref": "#/components/schemas/ModelType"
935935
},
936936
"glossary_id": {
937-
"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`.",
937+
"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`.",
938938
"type": "string",
939939
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
940940
},
941941
"glossary_ids": {
942-
"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`.",
942+
"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`.",
943943
"type": "array",
944944
"maxItems": 5,
945945
"items": {
@@ -1218,12 +1218,12 @@
12181218
"$ref": "#/components/schemas/Formality"
12191219
},
12201220
"glossary_id": {
1221-
"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`.",
1221+
"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`.",
12221222
"type": "string",
12231223
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
12241224
},
12251225
"glossary_ids": {
1226-
"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`.",
1226+
"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`.",
12271227
"type": "array",
12281228
"maxItems": 5,
12291229
"items": {

‎api-reference/openapi.yaml‎

Lines changed: 30 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,9 @@ tags:
8383
(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).
8484
Dictionaries with target language `EN` can be used in translations with either English variant.
8585
Similarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.
86-
(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.)
86+
(When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied.)
87+
88+
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`.
8789
8890
Glossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.
8991
Please only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website.
@@ -650,9 +652,12 @@ paths:
650652
$ref: '#/components/schemas/ModelType'
651653
glossary_id:
652654
description: |-
653-
Specify the glossary to use for the translation. **Important:** This requires the `source_lang`
654-
parameter to be set. The language pair of the glossary has to match the language pair of the
655-
request.
655+
Specify the glossary to use for the translation. The glossary needs a dictionary for the
656+
language pair of the request.
657+
658+
If `source_lang` is omitted, DeepL detects the source language and uses the dictionary for
659+
the detected language pair. The request returns a `400` if the glossary has no dictionary
660+
for that pair.
656661
657662
Cannot be used together with `glossary_ids`.
658663
type: string
@@ -661,7 +666,11 @@ paths:
661666
description: |-
662667
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.
663668
664-
**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.
669+
Every listed glossary must contain a dictionary for the requested language pair.
670+
671+
If `source_lang` is omitted, DeepL detects the source language and every listed glossary must
672+
contain a dictionary for the detected language pair. A single glossary without a matching
673+
dictionary returns a `400` for the whole request.
665674
666675
Cannot be used together with `glossary_id`.
667676
type: array
@@ -772,9 +781,12 @@ paths:
772781
$ref: '#/components/schemas/ModelType'
773782
glossary_id:
774783
description: |-
775-
Specify the glossary to use for the translation. **Important:** This requires the `source_lang`
776-
parameter to be set. The language pair of the glossary has to match the language pair of the
777-
request.
784+
Specify the glossary to use for the translation. The glossary needs a dictionary for the
785+
language pair of the request.
786+
787+
If `source_lang` is omitted, DeepL detects the source language and uses the dictionary for
788+
the detected language pair. The request returns a `400` if the glossary has no dictionary
789+
for that pair.
778790
779791
Cannot be used together with `glossary_ids`.
780792
type: string
@@ -783,7 +795,11 @@ paths:
783795
description: |-
784796
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.
785797
786-
**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.
798+
Every listed glossary must contain a dictionary for the requested language pair.
799+
800+
If `source_lang` is omitted, DeepL detects the source language and every listed glossary must
801+
contain a dictionary for the detected language pair. A single glossary without a matching
802+
dictionary returns a `400` for the whole request.
787803
788804
Cannot be used together with `glossary_id`.
789805
type: array
@@ -1047,14 +1063,18 @@ paths:
10471063
description: |-
10481064
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.
10491065
1066+
Requires the `source_lang` parameter. The request returns a `400` if `source_lang` is omitted.
1067+
10501068
Cannot be used together with `glossary_ids`.
10511069
type: string
10521070
example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
10531071
glossary_ids:
10541072
description: |-
10551073
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.
10561074
1057-
**Important:** This requires the `source_lang` parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.
1075+
Every listed glossary must contain a dictionary for the requested language pair.
1076+
1077+
Requires the `source_lang` parameter. The request returns a `400` if `source_lang` is omitted.
10581078
10591079
Cannot be used together with `glossary_id`.
10601080
type: array

‎docs/best-practices/document-translations.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ Each supported format has behaviors and constraints worth knowing before you upl
141141
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).
142142

143143
### Using glossaries with documents
144-
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.
144+
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).
145145

146146
### Requesting a quality evaluation
147147
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).

‎docs/customize/glossaries-in-the-real-world.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ acme_glossary = translator.create_glossary(
9595
print(acme_glossary.glossary_id) # "def3a26b-3e84..."
9696
```
9797

98-
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:
98+
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:
9999

100100
```python main.py
101101
import deepl

0 commit comments

Comments
 (0)