feat: Add ability to text translate with a translation memory

Author: BriannaDelgado

README.md

@@ -167,6 +167,13 @@ a `TextTranslationOptions`, with the following setters:
 - `setStyleRule()`: specifies a style rule to use with translation, as a string
   containing the ID of the style rule, or a `StyleRuleInfo` object.
     - `setStyleId()` is also available, accepting a string containing the style rule ID.
+- `setTranslationMemory()`: specifies a translation memory to use with translation,
+  as a `TranslationMemoryInfo` object. Sets the translation memory ID.
+    - `setTranslationMemoryId()` is also available, accepting a string containing
+      the translation memory ID.
+    - `setTranslationMemoryThreshold()` is also available, accepting an integer
+      from 0 to 100 to control the minimum matching percentage for translation
+      memory matches. We recommend a minimum threshold of 75%.
 - `setContext()`: 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
@@ -797,6 +804,64 @@ class Example {  // Continuing class Example from above
 }
 ```
 
+### Translation Memories
+
+Translation memories store and reuse previously created translations, helping to
+ensure consistency and reduce effort when translating similar or repeated content.
+
+#### 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 retrieve translation memories associated
+with your account:
+
+```java
+class Example {  // Continuing class Example from above
+    public void listTranslationMemoriesExample() throws Exception {
+        List<TranslationMemoryInfo> translationMemories =
+                client.listTranslationMemories();
+        for (TranslationMemoryInfo tm : translationMemories) {
+            System.out.println(String.format("%s (%s)",
+                tm.getName(), tm.getTranslationMemoryId()));
+        }
+    }
+}
+```
+
+#### Using a translation memory in translations
+
+You can use a translation memory for text translation by setting the translation
+memory options in `TextTranslationOptions`:
+
+```java
+class Example {  // Continuing class Example from above
+    public void usingTranslationMemoryExample() throws Exception {
+        // Using the translation memory ID directly
+        TextTranslationOptions options = new TextTranslationOptions()
+                .setTranslationMemoryId("tm-123abc")
+                .setTranslationMemoryThreshold(80);
+        TextResult result = client.translateText(
+            "Hello, world!", null, "de", options);
+        System.out.println(result.getText());
+
+        // Or using a TranslationMemoryInfo object from listTranslationMemories()
+        List<TranslationMemoryInfo> memories = client.listTranslationMemories();
+        if (!memories.isEmpty()) {
+            TextTranslationOptions optionsFromInfo = new TextTranslationOptions()
+                    .setTranslationMemory(memories.get(0));
+            TextResult resultFromInfo = client.translateText(
+                "Hello, world!", null, "de", optionsFromInfo);
+            System.out.println(resultFromInfo.getText());
+        }
+    }
+}
+```
+
 ### Checking account usage
 
 To check account usage, use the `getUsage()` function.

deepl-java/src/main/java/com/deepl/api/DeepLClient.java

@@ -803,6 +803,64 @@ public List<StyleRuleInfo> getAllStyleRules() throws DeepLException, Interrupted
     return getAllStyleRules(null, null, null);
   }
 
+  /**
+   * Retrieves a list of translation memories available for the account associated with the DeepL
+   * API auth key. The maximum number of translation memories returned is controlled by pageSize
+   * (max 25).
+   *
+   * @param page Page number to retrieve (starting from 0), or <code>null</code>.
+   * @param pageSize Number of items per page, or <code>null</code>.
+   * @return List of {@link TranslationMemoryInfo} objects.
+   * @throws InterruptedException If the thread is interrupted during execution of this function.
+   * @throws DeepLException If any error occurs while communicating with the DeepL API.
+   */
+  public List<TranslationMemoryInfo> listTranslationMemories(
+      @Nullable Integer page, @Nullable Integer pageSize)
+      throws DeepLException, InterruptedException {
+    ArrayList<KeyValuePair<String, String>> queryParams = new ArrayList<>();
+    if (page != null) {
+      queryParams.add(new KeyValuePair<>("page", page.toString()));
+    }
+    if (pageSize != null) {
+      queryParams.add(new KeyValuePair<>("page_size", pageSize.toString()));
+    }
+
+    String queryString = "";
+    if (!queryParams.isEmpty()) {
+      StringBuilder sb = new StringBuilder("?");
+      for (int i = 0; i < queryParams.size(); i++) {
+        if (i > 0) {
+          sb.append("&");
+        }
+        KeyValuePair<String, String> param = queryParams.get(i);
+        try {
+          sb.append(URLEncoder.encode(param.getKey(), StandardCharsets.UTF_8.name()))
+              .append("=")
+              .append(URLEncoder.encode(param.getValue(), StandardCharsets.UTF_8.name()));
+        } catch (java.io.UnsupportedEncodingException e) {
+          throw new RuntimeException("UTF-8 encoding not supported", e);
+        }
+      }
+      queryString = sb.toString();
+    }
+
+    String relativeUrl = "/v3/translation_memories" + queryString;
+    HttpResponse response = httpClientWrapper.sendGetRequestWithBackoff(relativeUrl);
+    checkResponse(response, false, false);
+    return jsonParser.parseTranslationMemoryInfoList(response.getBody());
+  }
+
+  /**
+   * Functions the same as {@link DeepLClient#listTranslationMemories(Integer, Integer, Boolean)}
+   * but with default parameters (all null).
+   *
+   * @see DeepLClient#listTranslationMemories(Integer, Integer)
+   */
+  public List<TranslationMemoryInfo> listTranslationMemories()
+      throws DeepLException, InterruptedException {
+    return listTranslationMemories(null, null);
+  }
+
   /**
    * Creates a new style rule with the specified details and returns a {@link StyleRuleInfo} object
    * with details about the newly created style rule.

deepl-java/src/main/java/com/deepl/api/TextTranslationOptions.java

@@ -17,6 +17,8 @@ public class TextTranslationOptions extends BaseRequestOptions {
   private Formality formality;
   private String glossaryId;
   private String styleId;
+  private String translationMemoryId;
+  private Integer translationMemoryThreshold;
   private SentenceSplittingMode sentenceSplittingMode;
   private boolean preserveFormatting = false;
   private String context;
@@ -85,6 +87,41 @@ public TextTranslationOptions setStyleRule(StyleRuleInfo styleRule) {
     return setStyleId(styleRule.getStyleId());
   }
 
+  /**
+   * Sets the ID of a translation memory to use with the translation. By default, this value is
+   * <code>null</code> and no translation memory is used.
+   */
+  public TextTranslationOptions setTranslationMemoryId(String translationMemoryId) {
+    this.translationMemoryId = translationMemoryId;
+    return this;
+  }
+
+  /**
+   * Sets the translation memory to use with the translation. By default, this value is <code>null
+   * </code> and no translation memory is used.
+   */
+  public TextTranslationOptions setTranslationMemory(TranslationMemoryInfo translationMemory) {
+    if (translationMemory == null) {
+      throw new IllegalArgumentException("translationMemory must not be null");
+    }
+    return setTranslationMemoryId(translationMemory.getTranslationMemoryId());
+  }
+
+  /**
+   * Sets the threshold for translation memory matches. By default, this value is <code>null</code>
+   * and the API default threshold is used. Note: a translation memory ID must also be set via
+   * {@link #setTranslationMemoryId} or {@link #setTranslationMemory}, otherwise an error will be
+   * thrown at translation time.
+   */
+  public TextTranslationOptions setTranslationMemoryThreshold(Integer translationMemoryThreshold) {
+    if (translationMemoryThreshold != null
+        && (translationMemoryThreshold < 0 || translationMemoryThreshold > 100)) {
+      throw new IllegalArgumentException("translationMemoryThreshold must be between 0 and 100");
+    }
+    this.translationMemoryThreshold = translationMemoryThreshold;
+    return this;
+  }
+
   /**
    * 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
@@ -210,6 +247,16 @@ public String getStyleId() {
     return styleId;
   }
 
+  /** Gets the current translation memory ID. */
+  public String getTranslationMemoryId() {
+    return translationMemoryId;
+  }
+
+  /** Gets the current translation memory threshold. */
+  public Integer getTranslationMemoryThreshold() {
+    return translationMemoryThreshold;
+  }
+
   /** Gets the current sentence splitting mode. */
   public SentenceSplittingMode getSentenceSplittingMode() {
     return sentenceSplittingMode;

deepl-java/src/main/java/com/deepl/api/TranslationMemoryInfo.java

@@ -0,0 +1,92 @@
+// 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.
+package com.deepl.api;
+
+import com.google.gson.annotations.*;
+import java.util.*;
+
+/** Information about a translation memory. */
+public class TranslationMemoryInfo {
+  @SerializedName(value = "translation_memory_id")
+  private final String translationMemoryId;
+
+  @SerializedName(value = "name")
+  private final String name;
+
+  @SerializedName(value = "source_language")
+  private final String sourceLanguage;
+
+  @SerializedName(value = "target_languages")
+  private final List<String> targetLanguages;
+
+  @SerializedName(value = "segment_count")
+  private final int segmentCount;
+
+  /**
+   * Initializes a new {@link TranslationMemoryInfo} containing information about a translation
+   * memory.
+   *
+   * @param translationMemoryId Unique ID assigned to the translation memory.
+   * @param name User-defined name assigned to the translation memory.
+   * @param sourceLanguage Source language code for the translation memory.
+   * @param targetLanguages List of target language codes for the translation memory.
+   * @param segmentCount Number of segments in the translation memory.
+   */
+  public TranslationMemoryInfo(
+      String translationMemoryId,
+      String name,
+      String sourceLanguage,
+      List<String> targetLanguages,
+      int segmentCount) {
+    this.translationMemoryId = translationMemoryId;
+    this.name = name;
+    this.sourceLanguage = sourceLanguage;
+    this.targetLanguages = targetLanguages;
+    this.segmentCount = segmentCount;
+  }
+
+  /** @return Unique ID assigned to the translation memory. */
+  public String getTranslationMemoryId() {
+    return translationMemoryId;
+  }
+
+  /** @return User-defined name assigned to the translation memory. */
+  public String getName() {
+    return name;
+  }
+
+  /** @return Source language code for the translation memory. */
+  public String getSourceLanguage() {
+    return sourceLanguage;
+  }
+
+  /** @return List of target language codes for the translation memory. */
+  public List<String> getTargetLanguages() {
+    return targetLanguages;
+  }
+
+  /** @return Number of segments in the translation memory. */
+  public int getSegmentCount() {
+    return segmentCount;
+  }
+
+  @Override
+  public String toString() {
+    return "TranslationMemoryInfo{"
+        + "translationMemoryId='"
+        + translationMemoryId
+        + '\''
+        + ", name='"
+        + name
+        + '\''
+        + ", sourceLanguage='"
+        + sourceLanguage
+        + '\''
+        + ", targetLanguages="
+        + targetLanguages
+        + ", segmentCount="
+        + segmentCount
+        + '}';
+  }
+}

deepl-java/src/main/java/com/deepl/api/Translator.java

@@ -852,6 +852,19 @@ private static ArrayList<KeyValuePair<String, String>> createHttpParams(
       if (options.getStyleId() != null) {
         params.add(new KeyValuePair<>("style_id", options.getStyleId()));
       }
+      if (options.getTranslationMemoryId() != null) {
+        params.add(new KeyValuePair<>("translation_memory_id", options.getTranslationMemoryId()));
+      }
+      if (options.getTranslationMemoryThreshold() != null) {
+        if (options.getTranslationMemoryId() == null) {
+          throw new IllegalArgumentException(
+              "translationMemoryThreshold requires translationMemoryId");
+        }
+        params.add(
+            new KeyValuePair<>(
+                "translation_memory_threshold",
+                options.getTranslationMemoryThreshold().toString()));
+      }
       if (options.getCustomInstructions() != null) {
         for (String instruction : options.getCustomInstructions()) {
           params.add(new KeyValuePair<>("custom_instructions", instruction));

deepl-java/src/main/java/com/deepl/api/parsing/Parser.java

@@ -99,6 +99,15 @@ public StyleRuleInfo parseStyleRuleInfo(String json) {
     return gson.fromJson(json, StyleRuleInfo.class);
   }
 
+  public List<TranslationMemoryInfo> parseTranslationMemoryInfoList(String json) {
+    TranslationMemoryListResponse result = gson.fromJson(json, TranslationMemoryListResponse.class);
+    return result.getTranslationMemories();
+  }
+
+  public TranslationMemoryInfo parseTranslationMemoryInfo(String json) {
+    return gson.fromJson(json, TranslationMemoryInfo.class);
+  }
+
   public CustomInstruction parseCustomInstruction(String json) {
     return gson.fromJson(json, CustomInstruction.class);
   }

deepl-java/src/main/java/com/deepl/api/parsing/TranslationMemoryListResponse.java

@@ -0,0 +1,20 @@
+// 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.
+package com.deepl.api.parsing;
+
+import com.deepl.api.TranslationMemoryInfo;
+import java.util.List;
+
+/**
+ * Class representing v3 translation_memories list response by the DeepL API.
+ *
+ * <p>This class is internal; you should not use this class directly.
+ */
+class TranslationMemoryListResponse {
+  private List<TranslationMemoryInfo> translation_memories;
+
+  public List<TranslationMemoryInfo> getTranslationMemories() {
+    return translation_memories;
+  }
+}