feat: support multiple glossaries (glossary_ids) and document style/translation-memory options

Author: BriannaDelgado

CHANGELOG.md

@@ -5,6 +5,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Added support for using multiple glossaries via the `glossary_ids` parameter
+  (up to 5 glossaries) in `translate_text()`, `translate_document()`,
+  `translate_document_upload()`, and `translate_document_from_filepath()`.
+- Added support for style rules in document translation via the `style_rule`
+  parameter in `translate_document()`, `translate_document_upload()`, and
+  `translate_document_from_filepath()`.
+- Added support for translation memories in document translation via the
+  `translation_memory` and `translation_memory_threshold` parameters in
+  `translate_document()`, `translate_document_upload()`, and
+  `translate_document_from_filepath()`.
+- Added `--glossary-ids` CLI argument for the `text` and `document` commands,
+  allowing up to 5 glossaries to be used per translation.
+- Added `--style-id`, `--translation-memory-id`, and
+  `--translation-memory-threshold` CLI arguments to the `document` command.
 
 ## [1.30.0] - 2026-04-09
 ### Added

README.md

@@ -160,6 +160,13 @@ arguments are:
 - `glossary`: specifies a glossary to use with translation, either as a string
   containing the glossary ID, or a `GlossaryInfo` as returned by
   `get_glossary()`.
+- `glossary_ids`: specifies a list of up to 5 glossaries to use with
+  translation, applied in order. Each entry may be a string containing the
+  glossary ID or a `GlossaryInfo` object. Requires `source_lang` to be set and
+  cannot be combined with the `glossary` parameter. On the command line, use the
+  repeatable `--glossary-ids` argument (available on both the `text` and
+  `document` commands), for example:
+  `--from=EN --to=DE --glossary-ids=ID1 --glossary-ids=ID2`.
 - `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
@@ -333,6 +340,10 @@ arguments, the available `translate_document()` and
 
 - `formality`: same as in [Text translation options](#text-translation-options).
 - `glossary`: same as in [Text translation options](#text-translation-options).
+- `glossary_ids`: same as in [Text translation options](#text-translation-options).
+- `style_rule`: same as in [Text translation options](#text-translation-options).
+- `translation_memory`: same as in [Text translation options](#text-translation-options).
+- `translation_memory_threshold`: same as in [Text translation options](#text-translation-options).
 - `output_format`: (`translate_document()` only)
   file extension of desired format of translated file, for example: `'pdf'`. If
   unspecified, by default the translated file will be in the same format as the
@@ -756,10 +767,17 @@ deepl_client.delete_style_rule("YOUR_STYLE_ID")
 
 #### Using a style rule in translations
 
-Style rules can also be used with the command line interface for text translation:
+Style rules can also be used with the command line interface for text
+translation:
 
 ```bash
 python3 -m deepl --auth-key=YOUR_AUTH_KEY text --to=DE --style-id=YOUR_STYLE_ID "Text to translate"
+```
+
+The `document` command also accepts `--style-id` for document translation:
+
+```bash
+python3 -m deepl --auth-key=YOUR_AUTH_KEY document --to=DE --style-id=YOUR_STYLE_ID /path/to/document.docx /path/to/output_dir
 ``` 
 
 ### Translation Memories
@@ -824,6 +842,13 @@ Translation memories can also be used with the command line interface:
 python3 -m deepl --auth-key=YOUR_AUTH_KEY text --to=DE --translation-memory-id=YOUR_TM_ID --translation-memory-threshold=75 "Text to translate"
 ```
 
+The `document` command also accepts `--translation-memory-id` and
+`--translation-memory-threshold` for document translation:
+
+```bash
+python3 -m deepl --auth-key=YOUR_AUTH_KEY document --to=DE --translation-memory-id=YOUR_TM_ID --translation-memory-threshold=75 /path/to/document.docx /path/to/output_dir
+```
+
 ### Writing a Plugin
 
 If you use this library in an application, please identify the application with

deepl/__main__.py

@@ -323,6 +323,16 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
             type=str,
             help="ID of glossary to use for translation",
         )
+        subparser.add_argument(
+            "--glossary-ids",
+            dest="glossary_ids",
+            action="append",
+            type=str,
+            metavar="id",
+            help="ID of a glossary to use for translation; may be repeated to "
+            "use up to 5 glossaries, applied in order. Requires --from and "
+            "cannot be combined with --glossary-id",
+        )
         subparser.add_argument(
             "--extra-body-parameters",
             dest="extra_body_parameters",
@@ -503,6 +513,25 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
         description="translate document(s)",
     )
     add_common_arguments(parser_document)
+    parser_document.add_argument(
+        "--style-id",
+        dest="style_rule",
+        type=str,
+        help="ID of style rule to use for translation",
+    )
+    parser_document.add_argument(
+        "--translation-memory-id",
+        dest="translation_memory",
+        type=str,
+        help="ID of translation memory to use for translation",
+    )
+    parser_document.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_document.add_argument(
         "file", nargs="+", help="file(s) to be translated."
     )

deepl/translator.py

@@ -267,6 +267,9 @@ def _check_language_and_formality(
         style_rule: Union[str, StyleRuleInfo, None] = None,
         translation_memory: Union[str, TranslationMemoryInfo, None] = None,
         translation_memory_threshold: Optional[int] = None,
+        glossary_ids: Optional[
+            List[Union[str, GlossaryInfo, MultilingualGlossaryInfo]]
+        ] = None,
     ) -> dict:
         # target_lang and source_lang are case insensitive
         target_lang = str(target_lang).upper()
@@ -276,6 +279,21 @@ def _check_language_and_formality(
         if glossary is not None and source_lang is None:
             raise ValueError("source_lang is required if using a glossary")
 
+        if glossary_ids is not None:
+            if glossary is not None:
+                raise ValueError(
+                    "glossary_ids cannot be used together with the glossary "
+                    "parameter"
+                )
+            if source_lang is None:
+                raise ValueError(
+                    "source_lang is required if using glossary_ids"
+                )
+            if len(glossary_ids) > 5:
+                raise ValueError(
+                    "glossary_ids must not contain more than 5 glossary IDs"
+                )
+
         if isinstance(glossary, GlossaryInfo):
             if (
                 Language.remove_regional_variant(target_lang)
@@ -318,6 +336,22 @@ def _check_language_and_formality(
             request_data["glossary_id"] = glossary.glossary_id
         elif glossary is not None:
             request_data["glossary_id"] = glossary
+        if glossary_ids is not None:
+            resolved_ids = [
+                (
+                    entry.glossary_id
+                    if isinstance(
+                        entry, (GlossaryInfo, MultilingualGlossaryInfo)
+                    )
+                    else entry
+                )
+                for entry in glossary_ids
+            ]
+            # The API expects glossary_ids as an array. For text translation
+            # this is JSON-encoded as an array; for document translation
+            # (form/multipart) translate_document_upload joins it into a
+            # single comma-separated glossary_ids field.
+            request_data["glossary_ids"] = resolved_ids
         if isinstance(style_rule, StyleRuleInfo):
             request_data["style_id"] = style_rule.style_id
         elif style_rule is not None:
@@ -397,6 +431,9 @@ def translate_text(
         glossary: Union[
             str, GlossaryInfo, MultilingualGlossaryInfo, None
         ] = None,
+        glossary_ids: Optional[
+            List[Union[str, GlossaryInfo, MultilingualGlossaryInfo]]
+        ] = None,
         tag_handling: Optional[str] = None,
         tag_handling_version: Optional[str] = None,
         outline_detection: Optional[bool] = None,
@@ -435,6 +472,9 @@ def translate_text(
             "default".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
+        :param glossary_ids: (Optional) list of up to 5 glossaries or glossary
+            IDs to use for translation, applied in order. Requires source_lang
+            to be set and cannot be combined with the glossary parameter.
         :param style_rule: (Optional) style rule or style rule ID to use for
             translation.
         :param translation_memory: (Optional) translation memory or translation
@@ -492,6 +532,7 @@ def translate_text(
             style_rule,
             translation_memory,
             translation_memory_threshold,
+            glossary_ids,
         )
         request_data["text"] = text
 
@@ -627,6 +668,12 @@ def translate_document_from_filepath(
         glossary: Union[
             str, GlossaryInfo, MultilingualGlossaryInfo, None
         ] = None,
+        glossary_ids: Optional[
+            List[Union[str, GlossaryInfo, MultilingualGlossaryInfo]]
+        ] = None,
+        style_rule: Union[str, StyleRuleInfo, None] = None,
+        translation_memory: Union[str, TranslationMemoryInfo, None] = None,
+        translation_memory_threshold: Optional[int] = None,
         timeout_s: Optional[int] = None,
         extra_body_parameters: Optional[dict] = None,
     ) -> DocumentStatus:
@@ -644,6 +691,16 @@ def translate_document_from_filepath(
             Formality enum, "less", "more", "prefer_less", or "prefer_more".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
+        :param glossary_ids: (Optional) list of up to 5 glossaries or glossary
+            IDs to use for translation, applied in order. Requires source_lang
+            to be set and cannot be combined with the glossary parameter.
+        :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 timeout_s: (beta) (Optional) Maximum time to wait before
             the call raises an error. Note that this is not accurate to the
             second, but only polls every 5 seconds.
@@ -674,6 +731,12 @@ def translate_document_from_filepath(
                         source_lang=source_lang,
                         formality=formality,
                         glossary=glossary,
+                        glossary_ids=glossary_ids,
+                        style_rule=style_rule,
+                        translation_memory=translation_memory,
+                        translation_memory_threshold=(
+                            translation_memory_threshold
+                        ),
                         output_format=output_format,
                         timeout_s=timeout_s,
                         extra_body_parameters=extra_body_parameters,
@@ -694,6 +757,12 @@ def translate_document(
         glossary: Union[
             str, GlossaryInfo, MultilingualGlossaryInfo, None
         ] = None,
+        glossary_ids: Optional[
+            List[Union[str, GlossaryInfo, MultilingualGlossaryInfo]]
+        ] = None,
+        style_rule: Union[str, StyleRuleInfo, None] = None,
+        translation_memory: Union[str, TranslationMemoryInfo, None] = None,
+        translation_memory_threshold: Optional[int] = None,
         filename: Optional[str] = None,
         output_format: Optional[str] = None,
         timeout_s: Optional[int] = None,
@@ -715,6 +784,16 @@ def translate_document(
             Formality enum, "less", "more", "prefer_less", or "prefer_more".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
+        :param glossary_ids: (Optional) list of up to 5 glossaries or glossary
+            IDs to use for translation, applied in order. Requires source_lang
+            to be set and cannot be combined with the glossary parameter.
+        :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 filename: (Optional) Filename including extension, only required
             if uploading string or bytes containing file content.
         :param output_format: (Optional) Desired output file extension, if
@@ -740,6 +819,10 @@ def translate_document(
             source_lang=source_lang,
             formality=formality,
             glossary=glossary,
+            glossary_ids=glossary_ids,
+            style_rule=style_rule,
+            translation_memory=translation_memory,
+            translation_memory_threshold=translation_memory_threshold,
             filename=filename,
             output_format=output_format,
             extra_body_parameters=extra_body_parameters,
@@ -770,6 +853,12 @@ def translate_document_upload(
         glossary: Union[
             str, GlossaryInfo, MultilingualGlossaryInfo, None
         ] = None,
+        glossary_ids: Optional[
+            List[Union[str, GlossaryInfo, MultilingualGlossaryInfo]]
+        ] = None,
+        style_rule: Union[str, StyleRuleInfo, None] = None,
+        translation_memory: Union[str, TranslationMemoryInfo, None] = None,
+        translation_memory_threshold: Optional[int] = None,
         filename: Optional[str] = None,
         output_format: Optional[str] = None,
         extra_body_parameters: Optional[dict] = None,
@@ -788,6 +877,16 @@ def translate_document_upload(
             Formality enum, "less", "more", "prefer_less", or "prefer_more".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
+        :param glossary_ids: (Optional) list of up to 5 glossaries or glossary
+            IDs to use for translation, applied in order. Requires source_lang
+            to be set and cannot be combined with the glossary parameter.
+        :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 filename: (Optional) Filename including extension, only required
             if uploading string or bytes containing file content.
         :param output_format: (Optional) Desired output file extension, if
@@ -801,11 +900,26 @@ def translate_document_upload(
         """
 
         request_data = self._check_language_and_formality(
-            source_lang, target_lang, formality, glossary
+            source_lang,
+            target_lang,
+            formality,
+            glossary,
+            style_rule,
+            translation_memory,
+            translation_memory_threshold,
+            glossary_ids=glossary_ids,
         )
         if output_format:
             request_data["output_format"] = output_format
 
+        # The document endpoint uses multipart/form-data. Send glossary_ids as
+        # a single comma-separated field (the form form of the array), matching
+        # the other SDKs, instead of repeated multipart fields.
+        if isinstance(request_data.get("glossary_ids"), list):
+            request_data["glossary_ids"] = ",".join(
+                request_data["glossary_ids"]
+            )
+
         files: Dict[str, Any] = {}
         if isinstance(input_document, (str, bytes)):
             if filename is None: