From ae91c2e67aa8c7f410f6d4413f8e10a059a37850 Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Tue, 23 Dec 2025 10:38:32 -0600 Subject: [PATCH 1/7] Add guide for translating between language variants --- api-reference/translate.mdx | 2 +- docs.json | 3 +- docs/getting-started/supported-languages.mdx | 2 +- .../translating-between-variants.mdx | 43 +++++++++++++++++++ 4 files changed, 47 insertions(+), 3 deletions(-) create mode 100644 docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 0be84a8..7db5f9e 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -169,7 +169,7 @@ Note that we do not include examples for our client libraries in every single se Please note that the Translate API is intended to be used for translation between different languages, but requests with the same source and target language are still counted toward billing. - If trying to convert between variants of the same language (e.g. `EN-US` to `EN-GB`), please consider using the [/write/rephrase](/api-reference/improve-text) API instead. Please see [here](/docs/getting-started/supported-languages#text-improvement-languages-deepl-api-for-write) for supported target languages for this use case. Translating between variants of the same language will result in no change to the text. + If trying to convert between variants of the same language (e.g. `EN-US` to `EN-GB`), please refer to [this guide](/docs/learning-how-tos/examples-and-guides/translating-between-variants). Translating between variants of the same language will result in no change to the text. ### Request Body Descriptions diff --git a/docs.json b/docs.json index 759d817..9e65fe7 100644 --- a/docs.json +++ b/docs.json @@ -69,7 +69,8 @@ "docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api", "docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world", "docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications", - "docs/learning-how-tos/examples-and-guides/enable-beta-languages" + "docs/learning-how-tos/examples-and-guides/enable-beta-languages", + "docs/learning-how-tos/examples-and-guides/translating-between-variants" ] } ] diff --git a/docs/getting-started/supported-languages.mdx b/docs/getting-started/supported-languages.mdx index 34e99a7..be4a3bc 100644 --- a/docs/getting-started/supported-languages.mdx +++ b/docs/getting-started/supported-languages.mdx @@ -5,7 +5,7 @@ public: true --- -If trying to convert between variants of the same language (e.g. `EN-US` to `EN-GB`), please consider using the [/write/rephrase](/api-reference/improve-text) API. Please see [here](#text-improvement-languages-deepl-api-for-write) for supported target languages for this use case. +If trying to convert between variants of the same language (e.g. `EN-US` to `EN-GB`), please refer to [this guide](/docs/learning-how-tos/examples-and-guides/translating-between-variants). ### Translation source languages diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx new file mode 100644 index 0000000..40c1a97 --- /dev/null +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -0,0 +1,43 @@ +--- +title: "Translating Between Language Variants" +description: "Learn how to translate between variants of the same language, such as en-US to en-GB" +public: true +--- + +You can use the DeepL API to translate between variants of the same language (for example, `pt-PT` to `pt-BR` or `en-US` to `en-GB`) using several methods: + +- **[Write/Rephrase endpoint](/api-reference/improve-text)**: Rephrases text into the target language variant. + +- **[Style rules](/api-reference/style-rules)**: Create a custom style rule and apply it using the [style_id](https://developers.deepl.com/api-reference/translate/request-translation#body-style-id) parameter. + +Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the api-us.deepl.com endpoint will not be able to access glossaries or style rules created in the UI at this time. + +- **[Custom instructions](/api-reference/translate/request-translation#body-custom-instructions)**: Add instructions like "translate to British English" to your `/translate` request. You can specify up to 10 custom instructions, each with a maximum of 300 characters. + +## Example: Converting American English to British English + +```bash Example request +curl --location 'https://api.deepl.com/v2/translate' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--header 'Accept: application/json' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--data-urlencode 'text=I went to the pharmacy to get some acetaminophen.' \ +--data-urlencode 'target_lang=en-GB' \ +--data-urlencode 'model_type=quality_optimized' \ +--data-urlencode 'custom_instructions=["translate to British English", "only replace words that would be different"]' +``` + +```json Example response +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "I went to the chemist to get some paracetamol.", + "model_type_used": "quality_optimized" + } + ] +} +``` + +The custom instructions convert American English terms ("pharmacy", "acetaminophen") to British English equivalents ("chemist", "paracetamol") while preserving sentence structure. + From e7185a1f7d9f0329a74d908037cb814f9400d338 Mon Sep 17 00:00:00 2001 From: Parvati-DeepL Date: Tue, 23 Dec 2025 10:50:52 -0600 Subject: [PATCH 2/7] Update docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../examples-and-guides/translating-between-variants.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx index 40c1a97..17b5568 100644 --- a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -8,7 +8,7 @@ You can use the DeepL API to translate between variants of the same language (fo - **[Write/Rephrase endpoint](/api-reference/improve-text)**: Rephrases text into the target language variant. -- **[Style rules](/api-reference/style-rules)**: Create a custom style rule and apply it using the [style_id](https://developers.deepl.com/api-reference/translate/request-translation#body-style-id) parameter. +- **[Style rules](/api-reference/style-rules)**: Create a custom style rule and apply it using the [style_id](/api-reference/translate/request-translation#body-style-id) parameter. Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the api-us.deepl.com endpoint will not be able to access glossaries or style rules created in the UI at this time. From 0837a3fc3043401430f99bded426eacec7b68937 Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Wed, 24 Dec 2025 08:37:08 -0600 Subject: [PATCH 3/7] translate-between-variants updated example to json --- .../translating-between-variants.mdx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx index 40c1a97..4fb0dbe 100644 --- a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -16,15 +16,16 @@ You can use the DeepL API to translate between variants of the same language (fo ## Example: Converting American English to British English -```bash Example request -curl --location 'https://api.deepl.com/v2/translate' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ +``` Example request +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Content-Type: application/json' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ ---data-urlencode 'text=I went to the pharmacy to get some acetaminophen.' \ ---data-urlencode 'target_lang=en-GB' \ ---data-urlencode 'model_type=quality_optimized' \ ---data-urlencode 'custom_instructions=["translate to British English", "only replace words that would be different"]' +--data '{ + "text": ["I went to the pharmacy to get some acetaminophen."], + "target_lang": "en-GB", + "model_type": "quality_optimized", + "custom_instructions": ["translate to British English", "only replace words that would be different"] +}' ``` ```json Example response From 16e1ea88699b4deef40fe24e4a4dcda28297b8fa Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Wed, 7 Jan 2026 13:53:26 -0500 Subject: [PATCH 4/7] rewrite variants guide with diataxis-style subagent --- .../translating-between-variants.mdx | 116 +++++++++++++++--- 1 file changed, 102 insertions(+), 14 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx index 3bfd654..b225e0e 100644 --- a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -1,30 +1,108 @@ --- title: "Translating Between Language Variants" -description: "Learn how to translate between variants of the same language, such as en-US to en-GB" +description: "Learn how to translate between language variants, like British English and US English, using the DeepL API." public: true --- -You can use the DeepL API to translate between variants of the same language (for example, `pt-PT` to `pt-BR` or `en-US` to `en-GB`) using several methods: +**This guide shows you:** +- How to translate between language variants (e.g., `en-US` to `en-GB`, `pt-PT` to `pt-BR`) +- Which method to choose: Write API, style rules, or custom instructions +- An example workflow for converting American English to British English -- **[Write/Rephrase endpoint](/api-reference/improve-text)**: Rephrases text into the target language variant. +--- + +## Methods for translating between variants + +You can use the DeepL API to translate between variants of the same language using 3 methods: + +### 1. DeepL Write API + +Use the [/write/rephrase](/api-reference/improve-text) endpoint to rephrase text into the target language variant. + +**When to use this:** +- You're translating shorter texts (headlines, product names, brief descriptions) +- You want high-quality rephrasing alongside variant translation + +```bash Example cURL request +curl -X POST 'https://api.deepl.com/v2/write/rephrase' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": ["Check out the new fall colors!"], + "target_lang": "en-GB" +}' +``` -- **[Style rules](/api-reference/style-rules)**: Create a custom style rule and apply it using the [style_id](/api-reference/translate/request-translation#body-style-id) parameter. +```json Example response +{ + "improvements": [ + { + "text": "Check out the new autumn colours!", + "detected_source_language": "en", + "target_language": "en-GB" + } + ] +} +``` + + +For longer texts, the Write API may rephrase and enhance content beyond simple variant conversion. If you need to maintain the exact structure while only updating locale-specific spelling and grammar, use another method. + -Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the api-us.deepl.com endpoint will not be able to access glossaries or style rules created in the UI at this time. +### 2. Style rules with custom instructions -- **[Custom instructions](/api-reference/translate/request-translation#body-custom-instructions)**: Add instructions like "translate to British English" to your `/translate` request. You can specify up to 10 custom instructions, each with a maximum of 300 characters. +Create a reusable [style rule](/api-reference/style-rules) with attached `custom_instructions` describing the desired variant translation. -## Example: Converting American English to British English +**When to use this:** +- You need to maintain the text's content between variants as precisely as possible +- You need consistent variant transformations across many translation requests +- You want to reuse the same variant rules without repeating the custom instructions -``` Example request +```bash Example cURL request curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ --header 'Content-Type: application/json' \ +--data '{ + "text": ["I went to the pharmacy."], + "target_lang": "en-GB", + "style_id": "your-style-rule-id" +}' +``` + +```json Example response +{ + "translations": [ + { + "detected_source_language": "EN", + "text": "I went to the chemist's." + } + ] +} +``` + + +Glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. + +Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time. + + +### 3. Per-request custom instructions + +Add [custom_instructions](/api-reference/translate/request-translation#body-custom-instructions) describing the desired variant translation directly into your `/translate` requests. + +**When to use this:** +- You need to maintain the text's content between variants as precisely as possible +- You need ad-hoc, one-off translations with specific variant requirements +- You don't want to manage separate style rules + +```bash Example cURL request +curl -X POST 'https://api.deepl.com/v2/translate' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ --data '{ - "text": ["I went to the pharmacy to get some acetaminophen."], + "text": ["I went to the pharmacy."], "target_lang": "en-GB", - "model_type": "quality_optimized", - "custom_instructions": ["translate to British English", "only replace words that would be different"] + "custom_instructions": ["translate to British English"] }' ``` @@ -33,12 +111,22 @@ curl -X POST 'https://api.deepl.com/v2/translate' \ "translations": [ { "detected_source_language": "EN", - "text": "I went to the chemist to get some paracetamol.", - "model_type_used": "quality_optimized" + "text": "I went to the chemist's." } ] } ``` -The custom instructions convert American English terms ("pharmacy", "acetaminophen") to British English equivalents ("chemist", "paracetamol") while preserving sentence structure. +You can specify up to 10 custom instructions per request, each with a maximum of 300 characters. + +--- + +## Next steps + +Now that you understand how to translate between language variants: + +- **Try it yourself:** Test out style rules and custom instructions in the [text translation API playground](/api-reference/translate) +- **Learn about the Write API:** Explore the [/write/rephrase endpoint](/api-reference/improve-text) for high-quality variant translation and rephrasing +- **Manage reusable rules:** Learn how to create [style rules](/api-reference/style-rules) for systematic variant transformations +- **Improve translation quality:** Understand how [the context parameter](/docs/best-practices/working-with-context) can enhance ambiguous translations From 3585cf4b57a5cdb16dab4d691283225185fa6d56 Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Wed, 7 Jan 2026 13:23:59 -0600 Subject: [PATCH 5/7] added disclaimers --- .../translating-between-variants.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx index 3bfd654..21a0577 100644 --- a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -4,15 +4,19 @@ description: "Learn how to translate between variants of the same language, such public: true --- -You can use the DeepL API to translate between variants of the same language (for example, `pt-PT` to `pt-BR` or `en-US` to `en-GB`) using several methods: +The DeepL API can translate between variants of the same language (for example, from pt-PT to pt-BR or from en-US to en-GB) using a few methods: -- **[Write/Rephrase endpoint](/api-reference/improve-text)**: Rephrases text into the target language variant. +- **[Write/Rephrase endpoint](/api-reference/improve-text)**: Rephrases text into the target language variant. This method is fully supported. -- **[Style rules](/api-reference/style-rules)**: Create a custom style rule and apply it using the [style_id](/api-reference/translate/request-translation#body-style-id) parameter. + +While preliminary testing has yielded positive results for the methods outlined below, please note that they are not fully supported and may not always perform as intended. We encourage you to conduct your own evaluations tailored to your specific use case. -Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the api-us.deepl.com endpoint will not be able to access glossaries or style rules created in the UI at this time. +Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the api-us.deepl.com endpoint will not be able to access glossaries or style rules created in the UI at this time. + -- **[Custom instructions](/api-reference/translate/request-translation#body-custom-instructions)**: Add instructions like "translate to British English" to your `/translate` request. You can specify up to 10 custom instructions, each with a maximum of 300 characters. +- **[Style rules](/api-reference/style-rules)**: Create a custom style rule in the UI such as “translate to British English” and apply it using the [style_id](/api-reference/translate/request-translation#body-style-id) parameter. + +- **[Custom instructions](/api-reference/translate/request-translation#body-custom-instructions)**: Add instructions like "translate to British English" to your `/translate` request. You can specify up to 10 custom instructions in conjunction, each with a maximum of 300 characters. ## Example: Converting American English to British English From f215c295fdf151ed96d9013071fba2cfad8f34be Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Thu, 8 Jan 2026 15:12:19 -0600 Subject: [PATCH 6/7] updated per claude subagent readme --- .../translating-between-variants.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx index 21a0577..5b13feb 100644 --- a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -9,7 +9,7 @@ The DeepL API can translate between variants of the same language (for example, - **[Write/Rephrase endpoint](/api-reference/improve-text)**: Rephrases text into the target language variant. This method is fully supported. -While preliminary testing has yielded positive results for the methods outlined below, please note that they are not fully supported and may not always perform as intended. We encourage you to conduct your own evaluations tailored to your specific use case. +Please note that currently, the methods outlined below are not fully supported for this use case and may not always perform as intended. We encourage you to conduct your own evaluations. Both glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using the api-us.deepl.com endpoint will not be able to access glossaries or style rules created in the UI at this time. @@ -18,9 +18,10 @@ Both glossaries and style rules are unique to each of DeepL's global data center - **[Custom instructions](/api-reference/translate/request-translation#body-custom-instructions)**: Add instructions like "translate to British English" to your `/translate` request. You can specify up to 10 custom instructions in conjunction, each with a maximum of 300 characters. -## Example: Converting American English to British English +## Example: Converting American English to British English using the custom_instructions parameter: -``` Example request +Example request +```bash curl -X POST 'https://api.deepl.com/v2/translate' \ --header 'Content-Type: application/json' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ @@ -32,7 +33,8 @@ curl -X POST 'https://api.deepl.com/v2/translate' \ }' ``` -```json Example response +Example response +```json { "translations": [ { From 933ad29e3fa32ee3f5eb2b20f82699f0710da399 Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Thu, 8 Jan 2026 15:28:42 -0600 Subject: [PATCH 7/7] updated to include Shir's commit and disclaimer --- .../examples-and-guides/translating-between-variants.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx index b225e0e..10552fa 100644 --- a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -47,6 +47,8 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \ For longer texts, the Write API may rephrase and enhance content beyond simple variant conversion. If you need to maintain the exact structure while only updating locale-specific spelling and grammar, use another method. + +Please note that currently, the methods outlined below are not fully supported for this use case and may not always perform as intended. We encourage you to conduct your own evaluations. ### 2. Style rules with custom instructions