From 30a80c8a38f912600e995af1c2e00b959c049fcd Mon Sep 17 00:00:00 2001 From: Kevin Abraham Date: Wed, 12 Aug 2026 12:26:14 -0400 Subject: [PATCH 1/2] docs: glossaries without source_lang on /v2/translate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- api-reference/openapi.json | 12 +++--- api-reference/openapi.yaml | 38 +++++++++++++----- docs/best-practices/document-translations.mdx | 2 +- .../glossaries-in-the-real-world.mdx | 2 +- docs/customize/managing-glossaries.mdx | 40 ++++++++++++++++++- docs/resources/roadmap-and-release-notes.mdx | 7 ++++ 6 files changed, 83 insertions(+), 18 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 0c71a295..0814b2b8 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -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 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", @@ -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 language pair of the glossary has to\nmatch the language pair of the request.\n\nIf `source_lang` is set, it must match the glossary's source language. If `source_lang` is\nomitted, DeepL detects the source language and applies the glossary's dictionary for the\ndetected language pair. The request returns a `400` if the glossary has no dictionary for\nthat pair. Automatic detection is less reliable on very short text.\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": { @@ -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 language pair of the glossary has to\nmatch the language pair of the request.\n\nIf `source_lang` is set, it must match the glossary's source language. If `source_lang` is\nomitted, DeepL detects the source language and applies the glossary's dictionary for the\ndetected language pair. The request returns a `400` if the glossary has no dictionary for\nthat pair. Automatic detection is less reliable on very short text.\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": { @@ -1218,7 +1218,7 @@ "$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" }, diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index b1cd9fac..77430d32 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -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 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. @@ -650,9 +652,13 @@ 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 language pair of the glossary has to + match the language pair of the request. + + If `source_lang` is set, it must match the glossary's source language. If `source_lang` is + omitted, DeepL detects the source language and applies the glossary's dictionary for the + detected language pair. The request returns a `400` if the glossary has no dictionary for + that pair. Automatic detection is less reliable on very short text. Cannot be used together with `glossary_ids`. type: string @@ -661,7 +667,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 @@ -772,9 +782,13 @@ 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 language pair of the glossary has to + match the language pair of the request. + + If `source_lang` is set, it must match the glossary's source language. If `source_lang` is + omitted, DeepL detects the source language and applies the glossary's dictionary for the + detected language pair. The request returns a `400` if the glossary has no dictionary for + that pair. Automatic detection is less reliable on very short text. Cannot be used together with `glossary_ids`. type: string @@ -783,7 +797,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 @@ -1047,6 +1065,8 @@ 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 diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 33671926..328ca31f 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -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 can omit it: see [use a glossary without a source language](/docs/customize/managing-glossaries#use-a-glossary-without-a-source-language). ### 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). diff --git a/docs/customize/glossaries-in-the-real-world.mdx b/docs/customize/glossaries-in-the-real-world.mdx index df854887..396ccb98 100644 --- a/docs/customize/glossaries-in-the-real-world.mdx +++ b/docs/customize/glossaries-in-the-real-world.mdx @@ -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`. Also be aware that when you use a glossary with the SDKs, you need to include `source_lang` as part of your request: ```python main.py import deepl diff --git a/docs/customize/managing-glossaries.mdx b/docs/customize/managing-glossaries.mdx index f61235d3..4c30fd08 100644 --- a/docs/customize/managing-glossaries.mdx +++ b/docs/customize/managing-glossaries.mdx @@ -97,7 +97,7 @@ curl -X POST https://api.deepl.com/v3/glossaries \ ## Use a glossary in a translation -Include the `glossary_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request. You must also set `source_lang`: glossaries can't yet be used with automatic source language detection. +Include the `glossary_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request. `/v2/document` requires `source_lang` with a glossary. On `/v2/translate` it's optional: see [Use a glossary without a source language](#use-a-glossary-without-a-source-language). ```sh Example request curl -X POST https://api.deepl.com/v2/translate \ @@ -126,6 +126,44 @@ Glossaries apply to root languages, not specific variants: a glossary with targe The `v3` endpoints handle glossary management only; translation itself stays on the `v2` endpoints. +### Use a glossary without a source language + +On [`/v2/translate`](/api-reference/translate/request-translation) you can omit `source_lang`. DeepL detects the source language and applies the glossary's dictionary for the detected language pair. This request has no `source_lang`: + +```sh Example request +curl -X POST https://api.deepl.com/v2/translate \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "text": ["Please send the invoice to the finance team."], + "target_lang": "DE", + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" +}' +``` + +The glossary maps `finance team` to `Buchhaltung`, and the response reports which language DeepL detected: + +```json Example response +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Bitte senden Sie die Rechnung an die Buchhaltung." + } + ] +} +``` + +Keep these points in mind: + +- The glossary must contain a dictionary for the detected source language and your `target_lang`. Otherwise the request returns a `400` and no translation. +- Detection is less reliable on very short text. A single word can be detected as the wrong language, so set `source_lang` where the input can be that short. +- With `glossary_ids`, every listed glossary must contain a dictionary for the detected language pair, and one that doesn't returns a `400` for the whole request. Use one multilingual glossary to cover several source languages: DeepL selects the dictionary that matches the detected language. + + + This applies to text translation through the REST API. Document translation requires `source_lang` when you use a glossary, and the DeepL client libraries currently require it as well, so call the REST API directly to omit it. + + ## Edit a glossary Two methods change an existing glossary, with different semantics: diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index b017910b..8e6f8e54 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -9,6 +9,13 @@ rss: true +## October 28 - Glossaries Without an Explicit Source Language +- [`POST /v2/translate`](/api-reference/translate/request-translation) now accepts `glossary_id` or `glossary_ids` without `source_lang`. Glossaries apply terminology you define to a translation. When you omit `source_lang`, DeepL detects the source language for you, so you don't need to detect it before calling the API. +- When `source_lang` is omitted, DeepL detects the source language and applies the glossary's dictionary for the detected language pair. The `detected_source_language` field in the response reports which language was used. +- The request returns a `400` if the glossary has no dictionary for the detected language pair. With `glossary_ids`, every listed glossary must contain a dictionary for that pair. A multilingual glossary with a dictionary per language pair is the simplest way to cover several source languages. +- Detection is less reliable on very short text, so set `source_lang` explicitly where input can be a few characters long. +- Document translation requires `source_lang` with a glossary. The DeepL client libraries currently require it too, so call the REST API directly to omit it. See [use a glossary without a source language](/docs/customize/managing-glossaries#use-a-glossary-without-a-source-language). + ## October 20 - Style Profiles - A [style profile](/docs/customize/using-style-profiles) bundles the glossaries, style rule lists, and translation memories you use together under a single ID. Pass one `style_profile_id` in [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) requests instead of the individual customization parameters, and update the profile when the bundle changes instead of your integration. - DeepL applies the components that fit each request: the glossaries for the language pair, the style rule list for the target language, and the translation memory for the source language. A profile can't be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold`, or `custom_instructions` in the same request. From 393256fd98acbc64f3e71802c98fba32a3558570 Mon Sep 17 00:00:00 2001 From: Kevin Abraham Date: Wed, 28 Oct 2026 12:12:49 -0400 Subject: [PATCH 2/2] docs: address review feedback on glossary detection docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- api-reference/openapi.json | 8 +++--- api-reference/openapi.yaml | 28 +++++++++---------- docs/best-practices/document-translations.mdx | 2 +- .../glossaries-in-the-real-world.mdx | 2 +- docs/customize/managing-glossaries.mdx | 21 +++++++------- docs/resources/roadmap-and-release-notes.mdx | 8 ++---- 6 files changed, 33 insertions(+), 36 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 0814b2b8..a6a3df79 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -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.)\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 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." + "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", @@ -813,7 +813,7 @@ "$ref": "#/components/schemas/ModelType" }, "glossary_id": { - "description": "Specify the glossary to use for the translation. The language pair of the glossary has to\nmatch the language pair of the request.\n\nIf `source_lang` is set, it must match the glossary's source language. If `source_lang` is\nomitted, DeepL detects the source language and applies the glossary's dictionary for the\ndetected language pair. The request returns a `400` if the glossary has no dictionary for\nthat pair. Automatic detection is less reliable on very short text.\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" }, @@ -934,7 +934,7 @@ "$ref": "#/components/schemas/ModelType" }, "glossary_id": { - "description": "Specify the glossary to use for the translation. The language pair of the glossary has to\nmatch the language pair of the request.\n\nIf `source_lang` is set, it must match the glossary's source language. If `source_lang` is\nomitted, DeepL detects the source language and applies the glossary's dictionary for the\ndetected language pair. The request returns a `400` if the glossary has no dictionary for\nthat pair. Automatic detection is less reliable on very short text.\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" }, @@ -1223,7 +1223,7 @@ "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": { diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 77430d32..f440e20a 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -85,7 +85,7 @@ tags: 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.) - For text translation, if you omit `source_lang`, DeepL detects the source language and applies the dictionary for the detected language pair. Document translation requires `source_lang`. + 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. @@ -652,13 +652,12 @@ paths: $ref: '#/components/schemas/ModelType' glossary_id: description: |- - Specify the glossary to use for the translation. 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 set, it must match the glossary's source language. If `source_lang` is - omitted, DeepL detects the source language and applies the glossary's dictionary for the - detected language pair. The request returns a `400` if the glossary has no dictionary for - that pair. Automatic detection is less reliable on very short text. + 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 @@ -782,13 +781,12 @@ paths: $ref: '#/components/schemas/ModelType' glossary_id: description: |- - Specify the glossary to use for the translation. 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 set, it must match the glossary's source language. If `source_lang` is - omitted, DeepL detects the source language and applies the glossary's dictionary for the - detected language pair. The request returns a `400` if the glossary has no dictionary for - that pair. Automatic detection is less reliable on very short text. + 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 @@ -1074,7 +1072,9 @@ 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 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 diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 328ca31f..c7895ff6 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -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`). 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 can omit it: see [use a glossary without a source language](/docs/customize/managing-glossaries#use-a-glossary-without-a-source-language). +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). diff --git a/docs/customize/glossaries-in-the-real-world.mdx b/docs/customize/glossaries-in-the-real-world.mdx index 396ccb98..28646a6c 100644 --- a/docs/customize/glossaries-in-the-real-world.mdx +++ b/docs/customize/glossaries-in-the-real-world.mdx @@ -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 you use a glossary with the SDKs, you 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 diff --git a/docs/customize/managing-glossaries.mdx b/docs/customize/managing-glossaries.mdx index 4c30fd08..062be8ee 100644 --- a/docs/customize/managing-glossaries.mdx +++ b/docs/customize/managing-glossaries.mdx @@ -97,7 +97,7 @@ curl -X POST https://api.deepl.com/v3/glossaries \ ## Use a glossary in a translation -Include the `glossary_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request. `/v2/document` requires `source_lang` with a glossary. On `/v2/translate` it's optional: see [Use a glossary without a source language](#use-a-glossary-without-a-source-language). +Include the `glossary_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request, along with the `source_lang` of the text. To translate text without setting `source_lang`, see [Use a glossary with automatic source language detection](#use-a-glossary-with-automatic-source-language-detection). ```sh Example request curl -X POST https://api.deepl.com/v2/translate \ @@ -126,9 +126,11 @@ Glossaries apply to root languages, not specific variants: a glossary with targe The `v3` endpoints handle glossary management only; translation itself stays on the `v2` endpoints. -### Use a glossary without a source language +### Use a glossary with automatic source language detection -On [`/v2/translate`](/api-reference/translate/request-translation) you can omit `source_lang`. DeepL detects the source language and applies the glossary's dictionary for the detected language pair. This request has no `source_lang`: +On [`/v2/translate`](/api-reference/translate/request-translation) you can omit `source_lang`: DeepL detects the source language and applies the glossary's dictionary for the detected language pair. This works through the REST API only. The DeepL client libraries currently require `source_lang` with a glossary, and so does document translation. + +This request has no `source_lang`: ```sh Example request curl -X POST https://api.deepl.com/v2/translate \ @@ -141,7 +143,7 @@ curl -X POST https://api.deepl.com/v2/translate \ }' ``` -The glossary maps `finance team` to `Buchhaltung`, and the response reports which language DeepL detected: +This example assumes the glossary's `EN` to `DE` dictionary also contains the entry `finance team` = `Buchhaltung`. The response reports which language DeepL detected: ```json Example response { @@ -154,15 +156,12 @@ The glossary maps `finance team` to `Buchhaltung`, and the response reports whic } ``` -Keep these points in mind: +If a request fails or detection picks the wrong language: -- The glossary must contain a dictionary for the detected source language and your `target_lang`. Otherwise the request returns a `400` and no translation. -- Detection is less reliable on very short text. A single word can be detected as the wrong language, so set `source_lang` where the input can be that short. -- With `glossary_ids`, every listed glossary must contain a dictionary for the detected language pair, and one that doesn't returns a `400` for the whole request. Use one multilingual glossary to cover several source languages: DeepL selects the dictionary that matches the detected language. +- A `400` means the glossary has no dictionary for the detected source language and your `target_lang`. Add the dictionary, or set `source_lang` if detection picked the wrong language. +- Short input, such as a single word, can be detected as the wrong language. Set `source_lang` for short text. See [Language detection](/docs/best-practices/language-detection). - - This applies to text translation through the REST API. Document translation requires `source_lang` when you use a glossary, and the DeepL client libraries currently require it as well, so call the REST API directly to omit it. - +A multilingual glossary can hold a dictionary for each source language, and DeepL uses the one that matches the detected language. With `glossary_ids`, every listed glossary needs a dictionary for the detected language pair, otherwise the whole request returns a `400`. ## Edit a glossary diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 8e6f8e54..9634d31e 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -10,11 +10,9 @@ rss: true ## October 28 - Glossaries Without an Explicit Source Language -- [`POST /v2/translate`](/api-reference/translate/request-translation) now accepts `glossary_id` or `glossary_ids` without `source_lang`. Glossaries apply terminology you define to a translation. When you omit `source_lang`, DeepL detects the source language for you, so you don't need to detect it before calling the API. -- When `source_lang` is omitted, DeepL detects the source language and applies the glossary's dictionary for the detected language pair. The `detected_source_language` field in the response reports which language was used. -- The request returns a `400` if the glossary has no dictionary for the detected language pair. With `glossary_ids`, every listed glossary must contain a dictionary for that pair. A multilingual glossary with a dictionary per language pair is the simplest way to cover several source languages. -- Detection is less reliable on very short text, so set `source_lang` explicitly where input can be a few characters long. -- Document translation requires `source_lang` with a glossary. The DeepL client libraries currently require it too, so call the REST API directly to omit it. See [use a glossary without a source language](/docs/customize/managing-glossaries#use-a-glossary-without-a-source-language). +- [`POST /v2/translate`](/api-reference/translate/request-translation) now accepts `glossary_id` or `glossary_ids` without `source_lang`. Glossaries apply terminology you define to a translation. When you omit `source_lang`, DeepL detects the source language and applies the glossary's dictionary for the detected language pair, and `detected_source_language` in the response reports which one was used. +- The request returns a `400` if the glossary has no dictionary for the detected language pair. +- Document translation still requires `source_lang` with a glossary, and the DeepL client libraries currently require it too. See [use a glossary with automatic source language detection](/docs/customize/managing-glossaries#use-a-glossary-with-automatic-source-language-detection). ## October 20 - Style Profiles - A [style profile](/docs/customize/using-style-profiles) bundles the glossaries, style rule lists, and translation memories you use together under a single ID. Pass one `style_profile_id` in [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) requests instead of the individual customization parameters, and update the profile when the bundle changes instead of your integration.