feat: Add ability to text translate with a translation memory

Author: BriannaDelgado

README.md

@@ -177,6 +177,12 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
     `getMultilingualGlossary()`/`getGlossary()`.
 -   `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()`.
+-   `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()`.
+-   `translationMemoryThreshold`: a number from 0 to 100 that specifies the
+    minimum matching percentage for translation memory matches. We recommend
+    a minimum threshold of 75%.
 -   `context`: specifies additional context to influence translations, that is not
     translated itself. Characters in the `context` parameter are not counted toward billing.
     See the [API documentation][api-docs-context-param] for more information and
@@ -592,6 +598,59 @@ Use `deleteStyleRule()` to delete a style rule by ID.
 await deeplClient.deleteStyleRule('YOUR_STYLE_ID');
 ```
 
+### Translation Memories
+
+Translation memories store and reuse previously created translations, helping to
+maintain consistency and reduce translation costs by leveraging past work.
+
+#### Uploading and managing translation memories
+
+Currently translation memories must be uploaded and managed in the DeepL UI via
+https://www.deepl.com/translation-memory. Full CRUD functionality via the APIs will
+come shortly.
+
+#### Listing translation memories
+
+Use `listTranslationMemories()` to list available translation memories
+associated with your account.
+
+```javascript
+const translationMemories = await deeplClient.listTranslationMemories();
+for (const tm of translationMemories) {
+    console.log(`${tm.name} (${tm.translationMemoryId})`);
+}
+```
+
+#### Using a translation memory in translations
+
+Pass the `translationMemory` option to `translateText()` to apply a translation
+memory during translation. You can provide either the translation memory ID as a
+string, or a `TranslationMemoryInfo` object returned by
+`listTranslationMemories()`. Optionally, use `translationMemoryThreshold` to
+control the minimum similarity for matches.
+
+```typescript
+// Using a translation memory ID
+const result = await deeplClient.translateText(
+    'Hello, world!',
+    'en',
+    'de',
+    { translationMemory: 'YOUR_TM_ID' },
+);
+
+// Using a TranslationMemoryInfo object with a similarity threshold
+const translationMemories = await deeplClient.listTranslationMemories();
+const result = await deeplClient.translateText(
+    'Hello, world!',
+    'en',
+    'de',
+    {
+        translationMemory: translationMemories[0],
+        translationMemoryThreshold: 80,
+    },
+);
+```
+
 ### Checking account usage
 
 To check account usage, use the `getUsage()` function.

src/deeplClient.ts

@@ -17,6 +17,7 @@ import {
     StyleRuleInfoApiResponse,
     StyleId,
     CustomInstruction,
+    TranslationMemoryInfo,
 } from './types';
 import {
     parseMultilingualGlossaryDictionaryInfo,
@@ -27,6 +28,7 @@ import {
     parseStyleRuleInfoList,
     parseStyleRuleInfo,
     parseCustomInstruction,
+    parseTranslationMemoryInfoList,
 } from './parsing';
 import {
     appendCsvDictionaryEntries,
@@ -598,6 +600,38 @@ export class DeepLClient extends Translator {
         return parseStyleRuleInfoList(content);
     }
 
+    /**
+     * Retrieves a list of available translation memories. The maximum number of translation
+     * memories returned is controlled by pageSize (max 25).
+     *
+     * @param page: Page number for pagination, 0-indexed (optional).
+     * @param pageSize: Number of items per page (optional).
+     * @returns {Promise<TranslationMemoryInfo[]>} An array of objects containing details about each translation memory.
+     *
+     * @throws {DeepLError} If any error occurs while communicating with the DeepL API.
+     */
+    async listTranslationMemories(
+        page?: number,
+        pageSize?: number,
+    ): Promise<TranslationMemoryInfo[]> {
+        const queryParams = new URLSearchParams();
+        if (page !== undefined) {
+            queryParams.append('page', String(page));
+        }
+        if (pageSize !== undefined) {
+            queryParams.append('page_size', String(pageSize));
+        }
+
+        const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
+            'GET',
+            '/v3/translation_memories',
+            { data: queryParams },
+        );
+
+        await checkStatusCode(statusCode, content);
+        return parseTranslationMemoryInfoList(content);
+    }
+
     /**
      * Creates a new style rule.
      *

src/parsing.ts

@@ -29,6 +29,9 @@ import {
     ListStyleRuleApiResponse,
     ConfiguredRules,
     CustomInstruction,
+    TranslationMemoryInfo,
+    TranslationMemoryInfoApiResponse,
+    ListTranslationMemoryApiResponse,
 } from './types';
 import { standardizeLanguageCode } from './utils';
 
@@ -611,3 +614,32 @@ export function parseStyleRuleInfoList(json: string): StyleRuleInfo[] {
         throw new DeepLError(`Error parsing response JSON: ${error}`);
     }
 }
+
+/**
+ * Parses the given translation memory API response to a TranslationMemoryInfo object.
+ * @private
+ */
+export function parseTranslationMemoryInfo(
+    tm: TranslationMemoryInfoApiResponse,
+): TranslationMemoryInfo {
+    return {
+        translationMemoryId: tm.translation_memory_id,
+        name: tm.name,
+        sourceLanguage: tm.source_language,
+        targetLanguages: tm.target_languages,
+        segmentCount: tm.segment_count,
+    };
+}
+
+/**
+ * Parses the given JSON string to an array of TranslationMemoryInfo objects.
+ * @private
+ */
+export function parseTranslationMemoryInfoList(json: string): TranslationMemoryInfo[] {
+    try {
+        const obj = JSON.parse(json) as ListTranslationMemoryApiResponse;
+        return obj.translation_memories.map(parseTranslationMemoryInfo);
+    } catch (error) {
+        throw new DeepLError(`Error parsing response JSON: ${error}`);
+    }
+}

src/types.ts

@@ -88,6 +88,7 @@ export type TagHandlingVersion = 'v1' | 'v2';
 export type ModelType = 'quality_optimized' | 'latency_optimized' | 'prefer_quality_optimized';
 export type GlossaryId = string;
 export type StyleId = string;
+export type TranslationMemoryId = string;
 export type TagList = string | string[];
 
 /**
@@ -161,6 +162,14 @@ export interface TranslateTextOptions extends BaseRequestOptions {
      */
     styleRule?: StyleId | StyleRuleInfo;
 
+    /** Specifies the ID of a translation memory to use with translation, or
+     * a TranslationMemoryInfo object as returned by listTranslationMemories().
+     */
+    translationMemory?: TranslationMemoryId | TranslationMemoryInfo;
+
+    /** Specifies the minimum similarity threshold (0 to 100) for translation memory matches. */
+    translationMemoryThreshold?: number;
+
     /** Type of tags to parse before translation, options are 'html' and 'xml'. */
     tagHandling?: TagHandlingMode;
 
@@ -764,3 +773,34 @@ export interface StyleRuleInfoApiResponse {
 export interface ListStyleRuleApiResponse {
     style_rules: StyleRuleInfoApiResponse[];
 }
+
+/**
+ * Information about a translation memory.
+ */
+export interface TranslationMemoryInfo {
+    readonly translationMemoryId: TranslationMemoryId;
+    readonly name: string;
+    readonly sourceLanguage: string;
+    readonly targetLanguages: string[];
+    readonly segmentCount: number;
+}
+
+/**
+ * Type used during JSON parsing of API response for translation memory info.
+ * @private
+ */
+export interface TranslationMemoryInfoApiResponse {
+    translation_memory_id: string;
+    name: string;
+    source_language: string;
+    target_languages: string[];
+    segment_count: number;
+}
+
+/**
+ * Type used during JSON parsing of API response for listing translation memories.
+ * @private
+ */
+export interface ListTranslationMemoryApiResponse {
+    translation_memories: TranslationMemoryInfoApiResponse[];
+}

src/utils.ts

@@ -288,6 +288,27 @@ export function validateAndAppendTextOptions(
             data.append('style_id', options.styleRule.styleId);
         }
     }
+    if (options.translationMemory !== undefined) {
+        if (!isString(options.translationMemory)) {
+            if (options.translationMemory.translationMemoryId === undefined) {
+                throw new DeepLError(
+                    'translationMemory option should be a TranslationMemoryId (string) or a TranslationMemoryInfo object.',
+                );
+            }
+            data.append('translation_memory_id', options.translationMemory.translationMemoryId);
+        } else {
+            data.append('translation_memory_id', options.translationMemory);
+        }
+    }
+    if (options.translationMemoryThreshold !== undefined) {
+        if (options.translationMemory === undefined) {
+            throw new DeepLError('translationMemoryThreshold requires translationMemory');
+        }
+        if (options.translationMemoryThreshold < 0 || options.translationMemoryThreshold > 100) {
+            throw new DeepLError('translationMemoryThreshold must be a number between 0 and 100.');
+        }
+        data.append('translation_memory_threshold', options.translationMemoryThreshold.toString());
+    }
     if (options.customInstructions !== undefined) {
         for (const instruction of options.customInstructions) {
             data.append('custom_instructions', instruction);

tests/translationMemories.test.ts

@@ -0,0 +1,38 @@
+// Copyright 2025 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+import { makeDeeplClient, withMockServer } from './core';
+
+describe('Translation Memories Tests', () => {
+    const DEFAULT_TM_ID = 'a74d88fb-ed2a-4943-a664-a4512398b994';
+
+    withMockServer('test listTranslationMemories', async () => {
+        const deeplClient = makeDeeplClient();
+        const translationMemories = await deeplClient.listTranslationMemories(0, 10);
+
+        expect(Array.isArray(translationMemories)).toBe(true);
+        expect(translationMemories.length).toBeGreaterThan(0);
+        expect(translationMemories[0].translationMemoryId).toBeDefined();
+        expect(translationMemories[0].name).toBeDefined();
+        expect(translationMemories[0].sourceLanguage).toBeDefined();
+        expect(translationMemories[0].targetLanguages).toBeDefined();
+        expect(translationMemories[0].segmentCount).toBeDefined();
+    });
+
+    withMockServer('test translateText with translationMemory string ID', async () => {
+        const deeplClient = makeDeeplClient();
+        const exampleText = 'Hallo, Welt!';
+        await deeplClient.translateText(exampleText, 'de', 'en-US', {
+            translationMemory: DEFAULT_TM_ID,
+        });
+    });
+
+    withMockServer('test translateText with translationMemory and threshold', async () => {
+        const deeplClient = makeDeeplClient();
+        const exampleText = 'Hallo, Welt!';
+        await deeplClient.translateText(exampleText, 'de', 'en-US', {
+            translationMemory: DEFAULT_TM_ID,
+            translationMemoryThreshold: 80,
+        });
+    });
+});