deepl-rb 3.7.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac9df781efec35e22812fb7d998386c19dd2f51afeb020d1850c4b2091e5ba20
-  data.tar.gz: 70db2ae1bd08aa8e1dffb01198225ad29fc5c2514cf4f1a38da948bbe97c51f3
+  metadata.gz: 35f6c08b68a4b9aa8907b543ebbfbab38e9f9f35f7e2dc60decaa4bac57340f5
+  data.tar.gz: 975d1d68cd43fec41b93252b609bc67a619d08d4fd2e6d6bc9b822ca01fd78ac
 SHA512:
-  metadata.gz: 5c55b0eb6a6ef528eb14f78acfb89591fa99de7c7d8a82fb322e5b189c6663ff5f5f915d46ac4e93fcebc5a1d1f71bcef3d94fb1cac36d5e5fcabec9eb656cb5
-  data.tar.gz: a606b2405448a3598faf0d38e51830437d14019ab6b2cec4a794f93bc47f8329612fc524b1f2d5c71e48063ef4682a12831cada04d8b5c2a9f8ffd1f2012c3e6
+  metadata.gz: 749cd28143798f5e08ba848bc4eaa476254ef24656e690fcb3e5ca84314eb54f68ffc7f3675ae74a0cc24c01d194d9dfebcd2d819e0982fad44aba5869e37344
+  data.tar.gz: 4a3b7ca19832725c49b0708f544f9842de7733cc8777b41f66835e4dbead815994ca6dab8b8b3052d172417240dcf5fff5934fc3959ef226001e8ad4e0769735

data/.gitlab-ci.yml

@@ -4,7 +4,7 @@ include:
   - project: '${CI_PROJECT_NAMESPACE}/ci-libs-for-client-libraries'
     file:
       - '/${CI_PROJECT_NAME}/.gitlab-ci.yml'
-  - project: 'deepl/ops/ci-cd-infrastructure/gitlab-ci-lib'
+  - project: 'deepl-org/deepl/devex/gitlab-ci-lib'
     file:
       - '/templates/.buildkit.yml'
       - '/templates/.secret-detection.yml'
@@ -118,6 +118,9 @@ semgrep-sast:
 .test_base:
     stage: test
     extends: .test
+    variables:
+        VALIDATE_REQUESTS_FOR_DEEPL_MOCK: '1'
+        VALIDATE_RESPONSES_FOR_DEEPL_MOCK: '1'
     parallel:
         matrix:
           - DOCKER_IMAGE: 'ruby:2.7'
@@ -164,7 +167,6 @@ test_manual:
   rules:
     - if: $CI_PIPELINE_SOURCE != "schedule"
 
-
 # stage: publish ----------------------
 
 gitlab release:

data/CHANGELOG.md

@@ -6,6 +6,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.9.0] - 2026-08-11
+### Added
+- Added support for using multiple glossaries in text and document translation
+  via the `glossary_ids` option (up to 5 glossary IDs) in `translate` and
+  document upload.
+- Added support for using a style rule in document translation via the
+  `style_id` option (the `style_rule` option) in document upload.
+- Added support for using a translation memory in document translation via the
+  `translation_memory_id` option (the `translation_memory` and
+  `translation_memory_threshold` options) in document upload.
+- Added support for translation memory management via `DeepL.translation_memories`:
+  `find()`, `segments()`, `destroy()`, `create_import()`, `upload_file()`,
+  `create_export()`, `find_job()`, `wait_until_job_done()`, `download_export()`,
+  and the convenience methods `import_from_filepath()` and `export_to_filepath()`.
+  Every method taking a translation memory accepts a string ID or a
+  `TranslationMemory` object. `wait_until_job_done()`, `import_from_filepath()`
+  and `export_to_filepath()` accept an optional `timeout_s` to stop waiting for
+  a job that does not finish. Please refer to the README for usage instructions.
+- Added the `creation_time` and `updated_time` attributes to `TranslationMemory`.
+
+### Changed
+- Reworked the test suite to run against the `deepl-mock` server with OpenAPI
+  request and response validation enabled in CI, replacing recorded VCR
+  cassettes. Added live integration and error-path specs across all endpoints,
+  with resource-level unit specs for response field mapping.
+
+### Removed
+- Dropped VCR cassette playback and the `vcr` and `webmock` development
+  dependencies.
+
+## [3.8.0] - 2026-05-27
+### Added
+- Added support for passing additional HTTP headers to `translate()` and
+  `rephrase()`. This can be used to send the `X-DeepL-Reporting-Tag` header
+  for usage reporting.
+
 ## [3.7.0] - 2026-05-14
 ### Added
 - Added support for listing translation memories via `DeepL.translation_memories.list`.
@@ -119,7 +155,9 @@ The change in major version is only due to the change in maintainership, there i
 ### Fixed
 - Make RequestEntityTooLarge error message more clear
 
-[Unreleased]: https://github.com/DeepLcom/deepl-rb/compare/v3.7.0...HEAD
+[Unreleased]: https://github.com/DeepLcom/deepl-rb/compare/v3.9.0...HEAD
+[3.9.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.8.0...v3.9.0
+[3.8.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.7.0...v3.8.0
 [3.7.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.6.1...v3.7.0
 [3.6.1]: https://github.com/DeepLcom/deepl-rb/compare/v3.6.0...v3.6.1
 [3.6.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.5.1...v3.6.0

data/Gemfile

@@ -19,6 +19,4 @@ group :test do
   gem 'rubocop-rspec'
   gem 'simplecov'
   gem 'simplecov-cobertura'
-  gem 'vcr'
-  gem 'webmock'
 end

data/README.md

@@ -267,6 +267,25 @@ puts translation.text
 # => Ojalá tuviéramos un auto.
 ```
 
+To use more than one glossary at once, specify the `glossary_ids` option with an
+array of up to 5 glossary IDs (as strings or `DeepL::Resources::Glossary`
+objects) instead of `glossary_id`. This works for both text and document
+translation. `glossary_ids` requires `source_lang` to be set, cannot be combined
+with `glossary_id`, and raises `ArgumentError` if these rules are violated or
+more than 5 IDs are provided:
+
+```rb
+# Text translation with multiple glossaries
+translation = DeepL.translate 'Hello World', 'EN', 'ES',
+                              glossary_ids: ['aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e',
+                                             'bb59d8g1-1e13-524f-9b17-e6ccg1db8b7f']
+
+# Document translation with multiple glossaries
+handle = DeepL.document.upload 'my_document.docx', 'EN', 'ES', 'my_document.docx',
+                              glossary_ids: ['aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e',
+                                             'bb59d8g1-1e13-524f-9b17-e6ccg1db8b7f']
+```
+
 To list all the glossaries available, use the `glossaries.list` method:
 
 ```rb
@@ -457,6 +476,15 @@ style_rules = DeepL.style_rules.list
 translation = DeepL.translate 'Hello World', 'EN', 'ES', style_rule: style_rules.first
 ```
 
+The same `style_rule` option can be passed to document translation via
+`DeepL.document.upload` (or `DeepL.document.translate_document`), accepting either
+a style rule ID string or a `StyleRule` object:
+
+```rb
+handle = DeepL.document.upload 'my_document.docx', 'EN', 'ES', 'my_document.docx',
+                              style_rule: 'dca2e053-8ae5-45e6-a0d2-881156e7f4e4'
+```
+
 ### Translation Memories
 
 Translation memories allow you to store and reuse previously created translations.
@@ -464,11 +492,11 @@ 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
+Translation memories can also be managed in the DeepL UI via
+https://www.deepl.com/translation-memory.
 
-Currently translation memories must be uploaded and managed in the DeepL UI via
-https://www.deepl.com/translation-memory. Full translation memory management via
-the API will come shortly.
+Every method that takes a translation memory accepts either a string containing
+the translation memory ID or a `TranslationMemory` object.
 
 #### Listing translation memories
 
@@ -490,6 +518,176 @@ end
 translation_memories = DeepL.translation_memories.list(page: 0, page_size: 10)
 ```
 
+#### Retrieving a single translation memory
+
+`translation_memories.find` retrieves one translation memory by ID. In addition
+to the fields returned by `list`, the resource carries the `creation_time` and
+`updated_time` timestamps.
+
+```rb
+tm = DeepL.translation_memories.find 'YOUR_TM_ID'
+
+puts tm.class
+# => DeepL::Resources::TranslationMemory
+puts tm.name
+# => 'Legal'
+puts tm.segment_count
+# => 12
+puts tm.creation_time.class
+# => Time
+```
+
+#### Listing the segments of a translation memory
+
+`translation_memories.segments` returns one page of the segments of a
+translation memory as a `TranslationMemorySegments` object. Each segment holds
+the source text and one target per target language of the translation memory.
+
+Pagination is cursor-based: omit `page_cursor` on the first call, then pass the
+`next_page_cursor` of the previous response until `next_page?` is `false`. The
+method also accepts `page_size` (1-100, defaults to 50), `filter_text` (a
+substring matched against the source and target texts, at least 2 characters)
+and `filter_case_sensitive` (defaults to `false`).
+
+Note that `segment_count` is the number of segments stored in the translation
+memory; a text filter does not reduce it.
+
+```rb
+page = DeepL.translation_memories.segments 'YOUR_TM_ID', page_size: 50
+
+puts page.class
+# => DeepL::Resources::TranslationMemorySegments
+puts page.segment_count
+# => 12
+puts page.segments.first.source_text
+# => 'Quelltext Nummer 0'
+puts page.segments.first.targets.first.target_text
+# => 'Source text number 0'
+
+# Walk through every page of segments
+while page.next_page?
+  page = DeepL.translation_memories.segments 'YOUR_TM_ID',
+                                             page_size: 50,
+                                             page_cursor: page.next_page_cursor
+end
+
+# Only the segments matching a text
+page = DeepL.translation_memories.segments 'YOUR_TM_ID',
+                                           filter_text: 'Nummer 1',
+                                           filter_case_sensitive: true
+```
+
+#### Importing a translation memory
+
+`translation_memories.import_from_filepath` creates a new translation memory
+from a TMX file. It creates the import job, uploads the file and waits for the
+processing to finish, and returns the finished `TranslationMemoryJob`. Its
+result carries the ID of the newly created translation memory.
+
+```rb
+job = DeepL.translation_memories.import_from_filepath 'legal.tmx',
+                                                      display_name: 'Legal',
+                                                      timeout_s: 300
+
+puts job.class
+# => DeepL::Resources::TranslationMemoryJob
+puts job.status
+# => 'completed'
+puts job.result.translation_memory_id
+# => 'a74d88fb-ed2a-4943-a664-a4512398b994'
+puts job.result.skipped_segment_count
+# => 0
+```
+
+The three steps can also be performed separately, for example to upload a file
+that is not available on the local file system. The upload URL is a pre-signed
+storage URL outside of the DeepL API, so no authorization header is sent with
+the upload.
+
+```rb
+content = File.binread 'legal.tmx'
+created = DeepL.translation_memories.create_import 'legal.tmx', content.bytesize,
+                                                   content_type: 'application/xml',
+                                                   display_name: 'Legal'
+
+puts created.upload_url
+# => 'https://...'
+
+DeepL.translation_memories.upload_file created, content
+job = DeepL.translation_memories.wait_until_job_done created.job_id
+```
+
+Until the file is uploaded the job stays in the `awaiting_input` status and
+`result.required_action` describes what is missing. The API detects the upload
+asynchronously, so the job keeps reporting `awaiting_input` for a while
+afterwards, typically around half a minute, before it completes.
+`wait_until_job_done` therefore polls through that status like any other
+non-terminal one. A job whose file is never uploaded does not finish on its own,
+so pass `timeout_s` when that is a possibility.
+
+#### Exporting a translation memory
+
+`translation_memories.export_to_filepath` writes a translation memory to a TMX
+file. It creates the export job, waits for it to finish and downloads the
+result, overwriting the output file if it already exists.
+
+```rb
+job = DeepL.translation_memories.export_to_filepath 'YOUR_TM_ID', 'export.tmx'
+
+puts job.status
+# => 'completed'
+```
+
+The steps can be performed separately as well. Repeating the export of an
+unchanged translation memory reuses the previously completed job instead of
+starting a new one, which `reused_existing?` reports. Just like the upload URL,
+the download URL is a pre-signed storage URL and is requested without an
+authorization header.
+
+```rb
+created = DeepL.translation_memories.create_export 'YOUR_TM_ID'
+
+puts created.reused_existing?
+# => false
+
+job = DeepL.translation_memories.wait_until_job_done created.job_id
+
+puts job.result.download_url
+# => 'https://...'
+
+DeepL.translation_memories.download_export job, 'export.tmx'
+```
+
+#### Tracking import and export jobs
+
+`translation_memories.find_job` returns the current status of an import or
+export job, and `translation_memories.wait_until_job_done` polls it every five
+seconds until it finished, raising if the job failed or expired. Pass
+`timeout_s` to give up after a number of seconds instead of waiting forever.
+
+```rb
+job = DeepL.translation_memories.find_job 'YOUR_JOB_ID'
+
+puts job.operation
+# => 'import'
+puts job.status
+# => 'processing'
+puts job.finished?
+# => false
+```
+
+The status is one of `awaiting_input`, `processing`, `completed`, `downloaded`,
+`failed` or `expired`.
+
+#### Deleting a translation memory
+
+`translation_memories.destroy` deletes a translation memory and returns its ID.
+
+```rb
+DeepL.translation_memories.destroy 'YOUR_TM_ID'
+# => 'YOUR_TM_ID'
+```
+
 #### Using a translation memory in translations
 
 Pass the `translation_memory` parameter to `translate` to use a translation
@@ -510,6 +708,17 @@ translation = DeepL.translate 'Hello, world!', 'EN', 'DE',
                               translation_memory: translation_memories.first
 ```
 
+The same `translation_memory` and `translation_memory_threshold` options can be
+passed to document translation via `DeepL.document.upload` (or
+`DeepL.document.translate_document`). The `translation_memory` option accepts
+either a translation memory ID string or a `TranslationMemory` object:
+
+```rb
+handle = DeepL.document.upload 'my_document.docx', 'EN', 'DE', 'my_document.docx',
+                              translation_memory: 'YOUR_TM_ID',
+                              translation_memory_threshold: 80
+```
+
 ### Monitor usage
 
 To check current API usage, use:
@@ -551,6 +760,18 @@ doc_handle = DeepL.document.upload('/path/to/spanish_document.pdf', 'ES', 'EN',
 
 The `extra_body_parameters` option allows you to pass arbitrary parameters in the request body. This can be used to access beta features by adding new parameters, or to override built-in parameters (such as `target_lang`, `source_lang`, etc.) for testing purposes.
 
+### Sending additional HTTP headers
+
+You can pass additional HTTP headers to `translate`, `rephrase`, and the
+`document` methods. For example, to send the `X-DeepL-Reporting-Tag` header
+for usage reporting (see the [cookbook entry](https://developers.deepl.com/docs/learning-how-tos/cookbook/sending-custom-reporting-tags-from-client-libraries)):
+
+```rb
+additional_headers = { 'X-DeepL-Reporting-Tag' => 'my-tag' }
+translation = DeepL.translate 'Hello, world!', 'EN', 'DE', {}, additional_headers
+rephrased = DeepL.rephrase 'Hello, world!', 'EN', nil, nil, {}, additional_headers
+```
+
 ### Handle exceptions
 
 You can capture and process exceptions that may be raised during API calls. These are all the possible exceptions:
@@ -712,18 +933,6 @@ To run tests (rspec and rubocop), use
 bundle exec rake test
 ```
 
-### Caution: Changing VCR Tests
-
-If you need to rerecord some of the VCR tests, simply setting `record: :new_episodes` and rerunning `rspec` won't be enough in some cases, specifically around document translation (due to its statefulness) and glossaries (since a glossary ID is associated with a specific API account).
-For example, there are document translations tests that split up the `upload`, `get_status` and `download` calls into separate test cases. You need to first rerecord the `upload` call, you can do execute a single test like this (the line should be where the `it` block of the test starts):
-
-```sh
-rspec ./spec/api/deepl_spec.rb:152
-```
-
-This will return a `document_id` and a `document_key`, you will need to update the values in the `get_status` and `download` tests accordingly. You can find examples for this in the git history.
-Similarly, for the glossary tests you will need to delete the recorded HTTP requests for certain glossary IDs so that `rspec` will create the glossaries on your account instead. Feel free to reach out on our discord if you run into any trouble here.
-
 ## Acknowledgements
 
 This library was originally developed by [Daniel Herzog](mailto:info@danielherzog.es), we are grateful for his contributions. Beginning with v3.0.0, DeepL took over development and officially supports and maintains the library together with Daniel.

data/VERSION

@@ -1 +1 @@
-3.7.0
+3.9.0

data/deepl-rb.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: deepl-rb 3.7.0 ruby lib
+# stub: deepl-rb 3.9.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "deepl-rb".freeze
-  s.version = "3.7.0"
+  s.version = "3.9.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.metadata = { "bug_tracker_uri" => "https://github.com/DeepLcom/deepl-rb/issues", "changelog_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/CHANGELOG.md", "documentation_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/README.md", "homepage_uri" => "https://github.com/DeepLcom/deepl-rb" } if s.respond_to? :metadata=
   s.require_paths = ["lib".freeze]
   s.authors = ["DeepL SE".freeze]
-  s.date = "2026-05-14"
+  s.date = "2026-08-12"
   s.description = "Official Ruby library for the DeepL language translation API (v2). For more information, check this: https://www.deepl.com/docs/api-reference.html".freeze
   s.email = "open-source@deepl.com".freeze
   s.extra_rdoc_files = [
@@ -82,7 +82,17 @@ Gem::Specification.new do |s|
     "lib/deepl/requests/style_rule/update_configured_rules.rb",
     "lib/deepl/requests/style_rule/update_custom_instruction.rb",
     "lib/deepl/requests/translate.rb",
+    "lib/deepl/requests/translation_memory/base.rb",
+    "lib/deepl/requests/translation_memory/create_export.rb",
+    "lib/deepl/requests/translation_memory/create_import.rb",
+    "lib/deepl/requests/translation_memory/destroy.rb",
+    "lib/deepl/requests/translation_memory/download_export.rb",
+    "lib/deepl/requests/translation_memory/find.rb",
+    "lib/deepl/requests/translation_memory/find_job.rb",
     "lib/deepl/requests/translation_memory/list.rb",
+    "lib/deepl/requests/translation_memory/segments.rb",
+    "lib/deepl/requests/translation_memory/storage_base.rb",
+    "lib/deepl/requests/translation_memory/upload_file.rb",
     "lib/deepl/requests/usage.rb",
     "lib/deepl/resources/base.rb",
     "lib/deepl/resources/document_handle.rb",
@@ -93,11 +103,16 @@ Gem::Specification.new do |s|
     "lib/deepl/resources/style_rule.rb",
     "lib/deepl/resources/text.rb",
     "lib/deepl/resources/translation_memory.rb",
+    "lib/deepl/resources/translation_memory_export.rb",
+    "lib/deepl/resources/translation_memory_import.rb",
+    "lib/deepl/resources/translation_memory_job.rb",
+    "lib/deepl/resources/translation_memory_segments.rb",
     "lib/deepl/resources/usage.rb",
     "lib/deepl/style_rule_api.rb",
     "lib/deepl/translation_memory_api.rb",
     "lib/deepl/utils/backoff_timer.rb",
     "lib/deepl/utils/exception_builder.rb",
+    "lib/deepl/utils/time_parser.rb",
     "lib/http_client_options.rb",
     "lib/version.rb",
     "license_checker.sh",
@@ -105,25 +120,25 @@ Gem::Specification.new do |s|
     "spec/api/configuration_spec.rb",
     "spec/api/deepl_spec.rb",
     "spec/constants/constants_spec.rb",
-    "spec/fixtures/vcr_cassettes/deepl_document.yml",
-    "spec/fixtures/vcr_cassettes/deepl_document_download.yml",
-    "spec/fixtures/vcr_cassettes/deepl_glossaries.yml",
-    "spec/fixtures/vcr_cassettes/deepl_languages.yml",
-    "spec/fixtures/vcr_cassettes/deepl_rephrase.yml",
-    "spec/fixtures/vcr_cassettes/deepl_translate.yml",
-    "spec/fixtures/vcr_cassettes/deepl_usage.yml",
-    "spec/fixtures/vcr_cassettes/glossaries.yml",
-    "spec/fixtures/vcr_cassettes/languages.yml",
-    "spec/fixtures/vcr_cassettes/rephrase_texts.yml",
-    "spec/fixtures/vcr_cassettes/style_rules.yml",
-    "spec/fixtures/vcr_cassettes/style_rules_crud.yml",
-    "spec/fixtures/vcr_cassettes/translate_texts.yml",
-    "spec/fixtures/vcr_cassettes/translation_memories.yml",
-    "spec/fixtures/vcr_cassettes/usage.yml",
     "spec/integration_tests/document_api_spec.rb",
+    "spec/integration_tests/document_error_paths_spec.rb",
+    "spec/integration_tests/glossary_api_spec.rb",
+    "spec/integration_tests/glossary_error_paths_spec.rb",
     "spec/integration_tests/integration_test_utils.rb",
+    "spec/integration_tests/languages_api_spec.rb",
+    "spec/integration_tests/languages_error_paths_spec.rb",
+    "spec/integration_tests/rephrase_api_spec.rb",
+    "spec/integration_tests/rephrase_error_paths_spec.rb",
+    "spec/integration_tests/smoke_test_spec.rb",
     "spec/integration_tests/style_rule_api_spec.rb",
+    "spec/integration_tests/style_rule_error_paths_spec.rb",
+    "spec/integration_tests/translate_api_spec.rb",
+    "spec/integration_tests/translate_error_paths_spec.rb",
     "spec/integration_tests/translation_memory_api_spec.rb",
+    "spec/integration_tests/translation_memory_error_paths_spec.rb",
+    "spec/integration_tests/usage_api_spec.rb",
+    "spec/integration_tests/usage_error_paths_spec.rb",
+    "spec/requests/document/upload_spec.rb",
     "spec/requests/extra_body_parameters_types_spec.rb",
     "spec/requests/glossary/create_spec.rb",
     "spec/requests/glossary/destroy_spec.rb",
@@ -144,15 +159,33 @@ Gem::Specification.new do |s|
     "spec/requests/style_rule/update_custom_instruction_spec.rb",
     "spec/requests/style_rule/update_spec.rb",
     "spec/requests/translate_spec.rb",
+    "spec/requests/translation_memory/create_export_spec.rb",
+    "spec/requests/translation_memory/create_import_spec.rb",
+    "spec/requests/translation_memory/destroy_spec.rb",
+    "spec/requests/translation_memory/download_export_spec.rb",
+    "spec/requests/translation_memory/find_job_spec.rb",
+    "spec/requests/translation_memory/find_spec.rb",
     "spec/requests/translation_memory/list_spec.rb",
+    "spec/requests/translation_memory/segments_spec.rb",
+    "spec/requests/translation_memory/upload_file_spec.rb",
     "spec/requests/usage_spec.rb",
+    "spec/resources/custom_instruction_spec.rb",
     "spec/resources/glossary_spec.rb",
     "spec/resources/language_pair_spec.rb",
     "spec/resources/language_spec.rb",
+    "spec/resources/style_rule_spec.rb",
     "spec/resources/text_spec.rb",
+    "spec/resources/translation_memory_export_spec.rb",
+    "spec/resources/translation_memory_import_spec.rb",
+    "spec/resources/translation_memory_job_spec.rb",
+    "spec/resources/translation_memory_segments_spec.rb",
     "spec/resources/translation_memory_spec.rb",
     "spec/resources/usage_spec.rb",
-    "spec/spec_helper.rb"
+    "spec/spec_helper.rb",
+    "spec/support/live_mock_server.rb",
+    "spec/support/managed_glossary.rb",
+    "spec/support/managed_style_rule.rb",
+    "spec/support/managed_translation_memory.rb"
   ]
   s.homepage = "https://github.com/DeepLcom/deepl-rb".freeze
   s.licenses = ["MIT".freeze]

data/lib/deepl/document_api.rb

@@ -25,7 +25,17 @@ module DeepL
     # @param [String, nil] filename The filename of the file, including its extension. Used to open
     #                               the different kinds of documents (PDFs, etc). If nil, will use
     #                               the filename of +input_file_path+.
-    # @param [Hash] options Additional (body) options for the upload.
+    # @param [Hash] options Additional (body) options for the upload. Notable glossary options:
+    #                       +:glossary_id+ (a single glossary ID) or +:glossary_ids+ (an array of
+    #                       up to 5 glossary IDs, as strings or `DeepL::Resources::Glossary`
+    #                       objects). +:glossary_ids+ requires +source_lang+ to be set, cannot be
+    #                       combined with +:glossary_id+, and raises `ArgumentError` if these rules
+    #                       are violated or more than 5 IDs are provided. Notable style/translation
+    #                       memory options (mirroring text translation): +:style_rule+ (a style rule
+    #                       ID string or a `DeepL::Resources::StyleRule` object),
+    #                       +:translation_memory+ (a translation memory ID string or a
+    #                       `DeepL::Resources::TranslationMemory` object), and
+    #                       +:translation_memory_threshold+ (integer 0-100, recommended minimum 75).
     # @param [Hash] additional_headers Additional HTTP headers for the upload.
     # @return [DeepL::Resources::DocumentHandle] Document handle for the uploaded document.
 

data/lib/deepl/requests/base.rb

@@ -6,6 +6,9 @@
 module DeepL
   module Requests
     class Base # rubocop:disable Metrics/ClassLength
+      # Maximum number of glossaries that may be provided via the +glossary_ids+ option.
+      MAX_GLOSSARY_IDS = 5
+
       attr_reader :api, :response, :options
 
       def initialize(api, options = {}, additional_headers = {})
@@ -85,7 +88,7 @@ module DeepL
         api.configuration.logger&.info("Request to the DeepL API: #{self}")
         api.configuration.logger&.debug("Request details: #{details}")
         loop do
-          resp = api.http_client.request(req)
+          resp = http_client.request(req)
           validate_response!(resp)
           return [req, resp]
         rescue DeepL::Exceptions::Error => e
@@ -95,7 +98,7 @@ module DeepL
             api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
           end
           api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
-                                         "request #{request} after sleeping for " \
+                                         "request #{self} after sleeping for " \
                                          "#{format('%.2f', @backoff_timer.time_until_deadline)}")
           files_to_reset.each(&:rewind)
           @backoff_timer.sleep_until_deadline
@@ -106,7 +109,7 @@ module DeepL
             api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
           end
           api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
-                                         "request #{request} after sleeping for " \
+                                         "request #{self} after sleeping for " \
                                          "#{format('%.2f', @backoff_timer.time_until_deadline)}")
           files_to_reset.each(&:rewind)
           @backoff_timer.sleep_until_deadline
@@ -172,6 +175,49 @@ module DeepL
         raise Utils::ExceptionBuilder.new(response).build
       end
 
+      # Validates the +glossary_ids+ option and resolves it to an array of glossary ID strings.
+      #
+      # The +glossary_ids+ option accepts an array of up to `MAX_GLOSSARY_IDS` glossary
+      # identifiers. Each entry may be a glossary ID string or a
+      # `DeepL::Resources::Glossary` object. It:
+      # * requires +source_lang+ to be set,
+      # * cannot be combined with the singular +glossary_id+ option,
+      # * allows at most `MAX_GLOSSARY_IDS` identifiers.
+      #
+      # The API expects +glossary_ids+ as an array (a JSON array in the JSON translate body).
+      # Callers sending multipart/form-data (e.g. document upload) should join the returned
+      # array into a comma-separated string.
+      #
+      # @param [String, nil] source_lang The source language for the request.
+      # @return [Array<String>, nil] The list of glossary IDs, or nil if the +glossary_ids+
+      #                              option was not provided.
+      # @raise [ArgumentError] If any of the validation rules above are violated.
+      def build_glossary_ids_param(source_lang)
+        return nil unless option?(:glossary_ids)
+
+        ids = Array(delete_option(:glossary_ids))
+        return nil if ids.empty?
+
+        validate_glossary_ids!(ids, source_lang)
+        ids.map do |glossary|
+          glossary.is_a?(DeepL::Resources::Glossary) ? glossary.id : glossary.to_s
+        end
+      end
+
+      def validate_glossary_ids!(ids, source_lang)
+        if option?(:glossary_id)
+          raise ArgumentError,
+                'The `glossary_ids` option cannot be used together with the `glossary_id` option'
+        end
+        if source_lang.nil?
+          raise ArgumentError, 'The `glossary_ids` option requires `source_lang` to be set'
+        end
+        return unless ids.size > MAX_GLOSSARY_IDS
+
+        raise ArgumentError,
+              "A maximum of #{MAX_GLOSSARY_IDS} glossary IDs may be provided via `glossary_ids`"
+      end
+
       def path
         raise NotImplementedError
       end
@@ -189,6 +235,12 @@ module DeepL
         api.configuration.host
       end
 
+      # Subclasses that talk to a host other than the DeepL API, such as a pre-signed storage
+      # URL, override this to request through their own connection.
+      def http_client
+        api.http_client
+      end
+
       def query_params
         options
       end