feat: Add support for custom_instructions parameter in text translation

Author: BriannaDelgado

README.md

@@ -161,7 +161,7 @@ arguments are:
   `get_glossary()`.
 - `context`: specifies additional context to influence translations, that is not
   translated itself. Characters in the `context` parameter are not counted toward billing.
-  See the [API documentation][api-docs-context-param] for more information and 
+  See the [API documentation][api-docs-context-param] for more information and
   example usage.
 - `model_type`: specifies the type of translation model to use, options are:
   - `'quality_optimized'` (`ModelType.QUALITY_OPTIMIZED`): use a translation
@@ -175,6 +175,14 @@ arguments are:
   and `'xml'`.
 - `style_rule`: specifies a style rule to use with translation, either as a string
   containing the ID of the style rule, or a `StyleRuleInfo` object.
+- `custom_instructions`: an array of instructions to customize the text 
+  translation behavior. Up to 10 custom instructions can be specified, each with 
+  a maximum of 300 characters.
+  Important: The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, 
+  `ko`, `zh` or any variants of these languages.
+  Note: Any request with the `custom_instructions` parameter enabled will use
+  the `quality_optimized` model type as the default. Requests combining
+  `custom_instructions` and `model_type: latency_optimized` will be rejected.
 - `extra_body_parameters`: Dictionary of extra parameters to pass in the body of
   the HTTP request. Mostly used by DeepL employees to test functionality, or for
   beta programs.

deepl/__main__.py

@@ -385,6 +385,14 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
         type=str,
         help="ID of style rule to use for translation",
     )
+    parser_text.add_argument(
+        "--custom-instructions",
+        dest="custom_instructions",
+        action="append",
+        type=str,
+        help="custom instructions to guide translation (can be specified "
+        "multiple times, max 10 instructions, each max 300 characters)",
+    )
     parser_text.add_argument(
         "text",
         nargs="+",

deepl/translator.py

@@ -382,6 +382,7 @@ def translate_text(
         ignore_tags: Union[str, List[str], None] = None,
         model_type: Union[str, ModelType, None] = None,
         style_rule: Union[str, StyleRuleInfo, None] = None,
+        custom_instructions: Optional[List[str]] = None,
         extra_body_parameters: Optional[dict] = None,
     ) -> Union[TextResult, List[TextResult]]:
         """Translate text(s) into the target language.
@@ -427,6 +428,9 @@ def translate_text(
         :type ignore_tags: List of XML tags or comma-separated-list of tags.
         :param model_type: (Optional) Controls whether the translation engine
             should use a potentially slower model to achieve higher quality.
+        :param custom_instructions: (Optional) List of custom instructions to
+            guide the translation. Maximum of 10 instructions, each with a
+            maximum length of 300 characters.
         :param extra_body_parameters: (Optional) Additional key/value pairs to
             include in the JSON request body sent to the API. If provided,
             keys in this dict will be added to the request body. Existing
@@ -490,6 +494,8 @@ def join_tags(tag_argument: Union[str, Iterable[str]]) -> List[str]:
             request_data["splitting_tags"] = join_tags(splitting_tags)
         if ignore_tags is not None:
             request_data["ignore_tags"] = join_tags(ignore_tags)
+        if custom_instructions is not None:
+            request_data["custom_instructions"] = custom_instructions
 
         # Do not overwrite keys that were explicitly set by this method.
         if extra_body_parameters:

tests/test_translate_text.py

@@ -418,3 +418,28 @@ def test_extra_body_params(translator):
     assert example_text["FR"] == res.text
     assert "EN" == res.detected_source_lang
     assert res.billed_characters == len(example_text["EN"])
+
+
+@needs_real_server
+def test_custom_instructions(translator):
+    text = "I am testing if custom instructions are working correctly."
+    no_custom_instructions_result = translator.translate_text(
+        text,
+        target_lang="DE",
+    )
+
+    custom_instructions_result = translator.translate_text(
+        text,
+        target_lang="DE",
+        custom_instructions=["Use informal language", "Be concise"],
+    )
+
+    assert isinstance(custom_instructions_result, deepl.TextResult)
+    assert custom_instructions_result.text is not None
+    assert len(custom_instructions_result.text) > 0
+    assert custom_instructions_result.detected_source_lang == "EN"
+
+    # Check that applying custom instructions results in different translations
+    assert (
+        custom_instructions_result.text != no_custom_instructions_result.text
+    )