diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 0c71a295..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. 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", @@ -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": { @@ -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": { @@ -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": { diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index b1cd9fac..f440e20a 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 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. @@ -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 @@ -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 @@ -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 @@ -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 @@ -1047,6 +1063,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 @@ -1054,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 33671926..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`). 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). diff --git a/docs/customize/glossaries-in-the-real-world.mdx b/docs/customize/glossaries-in-the-real-world.mdx index df854887..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 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 diff --git a/docs/customize/managing-glossaries.mdx b/docs/customize/managing-glossaries.mdx index f61235d3..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. 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, 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,6 +126,43 @@ 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 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 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 \ + --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" +}' +``` + +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 +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "Bitte senden Sie die Rechnung an die Buchhaltung." + } + ] +} +``` + +If a request fails or detection picks the wrong 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). + +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 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..9634d31e 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -9,6 +9,11 @@ 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 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. - 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.