feat: Add tag_handling_version parameter to translate_text

Author: jason-gardella-deepl

CHANGELOG.md

@@ -5,6 +5,8 @@ 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 `setTagHandlingVersion()` method to `TextTranslationOptions` to specify which version of the tag handling algorithm to use. Options are `v1` and `v2`.
 
 ## [1.13.0] - 2025-12-03
 ### Added

README.md

@@ -187,6 +187,7 @@ a `TextTranslationOptions`, with the following setters:
     cost of translation quality.
 - `setTagHandling()`: type of tags to parse before translation, options are
   `"html"` and `"xml"`.
+- `setTagHandlingVersion()`: specifies which version of the tag handling algorithm to use. Options are `"v1"` and `"v2"`.
 
 The following options are only used if `setTagHandling()` is set to `'xml'`:
 

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

@@ -21,6 +21,7 @@ public class TextTranslationOptions extends BaseRequestOptions {
   private boolean preserveFormatting = false;
   private String context;
   private String tagHandling;
+  private String tagHandlingVersion;
   private String modelType;
   private boolean outlineDetection = true;
   private Iterable<String> ignoreTags;
@@ -126,6 +127,15 @@ public TextTranslationOptions setTagHandling(String tagHandling) {
     return this;
   }
 
+  /**
+   * Sets the version of tag handling algorithm to use. By default, this value is <code>null</code>
+   * and the API default is used.
+   */
+  public TextTranslationOptions setTagHandlingVersion(String tagHandlingVersion) {
+    this.tagHandlingVersion = tagHandlingVersion;
+    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
@@ -225,6 +235,11 @@ public String getTagHandling() {
     return tagHandling;
   }
 
+  /** Gets the current tag handling version. */
+  public String getTagHandlingVersion() {
+    return tagHandlingVersion;
+  }
+
   /** Gets the current outline detection setting. */
   public boolean isOutlineDetection() {
     return outlineDetection;

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

@@ -833,6 +833,9 @@ private static ArrayList<KeyValuePair<String, String>> createHttpParams(
       if (options.getTagHandling() != null) {
         params.add(new KeyValuePair<>("tag_handling", options.getTagHandling()));
       }
+      if (options.getTagHandlingVersion() != null) {
+        params.add(new KeyValuePair<>("tag_handling_version", options.getTagHandlingVersion()));
+      }
       if (!options.isOutlineDetection()) {
         params.add(new KeyValuePair<>("outline_detection", "0"));
       }

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

@@ -299,6 +299,38 @@ void testTagHandlingHTML() throws DeepLException, InterruptedException {
     }
   }
 
+  @Test
+  void testTagHandlingVersionV1() throws DeepLException, InterruptedException {
+    Translator translator = createTranslator();
+    String text = "<p>Hello world</p>";
+
+    TextResult result =
+        translator.translateText(
+            text,
+            null,
+            "de",
+            new TextTranslationOptions().setTagHandling("html").setTagHandlingVersion("v1"));
+    Assertions.assertNotNull(result);
+    Assertions.assertNotNull(result.getText());
+    Assertions.assertFalse(result.getText().isEmpty());
+  }
+
+  @Test
+  void testTagHandlingVersionV2() throws DeepLException, InterruptedException {
+    Translator translator = createTranslator();
+    String text = "<p>Hello world</p>";
+
+    TextResult result =
+        translator.translateText(
+            text,
+            null,
+            "de",
+            new TextTranslationOptions().setTagHandling("html").setTagHandlingVersion("v2"));
+    Assertions.assertNotNull(result);
+    Assertions.assertNotNull(result.getText());
+    Assertions.assertFalse(result.getText().isEmpty());
+  }
+
   @Test
   void testEmptyText() {
     Translator translator = createTranslator();