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.

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.

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

"Create, retrieve, and delete operations work on entire lists. To update the rules within a list, you’ll need to manage predefined rules and instructions separately, using different API methods for each."

This is one of the quirkier aspects of the API. Until I went through all the methods and realized this was the case, and that it was consistent, I didn't understand how I would logically use the API.

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.

Talking with Brianna, I've realized that this method, already almost impossible, is in fact not quite the way to do it. People will really need to look for potential predefined rules in the web app first. I'll add this. Unfortunately I have no way of making discovery easy, but I'll try to explain a method to find rules that doesn't involve looking at web app options in DevTools (which is actually the easiest way)

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

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

More better languager

1cb8ca8

mintlify Bot deployed to staging April 27, 2026 02:44 View deployment

New language for sharing with DeepL translator

16b7609

mintlify Bot deployed to staging April 29, 2026 18:13 View deployment

As we learn more, we write better docs

0a80740

mintlify Bot deployed to staging April 29, 2026 21:49 View deployment


		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!

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!

Uh oh!

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!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mintlify Bot commented Apr 23, 2026 •

edited

Loading

shirgoldbird Apr 23, 2026 •

edited

Loading

shirgoldbird left a comment •

edited

Loading