Skip to content

Commit 16e1ea8

Browse files
shirgoldbirdshirgoldbird
committed
rewrite variants guide with diataxis-style subagent
1 parent 7a339d8 commit 16e1ea8

1 file changed

Lines changed: 102 additions & 14 deletions

File tree

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

Lines changed: 102 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,108 @@
11
---
22
title: "Translating Between Language Variants"
3-
description: "Learn how to translate between variants of the same language, such as en-US to en-GB"
3+
description: "Learn how to translate between language variants, like British English and US English, using the DeepL API."
44
public: true
55
---
66

7-
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:
7+
**This guide shows you:**
8+
- How to translate between language variants (e.g., `en-US` to `en-GB`, `pt-PT` to `pt-BR`)
9+
- Which method to choose: Write API, style rules, or custom instructions
10+
- An example workflow for converting American English to British English
811

9-
- **[Write/Rephrase endpoint](/api-reference/improve-text)**: Rephrases text into the target language variant.
12+
---
13+
14+
## Methods for translating between variants
15+
16+
You can use the DeepL API to translate between variants of the same language using 3 methods:
17+
18+
### 1. DeepL Write API
19+
20+
Use the [/write/rephrase](/api-reference/improve-text) endpoint to rephrase text into the target language variant.
21+
22+
**When to use this:**
23+
- You're translating shorter texts (headlines, product names, brief descriptions)
24+
- You want high-quality rephrasing alongside variant translation
25+
26+
```bash Example cURL request
27+
curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
28+
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
29+
--header 'Content-Type: application/json' \
30+
--data '{
31+
"text": ["Check out the new fall colors!"],
32+
"target_lang": "en-GB"
33+
}'
34+
```
1035

11-
- **[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.
36+
```json Example response
37+
{
38+
"improvements": [
39+
{
40+
"text": "Check out the new autumn colours!",
41+
"detected_source_language": "en",
42+
"target_language": "en-GB"
43+
}
44+
]
45+
}
46+
```
47+
48+
<Warning>
49+
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.
50+
</Warning>
1251

13-
<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>
52+
### 2. Style rules with custom instructions
1453

15-
- **[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.
54+
Create a reusable [style rule](/api-reference/style-rules) with attached `custom_instructions` describing the desired variant translation.
1655

17-
## Example: Converting American English to British English
56+
**When to use this:**
57+
- You need to maintain the text's content between variants as precisely as possible
58+
- You need consistent variant transformations across many translation requests
59+
- You want to reuse the same variant rules without repeating the custom instructions
1860

19-
``` Example request
61+
```bash Example cURL request
2062
curl -X POST 'https://api.deepl.com/v2/translate' \
63+
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
2164
--header 'Content-Type: application/json' \
65+
--data '{
66+
"text": ["I went to the pharmacy."],
67+
"target_lang": "en-GB",
68+
"style_id": "your-style-rule-id"
69+
}'
70+
```
71+
72+
```json Example response
73+
{
74+
"translations": [
75+
{
76+
"detected_source_language": "EN",
77+
"text": "I went to the chemist's."
78+
}
79+
]
80+
}
81+
```
82+
83+
<Info>
84+
Glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them.
85+
86+
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.
87+
</Info>
88+
89+
### 3. Per-request custom instructions
90+
91+
Add [custom_instructions](/api-reference/translate/request-translation#body-custom-instructions) describing the desired variant translation directly into your `/translate` requests.
92+
93+
**When to use this:**
94+
- You need to maintain the text's content between variants as precisely as possible
95+
- You need ad-hoc, one-off translations with specific variant requirements
96+
- You don't want to manage separate style rules
97+
98+
```bash Example cURL request
99+
curl -X POST 'https://api.deepl.com/v2/translate' \
22100
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
101+
--header 'Content-Type: application/json' \
23102
--data '{
24-
"text": ["I went to the pharmacy to get some acetaminophen."],
103+
"text": ["I went to the pharmacy."],
25104
"target_lang": "en-GB",
26-
"model_type": "quality_optimized",
27-
"custom_instructions": ["translate to British English", "only replace words that would be different"]
105+
"custom_instructions": ["translate to British English"]
28106
}'
29107
```
30108

@@ -33,12 +111,22 @@ curl -X POST 'https://api.deepl.com/v2/translate' \
33111
"translations": [
34112
{
35113
"detected_source_language": "EN",
36-
"text": "I went to the chemist to get some paracetamol.",
37-
"model_type_used": "quality_optimized"
114+
"text": "I went to the chemist's."
38115
}
39116
]
40117
}
41118
```
42119

43-
<Tip>The custom instructions convert American English terms ("pharmacy", "acetaminophen") to British English equivalents ("chemist", "paracetamol") while preserving sentence structure.</Tip>
120+
You can specify up to 10 custom instructions per request, each with a maximum of 300 characters.
121+
122+
---
123+
124+
## Next steps
125+
126+
Now that you understand how to translate between language variants:
127+
128+
- **Try it yourself:** Test out style rules and custom instructions in the [text translation API playground](/api-reference/translate)
129+
- **Learn about the Write API:** Explore the [/write/rephrase endpoint](/api-reference/improve-text) for high-quality variant translation and rephrasing
130+
- **Manage reusable rules:** Learn how to create [style rules](/api-reference/style-rules) for systematic variant transformations
131+
- **Improve translation quality:** Understand how [the context parameter](/docs/best-practices/working-with-context) can enhance ambiguous translations
44132

0 commit comments

Comments
 (0)