feat: add modelType option for text translation

Author: daniel-jones-dev

README.md

@@ -127,6 +127,8 @@ following properties:
 - `text` is the translated text,
 - `detectedSourceLang` is the detected source language code,
 - `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.
 
 ```javascript
 // Translate text into a target language, in this case, French:
@@ -180,6 +182,14 @@ console.log(await translator.translateText('How are you?', null, 'de', { formali
     translated itself. Characters in the `context` parameter are not counted toward billing.
     See the [API documentation][api-docs-context-param] for more information and
     example usage.
+-   `modelType`: specifies the type of translation model to use, options are:
+    - `'quality_optimized'`: use a translation model that maximizes translation
+      quality, at the cost of response time. This option may be unavailable for
+      some language pairs.
+    - `'prefer_quality_optimized'`: use the highest-quality translation model 
+      for the given language pair.
+    - `'latency_optimized'`: use a translation model that minimizes response
+      time, at the cost of translation quality.
 -   `tagHandling`: type of tags to parse before translation, options are `'html'`
     and `'xml'`.
 

src/index.ts

@@ -228,6 +228,11 @@ export interface TextResult {
      * Number of characters billed for this text.
      */
     readonly billedCharacters: number;
+
+    /**
+     * The translation model type used, if available.
+     */
+    readonly modelTypeUsed?: string;
 }
 
 /**
@@ -384,6 +389,9 @@ function validateAndAppendTextOptions(data: URLSearchParams, options?: Translate
     if (options.context !== undefined) {
         data.append('context', options.context);
     }
+    if (options.modelType !== undefined) {
+        data.append('model_type', options.modelType);
+    }
     if (options.nonSplittingTags !== undefined) {
         data.append('non_splitting_tags', joinTagList(options.nonSplittingTags));
     }

src/parsing.ts

@@ -61,6 +61,7 @@ interface TextResultApiResponse {
     text: string;
     detected_source_language: string;
     billed_characters: number;
+    model_type_used?: string;
 }
 
 /**
@@ -312,6 +313,7 @@ export function parseTextResultArray(json: string): TextResult[] {
                     translation.detected_source_language,
                 ) as SourceLanguageCode,
                 billedCharacters: translation.billed_characters,
+                modelTypeUsed: translation.model_type_used,
             };
         });
     } catch (error) {

src/types.ts

@@ -76,6 +76,7 @@ export interface 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 ModelType = 'quality_optimized' | 'latency_optimized' | 'prefer_quality_optimized';
 export type GlossaryId = string;
 export type TagList = string | string[];
 
@@ -136,6 +137,9 @@ export interface TranslateTextOptions {
      * See the API documentation for more information and example usage. */
     context?: string;
 
+    /** Type of translation model to use. */
+    modelType?: ModelType;
+
     /** List of XML tags that should be used to split text into sentences. */
     splittingTags?: TagList;
 

tests/translateText.test.ts

@@ -14,7 +14,7 @@ import {
     withMockServer,
     withRealServer,
 } from './core';
-import { QuotaExceededError, TranslateTextOptions } from 'deepl-node';
+import { ModelType, QuotaExceededError, TranslateTextOptions } from 'deepl-node';
 
 describe('translate text', () => {
     it('should translate a single text', async () => {
@@ -25,6 +25,19 @@ describe('translate text', () => {
         expect(result.billedCharacters).toBe(exampleText.en.length);
     });
 
+    it.each([['quality_optimized'], ['latency_optimized'], ['prefer_quality_optimized']])(
+        'should translate using model_type = %s',
+        async (modelTypeStr) => {
+            const translator = makeTranslator();
+            const modelType = modelTypeStr as ModelType;
+            const result = await translator.translateText(exampleText.en, 'en', 'de', {
+                modelType: modelType,
+            });
+            const expectedModelTypeUsed = modelType.replace('prefer_', '');
+            expect(result.modelTypeUsed).toBe(expectedModelTypeUsed);
+        },
+    );
+
     it('should translate an array of texts', async () => {
         const translator = makeTranslator();
         const result = await translator.translateText([exampleText.fr, exampleText.en], null, 'de');