feat: add context parameter (alpha feature)

Author: daniel-jones-dev

CHANGELOG.md

@@ -4,7 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
 ## [Unreleased]
+### Added
+* Add optional `context` parameter for text translation, that specifies
+  additional context to influence translations, that is not translated itself.
 ### Fixed
 * Remove unused `commons-math` dependency
 

README.md

@@ -159,6 +159,11 @@ a `TextTranslationOptions`, with the following setters:
   returned by glossary lookup functions, for example `listGlossaries()`).
     - `setGlossaryId()` is also available for backward-compatibility, accepting
       a string containing the glossary ID.
+- `setContext()`: 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.
 - `setTagHandling()`: type of tags to parse before translation, options are
   `"html"` and `"xml"`.
 
@@ -623,6 +628,8 @@ tests using `./gradlew test` with the `DEEPL_MOCK_SERVER_PORT` and
 
 [api-docs]: https://www.deepl.com/docs-api?utm_source=github&utm_medium=github-java-readme
 
+[api-docs-context-param]: https://www.deepl.com/docs-api/translating-text/?utm_source=github&utm_medium=github-java-readme
+
 [api-docs-csv-format]: https://www.deepl.com/docs-api/managing-glossaries/supported-glossary-formats/?utm_source=github&utm_medium=github-java-readme
 
 [api-docs-xml-handling]: https://www.deepl.com/docs-api/handling-xml/?utm_source=github&utm_medium=github-java-readme

deepl-java/src/main/java/com/deepl/api/TextTranslationOptions.java

@@ -18,6 +18,7 @@ public class TextTranslationOptions {
   private String glossaryId;
   private SentenceSplittingMode sentenceSplittingMode;
   private boolean preserveFormatting = false;
+  private String context;
   private String tagHandling;
   private boolean outlineDetection = true;
   private Iterable<String> ignoreTags;
@@ -63,6 +64,16 @@ public TextTranslationOptions setGlossary(String glossaryId) {
     return this;
   }
 
+  /**
+   * 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 for more information and example usage.
+   */
+  public TextTranslationOptions setContext(String context) {
+    this.context = context;
+    return this;
+  }
+
   /**
    * Specifies how input translation text should be split into sentences. By default, this value is
    * <code>null</code> and the default sentence splitting mode is used.
@@ -151,6 +162,11 @@ public boolean isPreserveFormatting() {
     return preserveFormatting;
   }
 
+  /** Gets the current context. */
+  public String getContext() {
+    return context;
+  }
+
   /** Gets the current tag handling setting. */
   public String getTagHandling() {
     return tagHandling;

deepl-java/src/main/java/com/deepl/api/Translator.java

@@ -803,6 +803,9 @@ private static ArrayList<KeyValuePair<String, String>> createHttpParams(
       if (options.isPreserveFormatting()) {
         params.add(new KeyValuePair<>("preserve_formatting", "1"));
       }
+      if (options.getContext() != null) {
+        params.add(new KeyValuePair<>("context", options.getContext()));
+      }
       if (options.getTagHandling() != null) {
         params.add(new KeyValuePair<>("tag_handling", options.getTagHandling()));
       }

deepl-java/src/test/java/com/deepl/api/TranslateTextTest.java

@@ -186,6 +186,22 @@ void testFormality() throws DeepLException, InterruptedException {
     }
   }
 
+  @Test
+  void testContext() throws DeepLException, InterruptedException {
+    // In German, "scharf" can mean:
+    //  - spicy/hot when referring to food, or
+    //  - sharp when referring to other objects such as a knife (Messer).
+    Translator translator = createTranslator();
+    String text = "Das ist scharf!";
+
+    translator.translateText(text, null, "de");
+    // Result: "That is hot!"
+
+    translator.translateText(
+        text, null, "de", new TextTranslationOptions().setContext("Das ist ein Messer."));
+    // Result: "That is sharp!"
+  }
+
   @Test
   void testSplitSentences() throws DeepLException, InterruptedException {
     Assumptions.assumeTrue(isMockServer);