diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx
index b9e96af..92a9653 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..10552fa
--- /dev/null
+++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx
@@ -0,0 +1,134 @@
+---
+title: "Translating Between Language Variants"
+description: "Learn how to translate between language variants, like British English and US English, using the DeepL API."
+public: true
+---
+
+**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
+
+---
+
+## 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"
+}'
+```
+
+```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.
+
+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
+
+Create a reusable [style rule](/api-reference/style-rules) with attached `custom_instructions` describing the desired variant translation.
+
+**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
+
+```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."],
+ "target_lang": "en-GB",
+ "custom_instructions": ["translate to British English"]
+}'
+```
+
+```json Example response
+{
+ "translations": [
+ {
+ "detected_source_language": "EN",
+ "text": "I went to the chemist's."
+ }
+ ]
+}
+```
+
+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
+