feat: Add support for custom_instructions parameter in text translation

Author: BriannaDelgado

README.md

@@ -168,9 +168,16 @@ a `TextTranslationOptions`, with the following setters:
   containing the ID of the style rule, or a `StyleRuleInfo` object.
     - `setStyleId()` is also available, accepting a string containing the style rule ID.
 - `setContext()`: specifies additional context to influence translations, that is not
-  translated itself. Characters in the `context` parameter are not counted toward billing.  
+  translated itself. Characters in the `context` parameter are not counted toward billing.
   See the [API documentation][api-docs-context-param] for more information and
   example usage.
+- `setCustomInstructions()`: an array of instructions to customize the 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.
 - `model_type`: specifies the type of translation model to use, options are:
   - `'quality_optimized'`: use a translation model that maximizes translation quality,
     at the cost of response time. This option may be unavailable for some language pairs.

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

@@ -26,6 +26,7 @@ public class TextTranslationOptions extends BaseRequestOptions {
   private Iterable<String> ignoreTags;
   private Iterable<String> nonSplittingTags;
   private Iterable<String> splittingTags;
+  private Iterable<String> customInstructions;
 
   /**
    * Sets whether translations should lean toward formal or informal language. This option is only
@@ -175,6 +176,15 @@ public TextTranslationOptions setSplittingTags(Iterable<String> splittingTags) {
     return this;
   }
 
+  /**
+   * Sets custom instructions to influence translations. By default, this value is <code>null</code>
+   * and no custom instructions are used.
+   */
+  public TextTranslationOptions setCustomInstructions(Iterable<String> customInstructions) {
+    this.customInstructions = customInstructions;
+    return this;
+  }
+
   /** Gets the current formality setting. */
   public Formality getFormality() {
     return formality;
@@ -234,4 +244,9 @@ public Iterable<String> getNonSplittingTags() {
   public Iterable<String> getSplittingTags() {
     return splittingTags;
   }
+
+  /** Gets the current custom instructions list. */
+  public Iterable<String> getCustomInstructions() {
+    return customInstructions;
+  }
 }

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

@@ -849,6 +849,11 @@ private static ArrayList<KeyValuePair<String, String>> createHttpParams(
       if (options.getStyleId() != null) {
         params.add(new KeyValuePair<>("style_id", options.getStyleId()));
       }
+      if (options.getCustomInstructions() != null) {
+        for (String instruction : options.getCustomInstructions()) {
+          params.add(new KeyValuePair<>("custom_instructions", instruction));
+        }
+      }
       addExtraBodyParameters(params, options.getExtraBodyParameters());
     }
     return params;

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

@@ -349,4 +349,27 @@ void testExtraBodyParams() throws DeepLException, InterruptedException {
     Assertions.assertEquals("en", result.getDetectedSourceLanguage());
     Assertions.assertEquals(exampleText.get("en").length(), result.getBilledCharacters());
   }
+
+  @Test
+  void testCustomInstructions() throws DeepLException, InterruptedException {
+    Translator translator = createTranslator();
+    String text = "Hello world. I am testing if custom instructions are working correctly.";
+
+    TextResult resultWithCustomInstructions =
+        translator.translateText(
+            text,
+            null,
+            "de",
+            new TextTranslationOptions()
+                .setCustomInstructions(Arrays.asList("Use informal language", "Be concise")));
+
+    TextResult resultWithoutCustomInstructions = translator.translateText(text, null, "de");
+
+    Assertions.assertNotNull(resultWithCustomInstructions.getText());
+    Assertions.assertEquals("en", resultWithCustomInstructions.getDetectedSourceLanguage());
+    if (!isMockServer) {
+      Assertions.assertFalse(
+          resultWithCustomInstructions.getText().equals(resultWithoutCustomInstructions.getText()));
+    }
+  }
 }