feat: Add modelType parameter to translateText()

Author: JanEbbing

CHANGELOG.md

@@ -5,6 +5,16 @@ 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
+* Added `modelType` option to `translateText()` to use models with higher
+  translation quality (available for some language pairs), or better latency.
+  Options are `'quality_optimized'`, `'latency_optimized'`, and  `'prefer_quality_optimized'`
+* Added the `modelTypeUsed` field to `translateText()` response, that
+  indicates the translation model used when the `modelType` option is
+  specified.
+
+
 ## [1.6.0] - 2024-09-17
 ### Added
 * Added `getBilledCharacters()` to text translation response.

README.md

@@ -98,8 +98,9 @@ There are additional optional arguments to control translation, see
 `translateText()` returns a `TextResult`, or a List of `TextResult`s
 corresponding to your input text(s). `TextResult` has the following accessors:
 - `getText()` returns the translated text,
-- `getDetectedSourceLanguage()` returns the detected source language code, and
-- `getBilledCharacters()` returns the number of characters billed for the text.
+- `getDetectedSourceLanguage()` returns the detected source language code,
+- `getBilledCharacters()` returns the number of characters billed for the text, and
+- `getModelTypeUsed()` returns the model type used for the translation.
 
 ```java
 class Example {  // Continuing class Example from above
@@ -166,6 +167,13 @@ a `TextTranslationOptions`, with the following setters:
   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.
+- `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.
+  - `'prefer_quality_optimized'`: use the highest-quality translation model for the given
+    language pair.
+  - `'latency_optimized'`: use a translation model that minimizes response time, at the
+    cost of translation quality.
 - `setTagHandling()`: type of tags to parse before translation, options are
   `"html"` and `"xml"`.
 

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

@@ -3,17 +3,25 @@
 // license that can be found in the LICENSE file.
 package com.deepl.api;
 
+import org.jetbrains.annotations.Nullable;
+
 /** The result of a text translation. */
 public class TextResult {
   private final String text;
   private final String detectedSourceLanguage;
   private final int billedCharacters;
+  private final @Nullable String modelTypeUsed;
 
   /** Constructs a new instance. */
-  public TextResult(String text, String detectedSourceLanguage, int billedCharacters) {
+  public TextResult(
+      String text,
+      String detectedSourceLanguage,
+      int billedCharacters,
+      @Nullable String modelTypeUsed) {
     this.text = text;
     this.detectedSourceLanguage = LanguageCode.standardize(detectedSourceLanguage);
     this.billedCharacters = billedCharacters;
+    this.modelTypeUsed = modelTypeUsed;
   }
 
   /** The translated text. */
@@ -30,4 +38,9 @@ public String getDetectedSourceLanguage() {
   public int getBilledCharacters() {
     return billedCharacters;
   }
+
+  /** Model type used for the translation of this text. */
+  public @Nullable String getModelTypeUsed() {
+    return modelTypeUsed;
+  }
 }

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

@@ -20,6 +20,7 @@ public class TextTranslationOptions {
   private boolean preserveFormatting = false;
   private String context;
   private String tagHandling;
+  private String modelType;
   private boolean outlineDetection = true;
   private Iterable<String> ignoreTags;
   private Iterable<String> nonSplittingTags;
@@ -106,6 +107,20 @@ public TextTranslationOptions setTagHandling(String tagHandling) {
     return this;
   }
 
+  /**
+   * Set the type of model to use for a text translation. Currently supported values: <code>
+   * "quality_optimized"</code> use a translation model that maximizes translation quality, at the
+   * cost of response time. This option may be unavailable for some language pairs and the API would
+   * respond with an error in this case; <code>"prefer_quality_optimized"</code> use the
+   * highest-quality translation model for the given language pair; <code>"latency_optimized"
+   * </code> use a translation model that minimizes response time, at the cost of translation
+   * quality.
+   */
+  public TextTranslationOptions setModelType(String modelType) {
+    this.modelType = modelType;
+    return this;
+  }
+
   /**
    * Sets whether outline detection is used; set to <code>false</code> to disable automatic tag
    * detection, default is <code>true</code>.
@@ -167,6 +182,11 @@ public String getContext() {
     return context;
   }
 
+  /** Gets the current model type. */
+  public String getModelType() {
+    return modelType;
+  }
+
   /** Gets the current tag handling setting. */
   public String getTagHandling() {
     return tagHandling;

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

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

deepl-java/src/main/java/com/deepl/api/parsing/TextResultDeserializer.java

@@ -16,9 +16,11 @@ class TextResultDeserializer implements JsonDeserializer<TextResult> {
   public TextResult deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context)
       throws JsonParseException {
     JsonObject jsonObject = json.getAsJsonObject();
+    JsonElement modelType = jsonObject.get("model_type_used");
     return new TextResult(
         jsonObject.get("text").getAsString(),
         jsonObject.get("detected_source_language").getAsString(),
-        jsonObject.get("billed_characters").getAsInt());
+        jsonObject.get("billed_characters").getAsInt(),
+        modelType != null ? (modelType.getAsString()) : null);
   }
 }

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

@@ -3,8 +3,6 @@
 // license that can be found in the LICENSE file.
 package com.deepl.api;
 
-import static org.mockito.Mockito.*;
-
 import java.io.*;
 import java.net.*;
 import java.time.*;
@@ -13,6 +11,7 @@
 import org.junit.jupiter.api.*;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.CsvSource;
 import org.junit.jupiter.params.provider.MethodSource;
 import org.mockito.MockedConstruction;
 import org.mockito.Mockito;
@@ -49,6 +48,25 @@ void testExampleTranslation() throws DeepLException, InterruptedException {
     }
   }
 
+  @ParameterizedTest
+  @CsvSource({
+    "quality_optimized,quality_optimized",
+    "prefer_quality_optimized,quality_optimized",
+    "latency_optimized,latency_optimized"
+  })
+  void testModelType(String modelTypeArg, String expectedModelType)
+      throws DeepLException, InterruptedException {
+    Translator translator = createTranslator();
+    String sourceLang = "de";
+    TextResult result =
+        translator.translateText(
+            exampleText.get(sourceLang),
+            sourceLang,
+            "en-US",
+            new TextTranslationOptions().setModelType(modelTypeArg));
+    Assertions.assertEquals(expectedModelType, result.getModelTypeUsed());
+  }
+
   @Test
   void testInvalidServerUrl() {
     Assertions.assertThrows(