Skip to main content
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 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
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"
}'
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 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
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"
}'
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 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
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"]
}'
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: