feat: add context parameter (alpha feature)

Author: daniel-jones-dev

CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 ## [Unreleased]
+### Added
+* Add optional `context` parameter for text translation, that specifies
+  additional context to influence translations, that is not translated itself.
 ### Changed
 * Added notice in Readme that starting in 2024 the library will drop support for
   Python versions that are officially end-of-life.

README.md

@@ -154,6 +154,11 @@ arguments are:
 - `glossary`: specifies a glossary to use with translation, either as a string
   containing the glossary ID, or a `GlossaryInfo` as returned by
   `get_glossary()`.
+- `context`: specifies additional context to influence translations, that is not
+  translated itself. Note this is an **alpha feature**: it may be deprecated at
+  any time, or incur charges if it becomes generally available.
+  See the [API documentation][api-docs-context-param] for more information and
+  example usage.
 - `tag_handling`: type of tags to parse before translation, options are `'html'`
   and `'xml'`.
 
@@ -600,6 +605,8 @@ environment variables defined referring to the mock-server.
 
 [api-docs-xml-handling]: https://www.deepl.com/docs-api/handling-xml/?utm_source=github&utm_medium=github-python-readme
 
+[api-docs-context-param]: https://www.deepl.com/docs-api/translating-text/?utm_source=github&utm_medium=github-python-readme
+
 [api-docs-lang-list]: https://www.deepl.com/docs-api/translating-text/?utm_source=github&utm_medium=github-python-readme
 
 [api-docs-glossary-lang-list]: https://www.deepl.com/docs-api/managing-glossaries/?utm_source=github&utm_medium=github-python-readme

deepl/__main__.py

@@ -283,6 +283,12 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
         "text", help="translate text(s)", description="translate text(s)"
     )
     add_common_arguments(parser_text)
+    parser_text.add_argument(
+        "--context",
+        type=str,
+        help="additional contextual text to improve translations, see API docs"
+        " for information",
+    )
     parser_text.add_argument(
         "--split-sentences",
         type=str,

deepl/translator.py

@@ -337,6 +337,7 @@ def translate_text(
         *,
         source_lang: Union[str, Language, None] = None,
         target_lang: Union[str, Language],
+        context: Optional[str] = None,
         split_sentences: Union[str, SplitSentences, None] = None,
         preserve_formatting: Optional[bool] = None,
         formality: Union[str, Formality, None] = None,
@@ -357,6 +358,11 @@ def translate_text(
             language. If a glossary is used, source_lang must be specified.
         :param target_lang: language code to translate text into, for example
             "DE", "EN-US", "FR".
+        :param context: (Optional) Additional contextual text to influence
+            translations, that is not translated itself. Note: this is an alpha
+            feature: it may be deprecated at any time, or incur charges if it
+            becomes generally available. See the API documentation for more
+            information and example usage.
         :param split_sentences: (Optional) Controls how the translation engine
             should split input into sentences before translation, see
             :class:`SplitSentences`.
@@ -406,6 +412,8 @@ def translate_text(
         )
         request_data["text"] = text
 
+        if context is not None:
+            request_data["context"] = context
         if split_sentences is not None:
             request_data["split_sentences"] = str(split_sentences)
         if preserve_formatting is not None:

tests/test_translate_text.py

@@ -236,6 +236,20 @@ def test_preserve_formatting(translator):
     )
 
 
+def test_context(translator):
+    # In German, "scharf" can mean:
+    # - spicy/hot when referring to food, or
+    # - sharp when referring to other objects such as a knife (Messer).
+    text = "Das ist scharf!"
+    _ = translator.translate_text(text, target_lang="en-US")
+    # Result: "That is hot!"
+
+    _ = translator.translate_text(
+        text, target_lang="en-US", context="Das ist ein Messer"
+    )
+    # Result: "That is sharp!"
+
+
 def test_split_sentences_basic(translator):
     text = """If the implementation is hard to explain, it's a bad idea.
         If the implementation is easy to explain, it may be a good idea."""