feat: accept any string for text option enums and parse tagHandlingVersion

Formality, SentenceSplittingMode, TagHandlingMode, TagHandlingVersion and
ModelType accept any string besides their listed values, so new API
values need no type cast. SentenceSplittingMode lists the API values '1'
and '0'; 'on' and 'default' are deprecated in favour of '1'.

TextResult gains tagHandlingVersion, parsed from the response field
tag_handling_version; undefined when absent or not a string.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Added `tagHandlingVersion` to `TextResult`: the tag handling version used, parsed
+  from the response; `undefined` when the API does not return it.
+- `SentenceSplittingMode` accepts `'1'` and `'0'`, the API values, which are sent
+  unchanged.
 - Added the `extraBodyParameters` option to `BaseRequestOptions`, and so to
   `TranslateTextOptions`, `DocumentTranslateOptions` and `RephraseTextOptions`.
   It replaces `extraRequestParameters` and behaves the same. Passing both
@@ -92,6 +96,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `updateStyleRuleCustomInstruction(styleId, instructionId, label, prompt, sourceLanguage?)`.
 
 ### Changed
+- `Formality`, `SentenceSplittingMode`, `TagHandlingMode`, `TagHandlingVersion`
+  and `ModelType` accept any string in addition to their listed values, so values
+  the API adds later can be passed without a type cast.
 - Every HTTP 404 response now throws `NotFoundError`; before, only glossary
   requests threw an error class of their own (`GlossaryNotFoundError`, which
   is still thrown there) and other requests threw a plain `DeepLError`.
@@ -116,6 +123,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   limit and links to the DeepL API usage limits instead.
 
 ### Deprecated
+- `SentenceSplittingMode` values `'on'` and `'default'` are deprecated. Use `'1'`
+  instead.
 - `extraRequestParameters` is deprecated; use `extraBodyParameters` instead.
   It will be removed in the next major version.
 - `Translator` and `TranslatorOptions` are deprecated; use `DeepLClient` and

README.md

@@ -139,6 +139,8 @@ following properties:
 - `billedCharacters` is the number of characters billed for the text.
 - `modelTypeUsed` indicates the translation model used, but is `undefined`
   unless the `modelType` option is specified.
+- `tagHandlingVersion` is the tag handling version used (for example `'v2'`), or
+  `undefined` unless the `tagHandling` option is specified.
 
 ```javascript
 // Translate text into a target language, in this case, French:
@@ -166,13 +168,14 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
 #### Text translation options
 
 -   `splitSentences`: specify how input text should be split into sentences,
-    default: `'on'`.
-    -   `'on'`: input text will be split into sentences using both newlines and
+    default: `'1'`.
+    -   `'1'`: input text will be split into sentences using both newlines and
         punctuation.
-    -   `'off'`: input text will not be split into sentences. Use this for
+    -   `'0'` or `'off'`: input text will not be split into sentences. Use this for
         applications where each input text contains only one sentence.
     -   `'nonewlines'`: input text will be split into sentences using punctuation
         but not newlines.
+    -   `'on'` and `'default'` are deprecated aliases of `'1'`.
 -   `preserveFormatting`: controls automatic-formatting-correction. Set to `true`
     to prevent automatic-correction of formatting, default: `false`.
 -   `formality`: controls whether translations should lean toward informal or
@@ -231,6 +234,10 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
 -   `tagHandlingVersion`: specifies which version of the tag handling algorithm to use.
     Options are `v1` and `v2`.
 
+`formality`, `splitSentences`, `modelType`, `tagHandling` and `tagHandlingVersion`
+also accept any other string, which is sent to the API unchanged; this allows values
+the API adds later to be used without a library update.
+
 The following options are only used if `tagHandling` is `'xml'`:
 
 -   `outlineDetection`: specify `false` to disable automatic tag detection,

src/parsing.ts

@@ -126,6 +126,7 @@ interface TextResultApiResponse {
     detected_source_language: string;
     billed_characters: number;
     model_type_used?: string;
+    tag_handling_version?: unknown;
 }
 
 /**
@@ -623,6 +624,10 @@ export function parseUsage(json: string): Usage {
     }
 }
 
+function parseOptionalString(value: unknown): string | undefined {
+    return typeof value === 'string' ? value : undefined;
+}
+
 /**
  * Parses the given JSON string to an array of TextResult objects.
  * @private
@@ -638,6 +643,7 @@ export function parseTextResultArray(json: string): TextResult[] {
                 ) as SourceLanguageCode,
                 billedCharacters: translation.billed_characters,
                 modelTypeUsed: translation.model_type_used,
+                tagHandlingVersion: parseOptionalString(translation.tag_handling_version),
             };
         });
     } catch (error) {
@@ -874,10 +880,6 @@ function parseIdList(value: unknown): string[] {
     return Array.isArray(value) ? value.filter((id): id is string => typeof id === 'string') : [];
 }
 
-function parseOptionalString(value: unknown): string | undefined {
-    return typeof value === 'string' ? value : undefined;
-}
-
 function parseRawStyleProfile(obj: StyleProfileApiResponse): StyleProfile {
     return {
         styleProfileId: obj.style_profile_id ?? '',

src/types.ts

@@ -88,11 +88,36 @@ export interface DeepLClientOptions extends HttpClientOptions {
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface TranslatorOptions extends DeepLClientOptions {}
 
-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';
+// `string & Record<never, never>` accepts any string, e.g. values the API adds later, while
+// keeping editor completion for the listed members.
+export type Formality =
+    | 'less'
+    | 'more'
+    | 'default'
+    | 'prefer_less'
+    | 'prefer_more'
+    | (string & Record<never, never>);
+/**
+ * Sentence splitting mode: '1' (split on punctuation and newlines), '0' (no splitting) or
+ * 'nonewlines' (split on punctuation only). 'off' is sent as '0'.
+ * 'on' and 'default' are deprecated: use '1' instead. They will be removed in the next major
+ * version.
+ */
+export type SentenceSplittingMode =
+    | '1'
+    | '0'
+    | 'off'
+    | 'nonewlines'
+    | 'on'
+    | 'default'
+    | (string & Record<never, never>);
+export type TagHandlingMode = 'html' | 'xml' | (string & Record<never, never>);
+export type TagHandlingVersion = 'v1' | 'v2' | (string & Record<never, never>);
+export type ModelType =
+    | 'quality_optimized'
+    | 'latency_optimized'
+    | 'prefer_quality_optimized'
+    | (string & Record<never, never>);
 export type GlossaryId = string;
 export type StyleId = string;
 export type TranslationMemoryId = string;
@@ -151,10 +176,10 @@ export interface GlossaryInfo {
 export interface TranslateTextOptions extends BaseRequestOptions {
     /**
      * Specifies how input translation text should be split into sentences.
-     * - 'on': Input translation text will be split into sentences using both newlines and
+     * - '1': Input translation text will be split into sentences using both newlines and
      *   punctuation, this is the default behaviour.
-     * - 'off': Input translation text will not be split into sentences. This is advisable for
-     *   applications where each input translation text is only one sentence.
+     * - '0' or 'off': Input translation text will not be split into sentences. This is advisable
+     *   for applications where each input translation text is only one sentence.
      * - 'nonewlines': Input translation text will be split into sentences using only punctuation
      *   but not newlines.
      */
@@ -801,6 +826,11 @@ export interface TextResult {
      * The translation model type used, if available.
      */
     readonly modelTypeUsed?: string;
+
+    /**
+     * The tag handling version used, present when tag handling was requested.
+     */
+    readonly tagHandlingVersion?: TagHandlingVersion;
 }
 
 /**

tests/offline/translateText.test.ts

@@ -56,6 +56,27 @@ describe('Translator.translateText', () => {
         });
     });
 
+    it('parses tag_handling_version, and leaves it undefined when it is not a string', async () => {
+        const reply = (version: unknown) => ({
+            translations: [
+                {
+                    detected_source_language: 'EN',
+                    text: 'out',
+                    billed_characters: 3,
+                    tag_handling_version: version,
+                },
+            ],
+        });
+        expectTranslateBody(baseBody, reply('v2'));
+        expectTranslateBody(baseBody, reply(2));
+        const translator = makeTranslator();
+
+        expect((await translator.translateText('abc', null, 'de')).tagHandlingVersion).toBe('v2');
+        expect(
+            (await translator.translateText('abc', null, 'de')).tagHandlingVersion,
+        ).toBeUndefined();
+    });
+
     it('sends every text of an array and parses one result per text', async () => {
         expectTranslateBody(
             { ...baseBody, text: ['a', 'b'] },
@@ -103,6 +124,8 @@ describe('Translator.translateText', () => {
         ['off', '0'],
         ['nonewlines', 'nonewlines'],
         ['OFF', '0'],
+        ['1', '1'],
+        ['0', '0'],
     ])('sends splitSentences %s as %s', async (splitSentences, sent) => {
         expectTranslateBody({ ...baseBody, split_sentences: sent });
 
@@ -113,15 +136,32 @@ describe('Translator.translateText', () => {
 
     it('does not change the splitSentences value of the caller options', async () => {
         expectTranslateBody({ ...baseBody, split_sentences: '0' });
-        const options: deepl.TranslateTextOptions = {
-            splitSentences: <deepl.SentenceSplittingMode>'OFF',
-        };
+        const options: deepl.TranslateTextOptions = { splitSentences: 'OFF' };
 
         await makeTranslator().translateText('abc', null, 'de', options);
 
         expect(options.splitSentences).toBe('OFF');
     });
 
+    it('sends enum option values that are not listed in their types', async () => {
+        expectTranslateBody({
+            ...baseBody,
+            formality: 'future_formality',
+            split_sentences: 'future_mode',
+            tag_handling: 'future_markup',
+            tag_handling_version: 'v3',
+            model_type: 'future_model',
+        });
+
+        await makeTranslator().translateText('abc', null, 'de', {
+            formality: 'future_formality',
+            splitSentences: 'future_mode',
+            tagHandling: 'future_markup',
+            tagHandlingVersion: 'v3',
+            modelType: 'future_model',
+        });
+    });
+
     it.each([
         [true, '1'],
         [false, '0'],