Added guide for translating between language variants

api-reference/translate.mdx

@@ -169,7 +169,7 @@ Note that we do not include examples for our client libraries in every single se
 <Info>
   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.
 </Info>
 
 ### Request Body Descriptions

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"
                 ]
               }
             ]

docs/getting-started/supported-languages.mdx

@@ -5,7 +5,7 @@ public: true
 ---
 
 <Info>
-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).
 </Info>
 
 ### Translation source languages

docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx

@@ -0,0 +1,44 @@
+---
+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](/api-reference/translate/request-translation#body-style-id) parameter.
+
+<Info>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.</Info>
+
+- **[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
+
+``` Example request
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--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
+{
+  "translations": [
+    {
+      "detected_source_language": "EN",
+      "text": "I went to the chemist to get some paracetamol.",
+      "model_type_used": "quality_optimized"
+    }
+  ]
+}
+```
+
+<Tip>The custom instructions convert American English terms ("pharmacy", "acetaminophen") to British English equivalents ("chemist", "paracetamol") while preserving sentence structure.</Tip>
+