feat: Add support for custom_instructions parameter in text translation

Author: BriannaDelgado

README.md

@@ -181,6 +181,13 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
     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.
+-   `customInstructions`: an array of instructions to customize the translation behavior.
+    Up to 10 custom instructions can be specified, each with a maximum of 300 characters.
+    Important: The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`
+    or any variants of these languages.
+    Note: Any request with the `customInstructions` parameter enabled will use 
+    the `quality_optimized` model type as the default. Requests combining 
+    `customInstructions` and `modelType: latency_optimized` will be rejected.
 -   `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

src/types.ts

@@ -184,6 +184,12 @@ export interface TranslateTextOptions extends BaseRequestOptions {
     /** List of XML tags containing content that should not be translated. */
     ignoreTags?: TagList;
 
+    /**
+     * List of custom instructions to guide the translation. Maximum 10 instructions,
+     * each with a maximum length of 300 characters.
+     */
+    customInstructions?: string[];
+
     /** (internal only) Override path to send translate request to. */
     __path?: string;
 }

src/utils.ts

@@ -285,6 +285,11 @@ export function validateAndAppendTextOptions(
             data.append('style_id', options.styleRule.styleId);
         }
     }
+    if (options.customInstructions !== undefined) {
+        for (const instruction of options.customInstructions) {
+            data.append('custom_instructions', instruction);
+        }
+    }
 }
 
 /**

tests/translateText.test.ts

@@ -281,6 +281,25 @@ describe('translate text', () => {
         expect(result.billedCharacters).toBe(exampleText.en.length);
     });
 
+    withRealServer('should translate with custom instructions', async () => {
+        const translator = makeTranslator();
+        const text = 'Hello world. I am testing if custom instructions are working correctly.';
+        const resultWithCustomInstructions = await translator.translateText(text, null, 'de', {
+            customInstructions: ['Use informal language', 'Be concise'],
+        });
+        const resultWithoutCustomInstructions = await translator.translateText(text, null, 'de');
+        expect(resultWithCustomInstructions.text).toBeTruthy();
+        expect(resultWithoutCustomInstructions.text).not.toBe(resultWithCustomInstructions.text);
+    });
+
+    it('should translate with empty custom instructions array', async () => {
+        const translator = makeTranslator();
+        const result = await translator.translateText(exampleText.en, null, 'de', {
+            customInstructions: [],
+        });
+        expect(result.text).toBe(exampleText.de);
+    });
+
     describe('request parameter tests', () => {
         beforeAll(() => {
             nock.disableNetConnect();