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 `tag_handling_version` parameter to `translateText()` specify which version of the tag handling algorithm to use. Options are `v1` and `v2`.
 
 ## [1.15.0] - 2025-12-03
 ### Added

README.md

@@ -132,6 +132,9 @@ using the following keys:
     - `'prefer_more'`: use formal, more polite language if available, otherwise default.
 -   `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`. This parameter is only relevant when `tag_handling` is set to
+    `'html'` or `'xml'`.
 -   `context`: specifies additional context to influence translations, that is not
     translated itself. Characters in the `context` parameter are not counted toward billing.
     See the [API documentation][api-docs-context-param] for more information and

src/TranslateTextOptions.php

@@ -45,6 +45,9 @@ class TranslateTextOptions
     /** Type of tags to parse before translation, options are 'html' and 'xml'. */
     public const TAG_HANDLING = 'tag_handling';
 
+    /** Version of tag handling algorithm to use, options are 'v1' and 'v2'. */
+    public const TAG_HANDLING_VERSION = 'tag_handling_version';
+
     /** Set to false to disable automatic tag detection, default is true. */
     public const OUTLINE_DETECTION = 'outline_detection';
 

src/Translator.php

@@ -671,6 +671,9 @@ private function validateAndAppendTextOptions(array &$params, ?array $options):
         if (isset($options[TranslateTextOptions::TAG_HANDLING])) {
             $params[TranslateTextOptions::TAG_HANDLING] = $options[TranslateTextOptions::TAG_HANDLING];
         }
+        if (isset($options[TranslateTextOptions::TAG_HANDLING_VERSION])) {
+            $params[TranslateTextOptions::TAG_HANDLING_VERSION] = $options[TranslateTextOptions::TAG_HANDLING_VERSION];
+        }
         if (isset($options[TranslateTextOptions::OUTLINE_DETECTION])) {
             $params[TranslateTextOptions::OUTLINE_DETECTION] =
                 $this->toBoolString($options[TranslateTextOptions::OUTLINE_DETECTION]);

tests/TranslateTextTest.php

@@ -97,6 +97,32 @@ public function testHandlingResponseWithInvalidUtf8(?ClientInterface $httpClient
         $this->assertInstanceOf(TextResult::class, $result);
     }
 
+    /**
+     * @dataProvider provideHttpClient
+     */
+    public function testTagHandlingVersion(?ClientInterface $httpClient)
+    {
+        $this->needsRealServer();
+        $translator = $this->makeTranslator([TranslatorOptions::HTTP_CLIENT => $httpClient]);
+        $text = '<p>Hello world</p>';
+
+        $resultV1 = $translator->translateText($text, 'en', 'de', [
+            TranslateTextOptions::TAG_HANDLING => 'html',
+            TranslateTextOptions::TAG_HANDLING_VERSION => 'v1',
+        ]);
+        $this->assertInstanceOf(TextResult::class, $resultV1);
+        $this->assertNotNull($resultV1->text);
+        $this->assertNotEmpty($resultV1->text);
+
+        $resultV2 = $translator->translateText($text, 'en', 'de', [
+            TranslateTextOptions::TAG_HANDLING => 'html',
+            TranslateTextOptions::TAG_HANDLING_VERSION => 'v2',
+        ]);
+        $this->assertInstanceOf(TextResult::class, $resultV2);
+        $this->assertNotNull($resultV2->text);
+        $this->assertNotEmpty($resultV2->text);
+    }
+
     /**
      * @dataProvider provideHttpClient
      */