feat: Add tag_handling_version parameter to translate_text

Author: jason-gardella-deepl

CHANGELOG.md

@@ -6,6 +6,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Added `tag_handling_version` parameter to `translate_text()` to specify which version
+  of the tag handling algorithm to use. Options are `v1` and `v2`.
 - Added an example CLI script for realtime audio translation using DeepL's Voice API.
 
 ## [1.26.0] - 2025-12-03

README.md

@@ -173,6 +173,8 @@ arguments are:
     model that minimizes response time, at the cost of translation quality.
 - `tag_handling`: type of tags to parse before translation, options are `'html'`
   and `'xml'`.
+- `tag_handling_version`: specifies which version of the tag handling algorithm to
+  use, options are `'v1'` and `'v2'`.
 - `style_rule`: specifies a style rule to use with translation, either as a string
   containing the ID of the style rule, or a `StyleRuleInfo` object.
 - `custom_instructions`: an array of instructions to customize the text 

deepl/__main__.py

@@ -422,6 +422,13 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
         default=None,
         help="activate processing of formatting tags, for example 'xml'",
     )
+    tag_handling_group.add_argument(
+        "--tag-handling-version",
+        type=str,
+        choices=["v1", "v2"],
+        default=None,
+        help="specify which version of the tag handling algorithm to use",
+    )
     tag_handling_group.add_argument(
         "--outline-detection-off",
         dest="outline_detection",

deepl/translator.py

@@ -376,6 +376,7 @@ def translate_text(
             str, GlossaryInfo, MultilingualGlossaryInfo, None
         ] = None,
         tag_handling: Optional[str] = None,
+        tag_handling_version: Optional[str] = None,
         outline_detection: Optional[bool] = None,
         non_splitting_tags: Union[str, List[str], None] = None,
         splitting_tags: Union[str, List[str], None] = None,
@@ -414,6 +415,8 @@ def translate_text(
             translation.
         :param tag_handling: (Optional) Type of tags to parse before
             translation, only "xml" and "html" are currently available.
+        :param tag_handling_version: (Optional) Version of tag handling
+            algorithm to use, "v1" or "v2".
         :param outline_detection: (Optional) Set to False to disable automatic
             tag detection.
         :param non_splitting_tags: (Optional) XML tags that should not split a
@@ -469,6 +472,8 @@ def translate_text(
             request_data["preserve_formatting"] = bool(preserve_formatting)
         if tag_handling is not None:
             request_data["tag_handling"] = tag_handling
+        if tag_handling_version is not None:
+            request_data["tag_handling_version"] = tag_handling_version
         if outline_detection is not None:
             request_data["outline_detection"] = bool(outline_detection)
         if model_type is not None:

tests/test_translate_text.py

@@ -443,3 +443,25 @@ def test_custom_instructions(translator):
     assert (
         custom_instructions_result.text != no_custom_instructions_result.text
     )
+
+
+@needs_real_server
+def test_tag_handling_version_v1(translator):
+    text = "<p>Hello world</p>"
+    result = translator.translate_text(
+        text, target_lang="DE", tag_handling="html", tag_handling_version="v1"
+    )
+    assert isinstance(result, deepl.TextResult)
+    assert result.text is not None
+    assert len(result.text) > 0
+
+
+@needs_real_server
+def test_tag_handling_version_v2(translator):
+    text = "<p>Hello world</p>"
+    result = translator.translate_text(
+        text, target_lang="DE", tag_handling="html", tag_handling_version="v2"
+    )
+    assert isinstance(result, deepl.TextResult)
+    assert result.text is not None
+    assert len(result.text) > 0