From ae91c2e67aa8c7f410f6d4413f8e10a059a37850 Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Tue, 23 Dec 2025 10:38:32 -0600 Subject: [PATCH 1/3] 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/3] 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/3] 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