feat: add the styleProfile option to text and document translation

Sends style_profile_id with the ID of a style profile string or a
StyleProfile object on /v2/translate and /v2/document.

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 the `styleProfile` option to `TranslateTextOptions` and
+  `DocumentTranslateOptions` to translate text and documents with a style
+  profile, given as its ID or a `StyleProfile` object. It is sent as
+  `style_profile_id`.
 - Added style profiles (`/v3/style_profiles`) to `DeepLClient`:
   `listStyleProfiles()`, `createStyleProfile()`, `getStyleProfile()`,
   `updateStyleProfile()` and `deleteStyleProfile()`. Added the `StyleProfile`,

README.md

@@ -183,6 +183,13 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
     `sourceLang` to be set, and cannot be combined with the singular `glossary` option.
 -   `styleRule`: specifies a style rule to use with translation, either as a string
     containing the style rule ID, or a `StyleRuleInfo` as returned by `getAllStyleRules()`.
+-   `styleProfile`: specifies a style profile to use with translation, either as a
+    string containing the style profile ID, or a `StyleProfile` as returned by
+    `getStyleProfile()`. The profile applies its linked glossaries, style rule lists and
+    translation memories; a component that does not fit the language pair is left out.
+    Does not require `sourceLang`. Cannot be combined with `glossary`, `glossaryIds`,
+    `styleRule`, `translationMemory`, `translationMemoryThreshold` or
+    `customInstructions`; the API rejects such requests.
 -   `translationMemory`: specifies a translation memory to use with translation,
     either as a string containing the translation memory ID, or a
     `TranslationMemoryInfo` as returned by `listTranslationMemories()`.
@@ -286,6 +293,9 @@ directly:
 -   `glossary`: same as in [Text translation options](#text-translation-options).
 -   `glossaryIds`: same as in [Text translation options](#text-translation-options).
 -   `styleRule`: same as in [Text translation options](#text-translation-options).
+-   `styleProfile`: same as in [Text translation options](#text-translation-options).
+    A style profile that does not exist fails the translation with a
+    `DocumentTranslationError` whose message contains `Style profile not found.`.
 -   `translationMemory`: same as in [Text translation options](#text-translation-options).
 -   `translationMemoryThreshold`: same as in [Text translation options](#text-translation-options).
 -   `filename`: if the input file is not provided as file path, this option is
@@ -704,6 +714,18 @@ console.log(updated.description); // undefined
 await deeplClient.deleteStyleProfile(styleProfile);
 ```
 
+To translate with a style profile, pass it as the `styleProfile` option of text or
+document translation:
+
+```javascript
+const result = await deeplClient.translateText('The artist is here.', null, 'de', {
+    styleProfile: 'YOUR_STYLE_PROFILE_ID',
+});
+await deeplClient.translateDocument('input.docx', 'output.docx', null, 'de', {
+    styleProfile: styleProfile,
+});
+```
+
 ### Translation Memories
 
 Translation memories store and reuse previously created translations, helping to

src/types.ts

@@ -178,6 +178,14 @@ export interface TranslateTextOptions extends BaseRequestOptions {
      */
     styleRule?: StyleId | StyleRuleInfo;
 
+    /** Specifies the ID of a style profile to use with translation, or a StyleProfile object
+     * as returned by getStyleProfile(). The style profile applies its linked glossaries, style
+     * rule lists and translation memories; a component that does not fit the language pair is
+     * left out. Cannot be combined with the glossary, style rule, translation memory or custom
+     * instructions options; the API rejects such requests.
+     */
+    styleProfile?: string | StyleProfile;
+
     /** Specifies the ID of a translation memory to use with translation, or
      * a TranslationMemoryInfo object as returned by listTranslationMemories().
      */
@@ -252,6 +260,15 @@ export interface DocumentTranslateOptions extends BaseRequestOptions {
      */
     styleRule?: StyleId | StyleRuleInfo;
 
+    /** Specifies the ID of a style profile to use with translation, or a StyleProfile object
+     * as returned by getStyleProfile(). The style profile applies its linked glossaries, style
+     * rule lists and translation memories; a component that does not fit the language pair is
+     * left out. Cannot be combined with the glossary, style rule or translation memory options;
+     * the API rejects such requests. A style profile that does not exist fails the document
+     * translation with a DocumentTranslationError.
+     */
+    styleProfile?: string | StyleProfile;
+
     /** Specifies the ID of a translation memory to use with translation, or
      * a TranslationMemoryInfo object as returned by listTranslationMemories().
      */

src/utils.ts

@@ -267,7 +267,7 @@ export function appendTextsAndReturnIsSingular(
 }
 
 /**
- * Validates and appends style-rule and translation-memory options to HTTP request parameters.
+ * Validates and appends style-rule, style-profile and translation-memory options to HTTP request parameters.
  * These options are shared between text and document translation requests.
  * @param data Parameters for HTTP request.
  * @param options Options containing style-rule and translation-memory fields.
@@ -277,6 +277,7 @@ export function appendStyleAndTranslationMemoryOptions(
     data: URLSearchParams,
     options: {
         styleRule?: StyleId | StyleRuleInfo;
+        styleProfile?: string | StyleProfile;
         translationMemory?: TranslationMemoryId | TranslationMemoryInfo;
         translationMemoryThreshold?: number;
     },
@@ -293,6 +294,18 @@ export function appendStyleAndTranslationMemoryOptions(
             data.append('style_id', options.styleRule);
         }
     }
+    if (options.styleProfile !== undefined) {
+        if (!isString(options.styleProfile)) {
+            if (options.styleProfile.styleProfileId === undefined) {
+                throw new DeepLError(
+                    'styleProfile option should be a string containing the style profile ID or a StyleProfile object.',
+                );
+            }
+            data.append('style_profile_id', options.styleProfile.styleProfileId);
+        } else {
+            data.append('style_profile_id', options.styleProfile);
+        }
+    }
     if (options.translationMemory !== undefined) {
         if (!isString(options.translationMemory)) {
             if (options.translationMemory.translationMemoryId === undefined) {

tests/offline/translateDocument.test.ts

@@ -67,6 +67,35 @@ describe('Translator.uploadDocument', () => {
         expect(result).toEqual(handle);
     });
 
+    it('sends the style profile ID of a string and of a StyleProfile as one part', async () => {
+        const translator = makeTranslator();
+        for (const [styleProfile, id] of <Array<[string | deepl.StyleProfile, string]>>[
+            ['sp-1', 'sp-1'],
+            [<deepl.StyleProfile>{ styleProfileId: 'sp-2' }, 'sp-2'],
+        ]) {
+            const upload = expectUpload();
+
+            await translator.uploadDocument(Buffer.from('x'), null, 'de', {
+                filename: 'example.txt',
+                styleProfile,
+            });
+
+            const body = upload.body();
+            expect(body).toContain(`name="style_profile_id"\r\n\r\n${id}\r\n`);
+            expect(body.split('name="style_profile_id"').length).toBe(2);
+        }
+    });
+
+    it('sends no style_profile_id part when styleProfile is unset', async () => {
+        const upload = expectUpload();
+
+        await makeTranslator().uploadDocument(Buffer.from('x'), null, 'de', {
+            filename: 'example.txt',
+        });
+
+        expect(upload.body()).not.toContain('name="style_profile_id"');
+    });
+
     it('sends the base name of a file path as the filename', async () => {
         const upload = expectUpload();
         const [exampleDocument] = createTextDocument();

tests/offline/translateText.test.ts

@@ -169,6 +169,39 @@ describe('Translator.translateText', () => {
         });
     });
 
+    it('sends the style profile ID of a string and of a StyleProfile', async () => {
+        expectTranslateBody({ ...baseBody, style_profile_id: 'sp-1' });
+        expectTranslateBody({ ...baseBody, style_profile_id: 'sp-2' });
+        const translator = makeTranslator();
+
+        await translator.translateText('abc', null, 'de', { styleProfile: 'sp-1' });
+        await translator.translateText('abc', null, 'de', {
+            styleProfile: <deepl.StyleProfile>{ styleProfileId: 'sp-2' },
+        });
+    });
+
+    it('sends no style_profile_id when styleProfile is unset', async () => {
+        let sent: Record<string, unknown> = {};
+        nock(serverUrl)
+            .post('/v2/translate', (body) => {
+                sent = body;
+                return true;
+            })
+            .reply(200, translation);
+
+        await makeTranslator().translateText('abc', null, 'de', { styleRule: 'style-1' });
+
+        expect(sent).toEqual({ ...baseBody, style_id: 'style-1' });
+    });
+
+    it('throws for a styleProfile object without an ID', async () => {
+        await expect(
+            makeTranslator().translateText('abc', null, 'de', {
+                styleProfile: <deepl.StyleProfile>{},
+            }),
+        ).rejects.toThrow(deepl.DeepLError);
+    });
+
     it('sends the translation memory ID and threshold', async () => {
         expectTranslateBody({
             ...baseBody,