The custom_instructions parameter allows you to provide natural language instructions that customize how the DeepL API translates text. This guide provides best practices for creating effective custom instructions that produce consistent, high-quality results.
What are custom instructions?
Custom instructions enable you to guide the translation engine with specific requirements for your use case. You can use custom instructions to:
- Control tone and style (e.g., “Use a friendly, diplomatic tone”)
- Specify domain-specific terminology preferences
- Define formatting conventions
- Adjust formality levels beyond the standard
formality parameter
- Provide context-specific guidance for specialized content
Custom instructions can also be used in conjunction with other features, such as glossaries, style rules, and the context parameter.
How instructions are applied
Custom instructions are applied while the text is translated, sentence by sentence and passage by passage. They are not applied as an editing pass over the finished document. This makes them effective for local changes, such as word choice, tone, and the structure of individual sentences, and unreliable for changes that depend on seeing the whole text at once.
An instruction that describes the shape of the entire text, such as reordering an argument, converting lists into running text, or adding a summary, is applied to each passage individually. Instead of restructuring the document once, it restructures every passage, which typically lowers translation quality.
Write instructions that apply to the structure of one or more sentences, not to the structure of the entire text.
Best practices
1. Write rules in English or the target language
Custom instructions should be written in either English or the target language. This ensures the translation engine can properly interpret and apply your instructions.
English instruction (works for all target languages) — “Use informal language appropriate for a mobile app”
Target language instruction (French) — “Utiliser un langage informel adapté à une application mobile”
State what the translation should do, rather than what it should not do. Positive formulations are clearer and more effective.
❌ INCORRECT: Negative formulation — “Don’t use overly formal language or avoid casual expressions”
✅ CORRECT: Positive formulation — “Use a conversational, friendly tone”
3. One instruction per rule
Each custom instruction should contain a single, focused directive. This makes your instructions clearer and more predictable.
❌ INCORRECT: Multiple instructions combined — “Use technical terminology, maintain formal tone, and convert measurements to metric”
✅ CORRECT: Separate instructions
- “Use technical terminology appropriate for engineers”
- “Maintain a formal, professional tone”
- “Convert imperial measurements to metric units”
4. Provide details on when and how to apply the rule
Include context about when the rule should be applied and specific guidance on how to apply it.
❌ INCORRECT: Vague instruction — “Handle gender appropriately”
✅ CORRECT: Specific instruction with context — “When translating role titles, use gender-neutral forms where available in the target language”
Elements of a detailed instruction:
- When: Conditions that trigger the rule
- What: Specific elements to modify
- How: Desired behavior or format
5. Avoid too many conditions per rule
Keep conditions simple and focused. Complex conditional logic reduces effectiveness.
❌ INCORRECT: Too many conditions — “If the text contains product names or brand terms, unless they appear in headings or quotes, and the context is marketing material rather than technical documentation, then capitalize all words except articles”
✅ CORRECT: Simplified conditions
- “Capitalize product names and brand terms in marketing content”
- “Preserve original capitalization in technical documentation”
6. Write instructions as translation directives, not chatbot prompts
Custom instructions guide translation behavior. They should be concise directives, not conversational prompts.
❌ INCORRECT: Chatbot-style prompt — “Please translate this text in a way that would be appropriate for a luxury fashion brand. Make sure to sound elegant and sophisticated, like you’re speaking to a high-end clientele.”
✅ CORRECT: Clear translation directive — “Use elegant, sophisticated language appropriate for luxury fashion”
Combining multiple instructions
All active instructions apply to every translation together; there is no priority order among them. However, the broader and more transformative an instruction is, the more strongly it shapes the output. A single instruction that rewrites heavily can drown out the effect of your more specific instructions.
To keep a set of instructions predictable:
- Add instructions one at a time, and test each against representative source texts before adding the next
- Keep each instruction local and specific, following the best practices above
- If translation quality drops after a change, remove the broadest instruction first and retest
Technical constraints
When using custom instructions, keep these constraints in mind:
- Maximum instructions: Up to 10 custom instructions per request
- Character limit: Each instruction can contain a maximum of 300 characters
- Supported target languages:
de, en, es, fr, it, ja, ko, zh, or any variants of these languages
- Model compatibility: Custom instructions are compatible with all
model_type values.
