From acdadca0ee894f8bf8a8b9cca519d76900fdd294 Mon Sep 17 00:00:00 2001 From: Jason Gardella Date: Tue, 7 Jul 2026 08:57:31 -0400 Subject: [PATCH 1/4] docs: remove outdated classic model references from model_type parameter Since the migration to Dynamic Workflows (next-gen), all model_type values route through the same translation pipeline. Remove references to "classic models" and the auto-detect warning that suggested specifying source_lang to use classic models. Co-Authored-By: Claude Opus 4.6 --- api-reference/translate.mdx | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 9fd0d491..b348fb59 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -7,7 +7,7 @@ public: true The text-translation API currently consists of a single endpoint, `translate`, which is described below. -For highest translation quality, we recommend using our next-gen models. For details, please see [here](/api-reference/translate#about-the-model_type-parameter). +For details on model selection, see the [`model_type` parameter](#about-the-model_type-parameter). To learn more about context in DeepL API translations, see our [context parameter guide](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter). @@ -210,16 +210,12 @@ Note that we do not include examples for our client libraries in every single se Specifies which DeepL model should be used for translation. Possible values: - - `latency_optimized`: Uses the lowest latency translation models available (usually classic models; default parameter value) - - `quality_optimized`: Uses the highest quality translation models available (currently next-gen models) - - `prefer_quality_optimized`: Same as `quality_optimized`, with fallback to classic models if no next-gen model is present (as of December 2025, all languages have next-gen models) + - `latency_optimized`: Optimizes for the lowest latency (default parameter value) + - `quality_optimized`: Optimizes for the highest translation quality + - `prefer_quality_optimized`: Same as `quality_optimized` When the `model_type` parameter is set, the response includes a `model_type_used` field indicating which model was used. - - To ensure accurate automatic language detection, the API uses next-gen models for all requests that omit `source_lang`, regardless of `model_type`. If your source language is known, you can specify `source_lang` to allow classic models to be used where available for your language pair. See [supported languages](/docs/getting-started/supported-languages) for language-specific model availability. - - See [About the model_type parameter](#about-the-model_type-parameter) for more details. From 7f961fe331dd0e895bd40ec4a6e17892341fc86d Mon Sep 17 00:00:00 2001 From: Jason Gardella Date: Tue, 7 Jul 2026 10:04:24 -0400 Subject: [PATCH 2/4] docs: update remaining classic/next-gen model references - tag-handling-v2 FAQ: now compatible with all model_type values - split_sentences notes: remove classic vs next-gen distinction - structured-content/html: simplify split_sentences override language - beginners guide: replace outdated "special cases" with general notes Co-Authored-By: Claude Opus 4.6 --- api-reference/translate.mdx | 2 +- .../examples-and-guides/translation-beginners-guide.mdx | 7 +++---- docs/xml-and-html-handling/html.mdx | 2 +- docs/xml-and-html-handling/structured-content.mdx | 4 +--- docs/xml-and-html-handling/tag-handling-v2.mdx | 2 +- 5 files changed, 7 insertions(+), 10 deletions(-) diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index b348fb59..3ec778c8 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -236,7 +236,7 @@ Note that we do not include examples for our client libraries in every single se

Please note that newlines will split sentences when split_sentences=1. We recommend cleaning files so they don't contain breaking sentences or setting the parameter split_sentences to nonewlines.

-

Please note that this value will be ignored when using next-gen models (model_type_used=quality_optimized) and a value of:

+

Please note that this value may be overridden by the translation engine. When overridden, a value of:

  • 0 will be used if tag_handling is not enabled
  • nonewlines will be used if tag_handling is enabled
    • diff --git a/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx b/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx index 4c1670b3..a88f1303 100644 --- a/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx +++ b/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx @@ -817,11 +817,10 @@ Naturally, the API tries to provide excellent translation quality and low latenc If you omit the `model_type`, the API normally defaults to `latency_optimized`. -### Special cases +### Notes -* If your request omits the `source_lang`, the API will use next-generation models to ensure the best possible language detection. -* [tag handling v2](/docs/xml-and-html-handling/tag-handling-v2#whats-new-in-v2) uses next-generation models. It is compatible with all `model_type` values. -* For some languages, like Thai, the API uses the same model, regardless of requested `model_type`. This behavior may change as our models evolve. +* All features and language pairs are compatible with all `model_type` values. +* If your request omits the `source_lang`, the API will choose the most suitable model to ensure accurate language detection. ## Limits diff --git a/docs/xml-and-html-handling/html.mdx b/docs/xml-and-html-handling/html.mdx index c4de23e3..9d4b94e0 100644 --- a/docs/xml-and-html-handling/html.mdx +++ b/docs/xml-and-html-handling/html.mdx @@ -20,7 +20,7 @@ The default value for the `split_sentences` parameter for all requests where `ta The default value `split_sentences` for text translations where `tag_handling` is not set to `html` is `1`, meaning the translation engine splits on punctuation and on newlines. -Please note that for next-gen models, the parameter `split_sentences`passed by the user is ignored and a value of `nonewlines`is used for maximum translation quality. +Please note that the `split_sentences` parameter may be overridden by the translation engine. A value of `nonewlines` is used for maximum translation quality. ### Disable translation of elements diff --git a/docs/xml-and-html-handling/structured-content.mdx b/docs/xml-and-html-handling/structured-content.mdx index 363f2f0a..89cca58a 100644 --- a/docs/xml-and-html-handling/structured-content.mdx +++ b/docs/xml-and-html-handling/structured-content.mdx @@ -5,9 +5,7 @@ description: "Learn how to work with structured XML content with the DeepL API." When enabling `tag_handling` by setting it to `xml`, the DeepL API is able to process structured XML content. This includes whole XML files, as the following example shows. -Please note that for XML structured content in classic models, we set the parameter `split_sentences` to `nonewlines` to make sure that newlines do not alter the results. The response is beautified for better readability. - -Please note that for next-gen models, the parameter `split_sentences`passed by the user is ignored and a value of `nonewlines`is used for maximum translation quality. +Please note that for XML structured content, the `split_sentences` parameter is set to `nonewlines` to ensure that newlines do not alter the results. The response is beautified for better readability. Parameters and corresponding results: diff --git a/docs/xml-and-html-handling/tag-handling-v2.mdx b/docs/xml-and-html-handling/tag-handling-v2.mdx index 2bb2be4e..0e5ab46a 100644 --- a/docs/xml-and-html-handling/tag-handling-v2.mdx +++ b/docs/xml-and-html-handling/tag-handling-v2.mdx @@ -175,7 +175,7 @@ A: Yes, simply set `tag_handling_version: v1` in your API requests. **Q: Does v2 work with all DeepL API features?** -A: Tag handling v2 works with all standard API features including glossaries and formality settings. However, it currently only supports the `quality_optimized` model type. +A: Tag handling v2 works with all standard API features including glossaries and formality settings. It is compatible with all `model_type` values. **Q: Is HTML also strictly parsed?** From b91299ff83fe4835161c79f61f88b6e1f1098c57 Mon Sep 17 00:00:00 2001 From: Jason Gardella Date: Tue, 7 Jul 2026 10:16:30 -0400 Subject: [PATCH 3/4] docs: remove unnecessary auto-detect model note from beginners guide Co-Authored-By: Claude Opus 4.6 --- .../examples-and-guides/translation-beginners-guide.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx b/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx index a88f1303..48337845 100644 --- a/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx +++ b/docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx @@ -820,7 +820,6 @@ If you omit the `model_type`, the API normally defaults to `latency_optimized`. ### Notes * All features and language pairs are compatible with all `model_type` values. -* If your request omits the `source_lang`, the API will choose the most suitable model to ensure accurate language detection. ## Limits From 8f52799bdf20a7d48e8d342c58f7938166c45ac6 Mon Sep 17 00:00:00 2001 From: Jason Gardella Date: Tue, 7 Jul 2026 12:58:18 -0400 Subject: [PATCH 4/4] docs: address review feedback on html.mdx and tag-handling-v2.mdx - html.mdx: clarify split_sentences default for HTML tag handling - tag-handling-v2.mdx: simplify compatibility statement Co-Authored-By: Claude Opus 4.6 --- docs/xml-and-html-handling/html.mdx | 2 +- docs/xml-and-html-handling/tag-handling-v2.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/xml-and-html-handling/html.mdx b/docs/xml-and-html-handling/html.mdx index 9d4b94e0..2699a7f3 100644 --- a/docs/xml-and-html-handling/html.mdx +++ b/docs/xml-and-html-handling/html.mdx @@ -20,7 +20,7 @@ The default value for the `split_sentences` parameter for all requests where `ta The default value `split_sentences` for text translations where `tag_handling` is not set to `html` is `1`, meaning the translation engine splits on punctuation and on newlines. -Please note that the `split_sentences` parameter may be overridden by the translation engine. A value of `nonewlines` is used for maximum translation quality. +Please note that when using HTML tag handling, the `split_sentences` parameter defaults to `nonewlines` for maximum translation quality. ### Disable translation of elements diff --git a/docs/xml-and-html-handling/tag-handling-v2.mdx b/docs/xml-and-html-handling/tag-handling-v2.mdx index 0e5ab46a..4a2fd366 100644 --- a/docs/xml-and-html-handling/tag-handling-v2.mdx +++ b/docs/xml-and-html-handling/tag-handling-v2.mdx @@ -175,7 +175,7 @@ A: Yes, simply set `tag_handling_version: v1` in your API requests. **Q: Does v2 work with all DeepL API features?** -A: Tag handling v2 works with all standard API features including glossaries and formality settings. It is compatible with all `model_type` values. +A: Tag handling v2 works with all standard API features and `model_type`s. **Q: Is HTML also strictly parsed?**