feat: Add ability to text translate with a translation memory

Author: BriannaDelgado

README.md

@@ -178,6 +178,12 @@ arguments are:
   use, options are `'v1'` and `'v2'`.
 - `style_rule`: specifies a style rule to use with translation, either as a string
   containing the ID of the style rule, or a `StyleRuleInfo` object.
+- `translation_memory`: specifies a translation memory to use with translation,
+  either as a string containing the ID of the translation memory, or a
+  `TranslationMemoryInfo` object.
+- `translation_memory_threshold`: the minimum matching percentage for fuzzy
+  matches from the translation memory (0-100). We recommend a minimum threshold
+  of 75%.
 - `custom_instructions`: an array of instructions to customize the text 
   translation behavior. Up to 10 custom instructions can be specified, each with 
   a maximum of 300 characters.
@@ -756,6 +762,68 @@ Style rules can also be used with the command line interface for text translatio
 python3 -m deepl --auth-key=YOUR_AUTH_KEY text --to=DE --style-id=YOUR_STYLE_ID "Text to translate"
 ``` 
 
+### Translation Memories
+
+Translation memories allow you to store and reuse previously created translations.
+They can be used in text translation requests to improve consistency by matching
+against stored segments. Multiple translation memories can be stored with your
+account, each with a source language and one or more target languages.
+
+#### 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
+
+`list_translation_memories()` returns a list of `TranslationMemoryInfo` objects
+for your stored translation memories. The number of translation memories
+returned is controlled by `page_size` (max 25). The method accepts
+optional parameters: `page` (page number for pagination, 0-indexed)
+and `page_size` (number of items per page).
+
+```python
+# List translation memories
+translation_memories = deepl_client.list_translation_memories()
+for tm in translation_memories:
+    print(f"{tm.name} ({tm.translation_memory_id})")
+    print(f"  Source: {tm.source_language}, Targets: {tm.target_languages}")
+    print(f"  Segments: {tm.segment_count}")
+```
+
+#### Using a translation memory in translations
+
+Pass the `translation_memory` parameter to `translate_text()` to use a
+translation memory. You can pass either a string containing the translation
+memory ID, or a `TranslationMemoryInfo` object. Use
+`translation_memory_threshold` to control the minimum matching percentage for
+fuzzy matches (0-100, recommended minimum of 75%).
+
+```python
+# Translate with a translation memory ID
+result = deepl_client.translate_text(
+    "Hello, world!",
+    target_lang="DE",
+    translation_memory="YOUR_TM_ID",
+    translation_memory_threshold=80,
+)
+
+# Or use a TranslationMemoryInfo object
+translation_memories = deepl_client.list_translation_memories()
+result = deepl_client.translate_text(
+    "Hello, world!",
+    target_lang="DE",
+    translation_memory=translation_memories[0],
+)
+```
+
+Translation memories can also be used with the command line interface:
+
+```bash
+python3 -m deepl --auth-key=YOUR_AUTH_KEY text --to=DE --translation-memory-id=YOUR_TM_ID --translation-memory-threshold=75 "Text to translate"
+```
+
 ### Writing a Plugin
 
 If you use this library in an application, please identify the application with

deepl/__main__.py

@@ -385,6 +385,19 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
         type=str,
         help="ID of style rule to use for translation",
     )
+    parser_text.add_argument(
+        "--translation-memory-id",
+        dest="translation_memory",
+        type=str,
+        help="ID of translation memory to use for translation",
+    )
+    parser_text.add_argument(
+        "--translation-memory-threshold",
+        dest="translation_memory_threshold",
+        type=int,
+        help="minimum matching percentage (0-100) for translation memory "
+        "fuzzy matches, recommended minimum is 75",
+    )
     parser_text.add_argument(
         "--custom-instructions",
         dest="custom_instructions",

deepl/api_data.py

@@ -1005,3 +1005,70 @@ def configured_rules(self) -> Optional[ConfiguredRules]:
     def custom_instructions(self) -> List[CustomInstruction]:
         """Returns the list of custom instructions."""
         return self._custom_instructions or []
+
+
+class TranslationMemoryInfo:
+    """Information about a translation memory.
+
+    :param translation_memory_id: Unique ID assigned to the translation memory.
+    :param name: User-defined name assigned to the translation memory.
+    :param source_language: Source language code for the translation memory.
+    :param target_languages: List of target language codes available.
+    :param segment_count: Number of segments stored in the translation memory.
+    """
+
+    def __init__(
+        self,
+        translation_memory_id: str,
+        name: str,
+        source_language: str,
+        target_languages: List[str],
+        segment_count: int,
+    ):
+        self._translation_memory_id = translation_memory_id
+        self._name = name
+        self._source_language = source_language
+        self._target_languages = target_languages
+        self._segment_count = segment_count
+
+    def __str__(self) -> str:
+        return (
+            f'TranslationMemory "{self.name}" '
+            f"({self.translation_memory_id})"
+        )
+
+    @staticmethod
+    def from_json(json) -> "TranslationMemoryInfo":
+        """Create TranslationMemoryInfo from the given API JSON object."""
+        return TranslationMemoryInfo(
+            translation_memory_id=json["translation_memory_id"],
+            name=json["name"],
+            source_language=json["source_language"],
+            target_languages=json.get("target_languages", []),
+            segment_count=json.get("segment_count", 0),
+        )
+
+    @property
+    def translation_memory_id(self) -> str:
+        """Returns the unique ID of the translation memory."""
+        return self._translation_memory_id
+
+    @property
+    def name(self) -> str:
+        """Returns the name of the translation memory."""
+        return self._name
+
+    @property
+    def source_language(self) -> str:
+        """Returns the source language code."""
+        return self._source_language
+
+    @property
+    def target_languages(self) -> List[str]:
+        """Returns the list of target language codes."""
+        return self._target_languages
+
+    @property
+    def segment_count(self) -> int:
+        """Returns the number of segments stored."""
+        return self._segment_count

deepl/deepl_client.py

@@ -11,6 +11,7 @@
     Language,
     WriteResult,
     StyleRuleInfo,
+    TranslationMemoryInfo,
 )
 from deepl.translator import Translator
 from deepl import util
@@ -907,3 +908,39 @@ def delete_style_rule_custom_instruction(
             method="DELETE",
         )
         self._raise_for_status(status, content, json)
+
+    def list_translation_memories(
+        self,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+    ) -> List[TranslationMemoryInfo]:
+        """Retrieves a list of TranslationMemoryInfo for available
+        translation memories. The maximum number of translation memories
+        returned is controlled by page_size (max 25).
+
+        :param page: Page number for pagination, 0-indexed (optional).
+        :param page_size: Number of items per page (optional).
+        :return: List of TranslationMemoryInfo objects.
+        """
+        params = {}
+        if page is not None:
+            params["page"] = str(page)
+        if page_size is not None:
+            params["page_size"] = str(page_size)
+
+        endpoint = "v3/translation_memories"
+        if params:
+            query_string = urllib.parse.urlencode(params)
+            endpoint += f"?{query_string}"
+
+        status, content, json = self._api_call(endpoint, method="GET")
+        self._raise_for_status(status, content, json)
+
+        translation_memories = (
+            json.get("translation_memories", [])
+            if (json and isinstance(json, dict))
+            else []
+        )
+        return [
+            TranslationMemoryInfo.from_json(tm) for tm in translation_memories
+        ]

deepl/translator.py

@@ -14,6 +14,7 @@
     SplitSentences,
     StyleRuleInfo,
     TextResult,
+    TranslationMemoryInfo,
     Usage,
 )
 from . import http_client, util
@@ -264,6 +265,8 @@ def _check_language_and_formality(
             str, GlossaryInfo, MultilingualGlossaryInfo, None
         ] = None,
         style_rule: Union[str, StyleRuleInfo, None] = None,
+        translation_memory: Union[str, TranslationMemoryInfo, None] = None,
+        translation_memory_threshold: Optional[int] = None,
     ) -> dict:
         # target_lang and source_lang are case insensitive
         target_lang = str(target_lang).upper()
@@ -304,7 +307,7 @@ def _check_language_and_formality(
 
         self._check_valid_languages(source_lang, target_lang)
 
-        request_data = {"target_lang": target_lang}
+        request_data: dict = {"target_lang": target_lang}
         if source_lang is not None:
             request_data["source_lang"] = source_lang
         if formality is not None:
@@ -319,6 +322,25 @@ def _check_language_and_formality(
             request_data["style_id"] = style_rule.style_id
         elif style_rule is not None:
             request_data["style_id"] = style_rule
+        if isinstance(translation_memory, TranslationMemoryInfo):
+            request_data["translation_memory_id"] = (
+                translation_memory.translation_memory_id
+            )
+        elif translation_memory is not None:
+            request_data["translation_memory_id"] = translation_memory
+        if translation_memory_threshold is not None:
+            if translation_memory is None:
+                raise ValueError(
+                    "translation_memory_threshold requires"
+                    " translation_memory"
+                )
+            if not (0 <= translation_memory_threshold <= 100):
+                raise ValueError(
+                    "translation_memory_threshold must be between 0 and 100"
+                )
+            request_data["translation_memory_threshold"] = (
+                translation_memory_threshold
+            )
         return request_data
 
     def _create_glossary(
@@ -383,6 +405,8 @@ def translate_text(
         ignore_tags: Union[str, List[str], None] = None,
         model_type: Union[str, ModelType, None] = None,
         style_rule: Union[str, StyleRuleInfo, None] = None,
+        translation_memory: Union[str, TranslationMemoryInfo, None] = None,
+        translation_memory_threshold: Optional[int] = None,
         custom_instructions: Optional[List[str]] = None,
         extra_body_parameters: Optional[dict] = None,
     ) -> Union[TextResult, List[TextResult]]:
@@ -413,6 +437,11 @@ def translate_text(
             translation. Must match specified source_lang and target_lang.
         :param style_rule: (Optional) style rule or style rule ID to use for
             translation.
+        :param translation_memory: (Optional) translation memory or translation
+            memory ID to use for translation.
+        :param translation_memory_threshold: (Optional) minimum matching
+            percentage for fuzzy matches from the translation memory (0-100).
+            Recommended minimum is 75%.
         :param tag_handling: (Optional) Type of tags to parse before
             translation, only "xml" and "html" are currently available.
         :param tag_handling_version: (Optional) Version of tag handling
@@ -456,7 +485,13 @@ def translate_text(
             )
 
         request_data = self._check_language_and_formality(
-            source_lang, target_lang, formality, glossary, style_rule
+            source_lang,
+            target_lang,
+            formality,
+            glossary,
+            style_rule,
+            translation_memory,
+            translation_memory_threshold,
         )
         request_data["text"] = text
 
@@ -478,11 +513,6 @@ def translate_text(
             request_data["outline_detection"] = bool(outline_detection)
         if model_type is not None:
             request_data["model_type"] = str(model_type)
-        if style_rule is not None:
-            if isinstance(style_rule, StyleRuleInfo):
-                request_data["style_id"] = style_rule.style_id
-            else:
-                request_data["style_id"] = style_rule
 
         def join_tags(tag_argument: Union[str, Iterable[str]]) -> List[str]:
             if isinstance(tag_argument, str):

tests/test_translation_memories.py

@@ -0,0 +1,39 @@
+# Copyright 2022 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.
+
+from .conftest import example_text, needs_mock_server
+
+DEFAULT_TM_ID = "a74d88fb-ed2a-4943-a664-a4512398b994"
+
+
+@needs_mock_server
+def test_list_translation_memories(deepl_client):
+    translation_memories = deepl_client.list_translation_memories()
+
+    assert isinstance(translation_memories, list)
+    assert len(translation_memories) > 0
+    assert translation_memories[0].translation_memory_id is not None
+    assert translation_memories[0].name is not None
+    assert translation_memories[0].source_language is not None
+    assert isinstance(translation_memories[0].target_languages, list)
+    assert isinstance(translation_memories[0].segment_count, int)
+
+
+@needs_mock_server
+def test_translate_text_with_translation_memory(deepl_client):
+    _ = deepl_client.translate_text(
+        example_text["DE"],
+        target_lang="EN-US",
+        translation_memory=DEFAULT_TM_ID,
+    )
+
+
+@needs_mock_server
+def test_translate_text_with_translation_memory_and_threshold(deepl_client):
+    _ = deepl_client.translate_text(
+        example_text["DE"],
+        target_lang="EN-US",
+        translation_memory=DEFAULT_TM_ID,
+        translation_memory_threshold=80,
+    )