From f4694cc368c156a6d6073380c877d0732fdf6ee8 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Tue, 28 Jul 2026 16:13:15 -0400 Subject: [PATCH] Explain instruction scope and combining rules in the custom instructions guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Customers writing whole-text structural instructions (reorder the argument, convert lists to prose) see translation quality drop and don't understand why. Document that instructions are applied per passage rather than as an editing pass over the finished document, that sentence-level scope is the intended use, and how multiple instructions interact, with good/bad structural examples. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/customize/custom-instructions.mdx | 26 ++++++++++++++++++++++++++ docs/customize/using-style-rules.mdx | 2 +- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/customize/custom-instructions.mdx b/docs/customize/custom-instructions.mdx index dfbccc20..37dc3f71 100644 --- a/docs/customize/custom-instructions.mdx +++ b/docs/customize/custom-instructions.mdx @@ -18,6 +18,22 @@ Custom instructions enable you to guide the translation engine with specific req 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. + + +❌ **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 @@ -78,6 +94,16 @@ Custom instructions guide translation behavior. They should be concise directive ✅ **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: diff --git a/docs/customize/using-style-rules.mdx b/docs/customize/using-style-rules.mdx index b7c293e0..fa2ac38f 100644 --- a/docs/customize/using-style-rules.mdx +++ b/docs/customize/using-style-rules.mdx @@ -72,7 +72,7 @@ curl -X POST https://api.deepl.com/v3/style_rules \ } ``` -The `version` field increments each time the list is modified, so you can track changes to your style rules. See the [endpoint reference](/api-reference/style-rules/create-style-rule) for all available configured rule categories and options, and the [custom instructions guide](/docs/customize/custom-instructions) for how to write instructions that work well. +The `version` field increments each time the list is modified, so you can track changes to your style rules. See the [endpoint reference](/api-reference/style-rules/create-style-rule) for all available configured rule categories and options, and the [custom instructions guide](/docs/customize/custom-instructions) for how to write instructions that work well and which kinds of changes they're suited for. ## Apply style rules to a translation