Custom instructions

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. ❌ INCORRECT: Whole-text restructuring — “Structure the text as a continuous chain: observation, problem framing, definition, implications” ✅ CORRECT: Sentence-level structure — “Split sentences longer than 25 words into two shorter sentences” If you need the translated document restructured, translate it with local instructions only, then restructure the result in a separate step.

​

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”

​

2. Formulate rules positively

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: See Languages supported
• Model compatibility: Custom instructions are compatible with all model_type values.

​

Related documentation

• Text translation API reference
• Document translation API reference
• Working with context
• Style rules API
• Multilingual glossaries