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

README.md

@@ -198,6 +198,8 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
       time, at the cost of translation quality.
 -   `tagHandling`: type of tags to parse before translation, options are `'html'`
     and `'xml'`.
+-   `tagHandlingVersion`: specifies which version of the tag handling algorithm to use.
+    Options are `v1` and `v2`.
 
 The following options are only used if `tagHandling` is `'xml'`:
 

src/types.ts

@@ -84,6 +84,7 @@ export interface DeepLClientOptions extends TranslatorOptions {}
 export type Formality = 'less' | 'more' | 'default' | 'prefer_less' | 'prefer_more';
 export type SentenceSplittingMode = 'off' | 'on' | 'nonewlines' | 'default';
 export type TagHandlingMode = 'html' | 'xml';
+export type TagHandlingVersion = 'v1' | 'v2';
 export type ModelType = 'quality_optimized' | 'latency_optimized' | 'prefer_quality_optimized';
 export type GlossaryId = string;
 export type StyleId = string;
@@ -163,6 +164,9 @@ export interface TranslateTextOptions extends BaseRequestOptions {
     /** Type of tags to parse before translation, options are 'html' and 'xml'. */
     tagHandling?: TagHandlingMode;
 
+    /** Version of tag handling to use, options are 'v1' and 'v2'. */
+    tagHandlingVersion?: TagHandlingVersion;
+
     /** Set to false to disable automatic tag detection, default is true. */
     outlineDetection?: boolean;
 

src/utils.ts

@@ -257,6 +257,9 @@ export function validateAndAppendTextOptions(
     if (options.tagHandling !== undefined) {
         data.append('tag_handling', options.tagHandling);
     }
+    if (options.tagHandlingVersion !== undefined) {
+        data.append('tag_handling_version', options.tagHandlingVersion);
+    }
     if (options.outlineDetection !== undefined) {
         data.append('outline_detection', toBoolString(options.outlineDetection));
     }

tests/translateText.test.ts

@@ -213,6 +213,26 @@ describe('translate text', () => {
         await translator.translateText(text, null, 'de', { tagHandling: 'html' });
     });
 
+    it('should translate with tag_handling_version option', async () => {
+        const text = '<p>Hello world</p>';
+        const translator = makeTranslator();
+        // Test with v1
+        const resultV1 = await translator.translateText(text, null, 'de', {
+            tagHandling: 'html',
+            tagHandlingVersion: 'v1',
+        });
+        expect(resultV1.text).toBeTruthy();
+        expect(resultV1.detectedSourceLang).toBe('en');
+
+        // Test with v2
+        const resultV2 = await translator.translateText(text, null, 'de', {
+            tagHandling: 'html',
+            tagHandlingVersion: 'v2',
+        });
+        expect(resultV2.text).toBeTruthy();
+        expect(resultV2.detectedSourceLang).toBe('en');
+    });
+
     it('should translate with context option', async () => {
         const translator = makeTranslator();
         const text = 'Das ist scharf!';