Skip to main content

​
What are style rules?

Style rules let you customize DeepL translations in a wide variety of ways. Glossaries let you set specific translations for words or short phrases. Translation memories allow you to save and apply a whole database of translations. Style rules are more flexible, letting you customize style, tone, grammar, punctuation conventions, numbers and currencies, and much more. DeepL supports two types of style rules:
  • predefined rules, a set of rules DeepL provides to enforce common formatting, punctuation, and stylistic choices
  • custom instructions, rules you write yourself
DeepL also refers to predefined rules as “configured rules”. The two are the same.
All style rules live in style rule lists. A style rule list can contain predefined rules, custom instructions, or both:
Diagram showing predefined rules and custom instructions inside a style rule list
If you use the DeepL Translator, you can also make style rule lists, predefined rules, and custom instructions on its style rules page.

​
API overview

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.

​
Creating a list

Let’s say we want to translate content into French, while following certain conventions used in Canadian French, also known as Québécois. (The DeepL API already supports Canadian French, but we’ll conveniently ignore that for now.)
  • Don’t use a space before punctuation marks like ”?”, ”!”, and ”:”
  • Use French chevrons (“guillemets”) for quotation marks
  • Use accents and cedillas, even on capital letters
How do we do this? Style rules, of course! To make a new style rule list, we need to pass the API:
  • the list’s name
  • the list’s language - the target language for translations where we want this rule to apply
When creating a new list, you have the option to include:
  • a set of predefined rules
  • a set of custom instructions
  • both of these
  • neither
In short, you can create an empty list, or you can populate a new list with predefined rules and/or custom instructions.

​
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 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. Expanding that reveals the available categories of predefined rules, including configured_rules.punctuation. Expand the “child attributes” section and scroll down to find the spacing_and_punctuation rule, with the option do_not_use_space. That’s just what we need! Use this method to find rules for each of our three guidelines, noting the category, rule name, and desired option for each:
  • Don’t use a space before punctuation marks like ”?”, ”!”, and ”:”
    • punctuation → spacing_and_punctuation → do_not_use_space
  • Use French chevrons (“guillemets”) for quotation marks
    • punctuation → quotation_mark → use_guillemets
  • Use accents and cedillas, even on capital letters
    • spelling_and_grammar → accents_and_cedillas → use_even_on_capital_letters
In the API, predefined rules go into a configured_rules object: a dictionary where each key is a category, and each value is a dictionary of rule names mapped to options. For our three rules, that looks like this: 
  "configured_rules": {
    "punctuation": {
      "spacing_and_punctuation": "do_not_use_space",
      "quotation_mark": "use_guillemets"
    },
    "spelling_and_grammar": {
      "accents_and_cedillas": "use_even_on_capital_letters"
    }
  }

​
Making a list with predefined rules

To create our new Québécois style rules list, we’ll need to send the API:
  • the name: "Québécois"
  • the language: "fr" for French
  • our predefined rules dictionary, which here we call configured_rules or configuredRules, depending on the conventions of your programming language
Request
import deepl

auth_key = "{YOUR_API_KEY}" # replace with your key
deepl_client = deepl.DeepLClient(auth_key)

result = deepl_client.create_style_rule(
    name="Québécois",
    language="fr",
    configured_rules={
        "punctuation": {
            "spacing_and_punctuation": "do_not_use_space",
            "quotation_mark": "use_guillemets"
        },
        "spelling_and_grammar": {
            "accents_and_cedillas": "use_even_on_capital_letters"
        }
    }
)

print(f"Yay, we made a new style rule list named '{result.name}' with the id '{result.style_id}'.")
Output
Yay, we made a new style rule list named 'Québécois' with the id '635073ee-dad3-4aaf-b1e9-2bc6f6ec314f'
In production code, it’s safer to store your API key in an environment variable.
The API returns everything in the new style rules list, including the style_id which DeepL has assigned it. You’ll need this id to reference the list later.

​
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. 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” For clarity, in the client library code samples below, we create configured_rules and custom_instructions objects first, then pass those to createStyleRule().
Request
configured_rules={
    "punctuation": {
        "spacing_and_punctuation": "do_not_use_space",
        "quotation_mark": "use_guillemets"
    },
    "spelling_and_grammar": {
        "accents_and_cedillas": "use_even_on_capital_letters"
    }
}

custom_instructions=[
    {
        "label": "one-digit numbers",
        "prompt": "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"
    }
]

result = deepl_client.create_style_rule(
    name="Québécois++",
    language="fr",
    configured_rules=configured_rules,
    custom_instructions=custom_instructions
)

print(f"Yay, we made a new style rule list named '{result.name}' with the id '{result.style_id}'.")
Output
Yay, we made a new style rule list named 'Québécois++' with the id '7f0a3b2c-1d4e-5f6a-9b8c-0d2e4f6a8b0c'

​
Client library tips

In the client libraries, StyleRule refers to a style rule list, not a single style rule. So, for example, to create a style rule list, depending on your language, you’d use something like create_style_rule or CreateStyleRule. In some client libraries, it is simpler to first make a configuredRules object, then create a new style rule list object containing those configuredRules.

​
Using style rules in translation

Let’s try our style rule list in an actual translation! To do so, we simply add our list’s style_id to a translation request, like this:
Request
text = 'He said, "I ate 6 burritos all at once!" She responded, "STOP!"'
result = deepl_client.translate_text(text, target_lang='fr', style_id='7f0a3b2c-1d4e-5f6a-9b8c-0d2e4f6a8b0c')

print(result.text)
Output
Il a dit: «J'ai mangé six burritos d'un coup!» Elle a répondu : « ARRÊTE! »
Notice that the translation includes French chevrons, the number “six” is spelled out, the circumflex accent is included on “ARRÊTE”, and there’s no space before final exclamation points.

​
Additional details

​
Sharing lists with DeepL Translator

In certain cases, you can share these rules between the DeepL Translator and the API. See the style rules reference for current information. The API provides many predefined rules that are unavailable in the DeepL Translator. Sometimes it’s good to be a programmer.

​
Language support

Predefined rules can only be applied to specific languages. If you try to add a predefined rule to a list for a language where it is not supported, the API will throw an error.

​
Keep exploring

For information on retrieving style rule lists, deleting lists, or modifying the predefined rules or custom instructions in a list, see the Style Rules reference. Happy customization!