You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2225892
Browse filesBrowse the repository at this point in the historyBrowse files
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>
Copy file name to clipboardExpand all lines: api-reference/openapi.json
+7-7Lines changed: 7 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -51,7 +51,7 @@
51
51
},
52
52
{
53
53
"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."
55
55
},
56
56
{
57
57
"name": "ManageGlossaries",
@@ -813,12 +813,12 @@
813
813
"$ref": "#/components/schemas/ModelType"
814
814
},
815
815
"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`.",
817
817
"type": "string",
818
818
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
819
819
},
820
820
"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`.",
822
822
"type": "array",
823
823
"maxItems": 5,
824
824
"items": {
@@ -934,12 +934,12 @@
934
934
"$ref": "#/components/schemas/ModelType"
935
935
},
936
936
"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`.",
938
938
"type": "string",
939
939
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
940
940
},
941
941
"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`.",
943
943
"type": "array",
944
944
"maxItems": 5,
945
945
"items": {
@@ -1218,12 +1218,12 @@
1218
1218
"$ref": "#/components/schemas/Formality"
1219
1219
},
1220
1220
"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`.",
1222
1222
"type": "string",
1223
1223
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
1224
1224
},
1225
1225
"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`.",
Copy file name to clipboardExpand all lines: api-reference/openapi.yaml
+30-10Lines changed: 30 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -83,7 +83,9 @@ tags:
83
83
(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).
84
84
Dictionaries with target language `EN` can be used in translations with either English variant.
85
85
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`.
87
89
88
90
Glossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.
89
91
Please only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website.
@@ -650,9 +652,12 @@ paths:
650
652
$ref: '#/components/schemas/ModelType'
651
653
glossary_id:
652
654
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.
656
661
657
662
Cannot be used together with `glossary_ids`.
658
663
type: string
@@ -661,7 +666,11 @@ paths:
661
666
description: |-
662
667
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.
663
668
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.
665
674
666
675
Cannot be used together with `glossary_id`.
667
676
type: array
@@ -772,9 +781,12 @@ paths:
772
781
$ref: '#/components/schemas/ModelType'
773
782
glossary_id:
774
783
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.
778
790
779
791
Cannot be used together with `glossary_ids`.
780
792
type: string
@@ -783,7 +795,11 @@ paths:
783
795
description: |-
784
796
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.
785
797
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.
787
803
788
804
Cannot be used together with `glossary_id`.
789
805
type: array
@@ -1047,14 +1063,18 @@ paths:
1047
1063
description: |-
1048
1064
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.
1049
1065
1066
+
Requires the `source_lang` parameter. The request returns a `400` if `source_lang` is omitted.
1067
+
1050
1068
Cannot be used together with `glossary_ids`.
1051
1069
type: string
1052
1070
example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
1053
1071
glossary_ids:
1054
1072
description: |-
1055
1073
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.
1056
1074
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.
Copy file name to clipboardExpand all lines: docs/best-practices/document-translations.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -141,7 +141,7 @@ Each supported format has behaviors and constraints worth knowing before you upl
141
141
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).
142
142
143
143
### 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).
145
145
146
146
### Requesting a quality evaluation
147
147
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).
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:
0 commit comments