MVP version of new style rules guide by morsssss · Pull Request #313 · DeepLcom/api-docs

morsssss · 2026-04-23T01:39:22Z

Comes with a diagram in light and dark modes
Eventually we'll flesh this out with instructions and code samples for using the other style rule list methods.

Comes with light and dark mode versions of a diagram

mintlify · 2026-04-23T01:39:28Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
deepl-c950b784	🟢 Ready	View Preview	Apr 23, 2026, 1:40 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Copilot

Pull request overview

Adds an MVP documentation guide for DeepL style rules and custom instructions, including a light/dark diagram, plus navigation wiring.

Changes:

Introduces a comprehensive “Style rules and custom instructions” guide with multi-language examples and a diagram.
Adds a shorter “How to Use Custom Instructions and Style Rules” how-to page.
Adds the new style-rules guide to the docs navigation and includes new diagram images (light/dark).

Reviewed changes

Copilot reviewed 3 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/learning-how-tos/examples-and-guides/using-custom-instructions-and-style-rules.mdx	New how-to page showing direct custom instructions + basic style rule list CRUD.
docs/learning-how-tos/examples-and-guides/style-rules-and-custom-instructions.mdx	New in-depth guide with API overview, examples, and embedded diagram.
docs.json	Adds the new style-rules guide to the “Guides” navigation list.
_assets/images/style-rule-list-light.jpg	Light-mode diagram asset referenced by the guide.
_assets/images/style-rule-list-dark.jpg	Dark-mode diagram asset referenced by the guide.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

shirgoldbird · 2026-04-23T02:09:20Z

+  <img className="hidden dark:block" src="/_assets/images/style-rule-list-dark.jpg" alt="Diagram showing predefined rules and custom instructions inside a style rule list"/>
+</div>
+
+If you use the [DeepL Translator](https://www.deepl.com), you can also make style rule lists, predefined rules, and custom instructions on its [style rules page](https://www.deepl.com/en/custom-rules/f5dd1adb-93e5-4013-813d-e20568edabfd?tab=predefined&section=style-tone).


isn't this also true for API users?

I'm impressed that you saw this at 10 pm!

Yes, if the API developer also uses the DeepL Translator. But does this phrasing not allow for that possibility?

API users who have access to style rules can also visit their dashboard and configure style rules. This is not a feature specific to DeepL Translate users. (Also, this link doesn't work, so I'm assuming it's trying to send users to the dashboard to set up a list.) Suggest this sentence is removed altogether

Brianna mentioned that I pasted the wrong link. I've fixed that!

I think it's important that API developers know whether they can also use these style rule lists in the Translator, so I'd keep this. But I didn't know that API developers could access any part of the web app. You're saying they can use https://www.deepl.com/custom-rules/ ?

Yes, before these CRUD endpoints were released, we told devs to make style rules in the admin panel, which they can still do. (They cannot use those style rules in the web translator without a separate paid Translate subscription, which very few devs have.)

You can test all this out for yourself if you make a new free API account, or request a paid DeepL API account by filing a ticket (currently, this requires a separate account than your SSO one).

Custom instructions are an array of associative arrays

Copilot

Pull request overview

Copilot reviewed 2 out of 4 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

BriannaDelgado · 2026-04-23T16:32:59Z

+* **custom instructions**, rules you write yourself
+
+<Tip>
+DeepL also refers to predefined rules as "configured rules". The two are the same.


This isn't necessarily true. We used the "configured rules" verbiage to denote rules that you've enabled for that style rule (e.g. "configured predefined rules"). Perhaps
In the API, "configured rules" refers to any enabled predefined rule in a style rule list

I kind of see what you mean... but because configured rules can't exist outside of a style rule list, I don't think we need to draw the distinction. What I want to do here is let people know that they'll see these things referred to in two different ways among bits of documentation and code, and I want them to know they refer to the same thing in practice.

BriannaDelgado · 2026-04-23T16:37:57Z

+
+The Style Rules API lets you create, retrieve, edit, and delete style rule lists.
+
+Create, retrieve, and delete operations deal with entire lists. When modifying the rules in a list, the API treats predefined rules and custom instructions separately, with dedicated sections for each.


When modifying the rules in a list, the API treats predefined rules and custom instructions separately, with dedicated sections for each.

nit: "When modifying the rules in a list, dedicated API endpoints are available for granular updates to both predefined rules and custom instructions separately." I wasn't sure what you meant by "dedicated sections for each" here.

shirgoldbird · 2026-04-23T21:06:32Z

+
+If you use the [DeepL Translator](https://www.deepl.com), you can also make style rule lists, predefined rules, and custom instructions on its [style rules page](https://www.deepl.com/en/custom-rules/f5dd1adb-93e5-4013-813d-e20568edabfd?tab=predefined&section=style-tone).
+
+## API overview


This section ("API overview") doesn't add value

Disagreed, I'm afraid. This is one of the most important parts. It's a distillation of much conversation with Brianna about how to clarify the highly nonintuitive way in which the API allows developers to modify style rule lists. I'd sooner cut everything else in the guide and leave this part.

Perhaps you can make the non-intuitive parts you're trying to highlight clearer? Right now, I don't see it clarifying anything beyond our support for CRUD

shirgoldbird · 2026-04-23T21:08:08Z

+
+### Discovering predefined rules
+
+To find whether DeepL provides predefined rules for the three Québécois guidelines we need, we can check the API Reference for any method that changes the predefined rules in a list. Let's try this with the [Create a style rule list](https://developers.deepl.com/api-reference/style-rules/create-style-rule) method, looking for a rule that matches our first guideline: 'Don't use a space before punctuation marks like "?", "!", and ":"'.


"any method that changes the predefined rules in a list" - what does this mean?

This section is very difficult to make clear, because in fact it's incredibly difficult to find predefined rules and their names. To find these, I had to go to the web app and look at the HTML. I'm trying to give people a path. I'll see if I can make this more clear.

shirgoldbird

I just reworked our agents to ease the process of editing new pages - will send you the output in Slack. Here's its "must fix" section

Page mixes Diataxis types (style-rules-and-custom-instructions.mdx:8-35)
Lines 8-29 ("What are style rules?") are explanation content: they define the feature, compare it to glossaries and translation memories, and describe types. Lines 31-35 ("API overview") read as reference content describing CRUD operations. The rest of the page is a tutorial walkthrough. Extract the explanation into a brief intro (1-2 sentences with a link) and remove the API overview section, replacing it with a link to the style rules reference.
Tab default should be curl, not Python (style-rules-and-custom-instructions.mdx:99, :365, :650)
All three <Tabs> components use defaultTabIndex={2}, which defaults to Python. CLAUDE.md states: "Use curl as the default, with SDK examples in tabs where available." Set the cURL tab as default (either reorder tabs so cURL is first, or adjust defaultTabIndex).
Internal links use absolute URLs instead of relative paths (style-rules-and-custom-instructions.mdx:12, :63, :65)
Three links use https://developers.deepl.com/... instead of relative paths. CLAUDE.md requires relative links for internal docs. Change to relative paths, e.g., [Glossaries](/api-reference/multilingual-glossaries), [Create a style rule list](/api-reference/style-rules/create-style-rule), and [the configured_rules parameter](/api-reference/style-rules/create-style-rule#body-configured-rules).
Excessive callout boxes: 6 Tip boxes, limit is 2 (style-rules-and-custom-instructions.mdx:19, :217, :251, :280, :313, :349)
CLAUDE.md says "No more than 2 callout boxes per page." The "In production code..." tips on lines 217-349 are identical and repeated in 5 tabs. Remove the per-tab tips and add a single <Tip> after the first code example section, or convert to a brief sentence before the tabs.
Frontmatter description is not action-oriented (style-rules-and-custom-instructions.mdx:3)
Current: "Fine-tune your translations using style rules, style rule lists, and custom instructions." CLAUDE.md requires "Learn how to X" style descriptions. Rewrite to something like "Learn how to create and use style rules, predefined rules, and custom instructions to customize DeepL translations."

shirgoldbird · 2026-04-23T21:13:01Z

+
+### Including custom instructions
+
+What if we forgot a rule? In French Canadian, numbers below 10 are usually written out, unless the sentence contains other numbers. As the API presently has no predefined rule for that, this is a fine candidate for a custom instruction.


"We" is ambiguous - is it DeepL, or the user? Either way, I'm not sure "forget" is the correct verb. It'd better set user expectations to say something like "What if we want to go beyond the predefined options for rules? We can write our own" etc

shirgoldbird · 2026-04-23T21:14:26Z

+
+What if we forgot a rule? In French Canadian, numbers below 10 are usually written out, unless the sentence contains other numbers. As the API presently has no predefined rule for that, this is a fine candidate for a custom instruction.
+
+Let's make a new style rule list with the predefined rules above plus this custom instruction, which should cover most cases: "Write out any integer below 10, in any sentence that only contains one number, unless that integer is part of a date, time, percentage, or currency"


Why not introduce PATCH here instead of repeating a POST example?

I wanted to show how to create a list that has both predefined rules and custom instructions. The github repos have very few examples; they don't show every use case.

I do want to use PATCH later in the guide when I expand it!

shirgoldbird · 2026-04-23T21:15:07Z

+
+To find whether DeepL provides predefined rules for the three Québécois guidelines we need, we can check the API Reference for any method that changes the predefined rules in a list. Let's try this with the [Create a style rule list](https://developers.deepl.com/api-reference/style-rules/create-style-rule) method, looking for a rule that matches our first guideline: 'Don't use a space before punctuation marks like "?", "!", and ":"'.
+
+Scanning through the `Body` section, we find [the `configured_rules` parameter](https://developers.deepl.com/api-reference/style-rules/create-style-rule#body-configured-rules). Expanding that reveals the available categories of predefined rules, including [`configured_rules.punctuation`](/api-reference/style-rules/create-style-rule#body-configured-rules-punctuation). Expand the "child attributes" section and scroll down to find the [`spacing_and_punctuation`](/api-reference/style-rules/create-style-rule#body-configured-rules-punctuation-spacing-and-punctuation) rule, with the option `do_not_use_space`. That's just what we need!


This section is very verbose, which makes it hard to follow

Yeah, this is a tough one. I'm trying to make a very difficult process clear, as I just mentioned in a comment above. I tried this a few ways. I'll try to compress it.

shirgoldbird · 2026-04-23T21:16:34Z

+
+## Additional details
+
+### Sharing lists with DeepL Translator


recommend cutting this section - it's not specific enough to be helpful, and I don't think most people reading this doc will need the info

I think this is important information. Since this API is pretty inconsistent and unintuitive, I think every bit of explanation helps.

morsssss added 6 commits April 2, 2026 17:32

Put new guide into docs.json

7f9876e

First draft, from Claude... well, ok

9382975

Propagated file name change into docs.json

72f8a69

Shortened file name, lots more writing and changes

92fc15f

Merge branch 'main' into customization-guide

55cf0ed

MVP version of new style rules guide

5f5f7d3

Comes with light and dark mode versions of a diagram

Copilot AI review requested due to automatic review settings April 23, 2026 01:39

Copilot started reviewing on behalf of morsssss April 23, 2026 01:39 View session

mintlify Bot deployed to staging April 23, 2026 01:40 View deployment

Copilot AI reviewed Apr 23, 2026

View reviewed changes

shirgoldbird reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/learning-how-tos/examples-and-guides/style-rules-and-custom-instructions.mdx Outdated

A number of small fixes, mostly inspired by Copilot

42aae87

mintlify Bot deployed to staging April 23, 2026 02:22 View deployment

shirgoldbird reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/learning-how-tos/examples-and-guides/using-custom-instructions-and-style-rules.mdx Outdated

Removing Claude's original creation

2efc67b

mintlify Bot deployed to staging April 23, 2026 03:11 View deployment

Fix PHP sample

1cbec80

Custom instructions are an array of associative arrays

mintlify Bot deployed to staging April 23, 2026 03:17 View deployment

morsssss requested a review from Copilot April 23, 2026 03:18

Copilot started reviewing on behalf of morsssss April 23, 2026 03:18 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

morsssss requested a review from BriannaDelgado April 23, 2026 15:16

BriannaDelgado reviewed Apr 23, 2026

View reviewed changes

shirgoldbird reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/learning-how-tos/examples-and-guides/style-rules-and-custom-instructions.mdx Outdated

shirgoldbird reviewed Apr 23, 2026

View reviewed changes

shirgoldbird requested changes Apr 23, 2026

View reviewed changes

Yet more changes from review

82e4d16

mintlify Bot deployed to staging April 23, 2026 22:39 View deployment


		The Style Rules API lets you create, retrieve, edit, and delete style rule lists.

		Create, retrieve, and delete operations deal with entire lists. When modifying the rules in a list, the API treats predefined rules and custom instructions separately, with dedicated sections for each.


		If you use the [DeepL Translator](https://www.deepl.com), you can also make style rule lists, predefined rules, and custom instructions on its [style rules page](https://www.deepl.com/en/custom-rules/f5dd1adb-93e5-4013-813d-e20568edabfd?tab=predefined&section=style-tone).

		## API overview


		### Discovering predefined rules

		To find whether DeepL provides predefined rules for the three Québécois guidelines we need, we can check the API Reference for any method that changes the predefined rules in a list. Let's try this with the [Create a style rule list](https://developers.deepl.com/api-reference/style-rules/create-style-rule) method, looking for a rule that matches our first guideline: 'Don't use a space before punctuation marks like "?", "!", and ":"'.


		### Including custom instructions

		What if we forgot a rule? In French Canadian, numbers below 10 are usually written out, unless the sentence contains other numbers. As the API presently has no predefined rule for that, this is a fine candidate for a custom instruction.


		What if we forgot a rule? In French Canadian, numbers below 10 are usually written out, unless the sentence contains other numbers. As the API presently has no predefined rule for that, this is a fine candidate for a custom instruction.

		Let's make a new style rule list with the predefined rules above plus this custom instruction, which should cover most cases: "Write out any integer below 10, in any sentence that only contains one number, unless that integer is part of a date, time, percentage, or currency"


		To find whether DeepL provides predefined rules for the three Québécois guidelines we need, we can check the API Reference for any method that changes the predefined rules in a list. Let's try this with the [Create a style rule list](https://developers.deepl.com/api-reference/style-rules/create-style-rule) method, looking for a rule that matches our first guideline: 'Don't use a space before punctuation marks like "?", "!", and ":"'.

		Scanning through the `Body` section, we find [the `configured_rules` parameter](https://developers.deepl.com/api-reference/style-rules/create-style-rule#body-configured-rules). Expanding that reveals the available categories of predefined rules, including [`configured_rules.punctuation`](/api-reference/style-rules/create-style-rule#body-configured-rules-punctuation). Expand the "child attributes" section and scroll down to find the [`spacing_and_punctuation`](/api-reference/style-rules/create-style-rule#body-configured-rules-punctuation-spacing-and-punctuation) rule, with the option `do_not_use_space`. That's just what we need!


		## Additional details

		### Sharing lists with DeepL Translator

Conversation

morsssss commented Apr 23, 2026

Uh oh!

mintlify Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shirgoldbird Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

shirgoldbird Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shirgoldbird left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

mintlify Bot commented Apr 23, 2026 •

edited

Loading

shirgoldbird Apr 23, 2026 •

edited

Loading

shirgoldbird Apr 23, 2026 •

edited

Loading

shirgoldbird left a comment •

edited

Loading