deepl-rb 3.7.0 → 3.9.0

data/spec/integration_tests/translate_api_spec.rb

@@ -0,0 +1,117 @@
+# Copyright 2026 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.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'DeepL.translate' do # rubocop:disable RSpec/DescribeClass
+  include_context 'with a live mock server'
+
+  let(:text) { 'proton beam' }
+
+  describe 'happy path' do
+    it 'translates a single string into a Text resource' do
+      result = DeepL.translate(text, 'EN', 'DE')
+
+      expect(result).to be_a(DeepL::Resources::Text)
+      expect(result.text).to be_a(String)
+      expect(result.text).not_to be_empty
+    end
+
+    it 'translates an array of strings into an array of Text resources' do
+      results = DeepL.translate(%w[Sample Word], 'EN', 'ES')
+
+      expect(results).to be_an(Array)
+      expect(results.size).to eq(2)
+      expect(results).to all(be_a(DeepL::Resources::Text))
+    end
+  end
+
+  describe 'options' do
+    it 'accepts a formality setting' do
+      result = DeepL.translate('How are you?', 'EN', 'DE', { formality: 'more' })
+
+      expect(result).to be_a(DeepL::Resources::Text)
+    end
+
+    it 'translates with XML tag handling and ignored tags' do
+      result = DeepL.translate('<p>Sample <code>x</code></p>', 'EN', 'ES',
+                               { tag_handling: 'xml', ignore_tags: %w[code] })
+
+      expect(result.text).to be_a(String)
+      expect(result.text).not_to be_empty
+    end
+
+    it 'accepts a context option' do
+      result = DeepL.translate('That is hot!', 'EN', 'ES', { context: 'about the weather' })
+
+      expect(result).to be_a(DeepL::Resources::Text)
+    end
+
+    it 'accepts an empty context option' do
+      result = DeepL.translate('That is hot!', 'EN', 'ES', { context: '' })
+
+      expect(result).to be_a(DeepL::Resources::Text)
+    end
+
+    it 'translates an HTML document with split_sentences, outline_detection and splitting_tags' do
+      document = '<document><meta><title>Title</title></meta>' \
+                 '<content><par>First sentence. Second one.</par></content></document>'
+      result = DeepL.translate(document, 'EN', 'ES',
+                               { tag_handling: 'xml', split_sentences: 'nonewlines',
+                                 outline_detection: false, splitting_tags: %w[title par] })
+
+      expect(result).to be_a(DeepL::Resources::Text)
+      expect(result.text).not_to be_empty
+    end
+
+    it 'translates using a glossary' do
+      with_managed_glossary(name: 'Translate Glossary', source_lang: 'en', target_lang: 'de',
+                            entries: [%w[Hello Hallo]]) do |glossary|
+        result = DeepL.translate('Hello', 'EN', 'DE', { glossary_id: glossary.id })
+
+        expect(result).to be_a(DeepL::Resources::Text)
+        expect(result.text).not_to be_empty
+      end
+    end
+
+    it 'translates using multiple glossaries via glossary_ids' do # rubocop:disable RSpec/ExampleLength
+      with_managed_glossary(name: 'Translate Glossary IDs 1', source_lang: 'en', target_lang: 'de',
+                            entries: [%w[Hello Hallo]]) do |glossary1|
+        with_managed_glossary(name: 'Translate Glossary IDs 2', source_lang: 'en',
+                              target_lang: 'de', entries: [%w[World Welt]]) do |glossary2|
+          # Newly created glossaries can lag behind (eventual consistency), so
+          # ensure they are resolvable before translating and tolerate a
+          # transient "not found" on the translate call itself.
+          wait_until_glossaries_ready(glossary1, glossary2)
+          result = translate_retrying_missing_glossary(
+            'Hello', 'EN', 'DE', { glossary_ids: [glossary1.id, glossary2.id] }
+          )
+
+          expect(result).to be_a(DeepL::Resources::Text)
+          expect(result.text).not_to be_empty
+        end
+      end
+    end
+
+    %w[quality_optimized latency_optimized prefer_quality_optimized].each do |model_type|
+      it "returns model_type_used for #{model_type}" do
+        result = DeepL.translate(text, 'EN', 'DE', { model_type: model_type })
+
+        expect(result).to be_a(DeepL::Resources::Text)
+        expect(result.model_type_used).not_to be_nil
+      end
+    end
+
+    %w[v1 v2].each do |version|
+      it "translates with tag_handling_version #{version}" do
+        result = DeepL.translate('<p>Hello world</p>', 'EN', 'DE',
+                                 { tag_handling: 'html', tag_handling_version: version })
+
+        expect(result).to be_a(DeepL::Resources::Text)
+        expect(result.text).not_to be_empty
+      end
+    end
+  end
+end

data/spec/integration_tests/translate_error_paths_spec.rb

@@ -0,0 +1,48 @@
+# Copyright 2026 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.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'DeepL.translate error paths' do # rubocop:disable RSpec/DescribeClass
+  include_context 'with a live mock server'
+
+  let(:text) { 'proton beam' }
+
+  describe 'authorization failures' do
+    it 'raises AuthorizationFailed when the auth key is invalid' do
+      request = DeepL::Requests::Translate.new(unauthorized_api, text, 'EN', 'DE')
+
+      expect { request.request }.to raise_error(DeepL::Exceptions::AuthorizationFailed)
+    end
+  end
+
+  describe 'bad request errors' do
+    it 'raises BadRequest for an unsupported target language' do
+      expect { DeepL.translate(text, 'EN', 'ZZ') }
+        .to raise_error(DeepL::Exceptions::BadRequest)
+    end
+
+    it 'raises BadRequest when no target language is given' do
+      expect { DeepL.translate(text, 'EN', nil) }
+        .to raise_error(DeepL::Exceptions::BadRequest)
+    end
+
+    # Real-server only: the mock coerces text:[null] to text:[""] and accepts it,
+    # so it cannot reproduce this; prod rejects [null] with 400.
+    it 'raises BadRequest when the text is nil', :real_server_only do
+      expect { DeepL.translate(nil, 'EN', 'DE') }
+        .to raise_error(DeepL::Exceptions::BadRequest)
+    end
+  end
+
+  describe 'request entity too large errors' do
+    it 'raises RequestEntityTooLarge when too many texts are sent in a single request' do
+      texts = Array.new(10_000) { |i| "This is the sentence number #{i}" }
+
+      expect { DeepL.translate(texts, 'EN', 'DE') }
+        .to raise_error(DeepL::Exceptions::RequestEntityTooLarge)
+    end
+  end
+end

data/spec/integration_tests/translation_memory_api_spec.rb

@@ -5,34 +5,25 @@
 
 require 'spec_helper'
 
-describe DeepL::TranslationMemoryApi do
-  before do
-    VCR.turn_off!
-    WebMock.allow_net_connect!
-  end
+describe DeepL::TranslationMemoryApi, :mock_server_only do
+  include_context 'with temp dir'
 
-  after do
-    VCR.turn_on!
-    WebMock.disable_net_connect!
-  end
+  let(:default_tm_id) { 'a74d88fb-ed2a-4943-a664-a4512398b994' }
+  let(:tmx_file_path) { write_example_tmx(File.join(temp_dir, 'example.tmx')) }
+  let(:translation_memories) { DeepL.translation_memories }
 
   describe '#translate_with_translation_memory' do
     it 'when performing a request with translation_memory_id' do
-      skip 'Only runs on mock server' if real_server?
-
       source_lang = 'DE'
       target_lang = 'EN'
       text = 'Protonenstrahl'
-      translation_memory_id = 'a74d88fb-ed2a-4943-a664-a4512398b994'
 
       result = DeepL.translate(text, source_lang, target_lang,
-                               { translation_memory: translation_memory_id })
+                               { translation_memory: default_tm_id })
       expect(result).to be_a(DeepL::Resources::Text)
     end
 
     it 'when performing a request with translation_memory resource object' do
-      skip 'Only runs on mock server' if real_server?
-
       source_lang = 'DE'
       target_lang = 'EN'
       text = 'Protonenstrahl'
@@ -46,8 +37,6 @@ describe DeepL::TranslationMemoryApi do
 
   describe '#list_translation_memories' do
     it 'when requesting a list of all translation memories' do
-      skip 'Only runs on mock server' if real_server?
-
       translation_memories = DeepL.translation_memories.list
       expect(translation_memories).to be_an(Array)
       expect(translation_memories).not_to be_empty
@@ -57,6 +46,191 @@ describe DeepL::TranslationMemoryApi do
     end
   end
 
+  describe '#find' do
+    it 'when requesting a single translation memory by ID' do
+      translation_memory = DeepL.translation_memories.find(default_tm_id)
+      expect(translation_memory).to be_a(DeepL::Resources::TranslationMemory)
+      expect(translation_memory.translation_memory_id).to eq(default_tm_id)
+      expect(translation_memory.name).to eq('Default Translation Memory')
+      expect(translation_memory.source_language).to eq('de')
+      expect(translation_memory.target_languages).to eq(%w[en es fr])
+      expect(translation_memory.segment_count).to eq(12)
+    end
+
+    it 'when requesting a single translation memory by resource object' do
+      translation_memory = DeepL.translation_memories.find(build_test_translation_memory)
+      expect(translation_memory.translation_memory_id).to eq(default_tm_id)
+      expect(translation_memory.creation_time).to be_a(Time)
+      expect(translation_memory.updated_time).to be_a(Time)
+    end
+  end
+
+  describe '#segments' do
+    it 'when requesting the segments of a translation memory' do
+      page = DeepL.translation_memories.segments(default_tm_id)
+      expect(page).to be_a(DeepL::Resources::TranslationMemorySegments)
+      expect(page.segments.length).to eq(12)
+      expect(page.segment_count).to eq(12)
+      expect(page.next_page?).to be(false)
+      expect(page.segments.first.source_text).to eq('Quelltext Nummer 0')
+    end
+
+    it 'when reading segment timestamps' do
+      # The API does not return creation_time/updated_time on segments at all, and returns
+      # last_used_time only for segments that have been used.
+      page = DeepL.translation_memories.segments(default_tm_id)
+      expect(page.segments.first.creation_time).to be_nil
+      expect(page.segments.first.updated_time).to be_nil
+      expect(page.segments.first.last_used_time).to be_a(Time)
+      expect(page.segments[1].last_used_time).to be_nil
+    end
+
+    it 'when reading the target segments of a source segment' do
+      page = DeepL.translation_memories.segments(default_tm_id, page_size: 1)
+      segment = page.segments.first
+      expect(segment.targets.map(&:target_language)).to eq(%w[en es fr])
+      expect(segment.targets.first.target_text).to eq('Target text number 0 (de->en)')
+      expect(segment.targets.first.target_segment_id).not_to be_nil
+      expect(segment.targets.first.last_used_time).to be_a(Time)
+    end
+
+    it 'when paginating through the segments with the page cursor' do
+      first_page = DeepL.translation_memories.segments(default_tm_id, page_size: 5)
+      second_page = next_segments_page(first_page)
+      last_page = next_segments_page(second_page)
+
+      expect(first_page.segments.length).to eq(5)
+      expect(first_page.next_page?).to be(true)
+      expect(second_page.segments.first.source_text).to eq('Quelltext Nummer 5')
+      expect(last_page.segments.length).to eq(2)
+      expect(last_page.next_page?).to be(false)
+    end
+
+    it 'when filtering the segments by a text containing a space' do
+      page = DeepL.translation_memories.segments(default_tm_id, filter_text: 'Nummer 1')
+      expect(page.segments.map(&:source_text))
+        .to eq(['Quelltext Nummer 1', 'Quelltext Nummer 10', 'Quelltext Nummer 11'])
+      # segment_count is the number of segments stored in the translation memory, a text filter
+      # does not reduce it.
+      expect(page.segment_count).to eq(12)
+    end
+
+    it 'when filtering the segments case-sensitively' do
+      page = DeepL.translation_memories.segments(default_tm_id, filter_text: 'quelltext',
+                                                                filter_case_sensitive: true)
+      expect(page.segments).to be_empty
+      expect(page.segment_count).to eq(12)
+    end
+  end
+
+  describe '#import_from_filepath' do
+    it 'when importing a translation memory from a TMX file' do
+      with_managed_translation_memory(tmx_file_path, display_name: 'Imported TM') do |job|
+        expect(job).to be_a(DeepL::Resources::TranslationMemoryJob)
+        expect(job.operation).to eq('import')
+        expect(job.display_name).to eq('Imported TM')
+        expect(job.status).to eq('completed')
+        expect(job.finished?).to be(true)
+        expect(job.result.translation_memory_id).not_to be_nil
+        expect(job.result.skipped_segment_count).to eq(0)
+      end
+    end
+
+    it 'when the imported translation memory can be retrieved afterwards' do
+      with_managed_translation_memory(tmx_file_path) do |job|
+        translation_memory = DeepL.translation_memories.find(job.result.translation_memory_id)
+        expect(translation_memory.name).to eq('example.tmx')
+        expect(translation_memory.source_language).to eq('de')
+        expect(job.source_content_type).to eq('application/xml')
+        expect(job.source_content_length).to eq(File.size(tmx_file_path))
+      end
+    end
+  end
+
+  describe '#create_import' do
+    it 'when the import job is still awaiting the file upload' do
+      created = DeepL.translation_memories.create_import('awaiting.tmx', 128,
+                                                         display_name: 'Awaiting Upload')
+      expect(created).to be_a(DeepL::Resources::TranslationMemoryImport)
+      expect(created.upload_url).to start_with('http')
+      expect(created.expires_at).to be_a(Time)
+
+      job = DeepL.translation_memories.find_job(created.job_id)
+      expect(job.awaiting_input?).to be(true)
+      expect(job.status).to eq('awaiting_input')
+      expect(job.result.required_action).not_to be_nil
+    end
+
+    # The API detects the upload asynchronously, so an uploaded job keeps reporting
+    # `awaiting_input` for a while. The wait loop must poll through that status.
+    it 'when waiting on an uploaded job it polls through the awaiting_input status' do
+      created = create_uploaded_import(translation_memories, tmx_file_path, processing_polls: 1)
+      polled_statuses = []
+      allow(translation_memories).to receive(:find_job).and_wrap_original do |original, *args|
+        original.call(*args).tap { |status| polled_statuses << status.status }
+      end
+      expect(translation_memories).to receive(:sleep).once
+
+      job = translation_memories.wait_until_job_done(created.job_id)
+
+      expect(polled_statuses).to eq(%w[awaiting_input completed])
+      expect(job.status).to eq('completed')
+      DeepL.translation_memories.destroy(job.result.translation_memory_id)
+    end
+
+    it 'when the file is never uploaded it waits until the timeout of the caller' do
+      created = translation_memories.create_import('never-uploaded.tmx', 128)
+      # Such a job does not finish on its own, only the timeout ends the wait.
+      expect(translation_memories).not_to receive(:sleep)
+
+      expect { translation_memories.wait_until_job_done(created.job_id, timeout_s: 0) }
+        .to raise_error(DeepL::Exceptions::Error, /Manual timeout of 0s exceeded/)
+    end
+  end
+
+  describe '#export_to_filepath' do
+    let(:output_path) { File.join(temp_dir, 'export.tmx') }
+
+    it 'when exporting a translation memory to a TMX file' do
+      job = DeepL.translation_memories.export_to_filepath(default_tm_id, output_path)
+      expect(job).to be_a(DeepL::Resources::TranslationMemoryJob)
+      expect(job.operation).to eq('export')
+      expect(job.status).to eq('completed')
+      expect(job.result.download_url).to start_with('http')
+
+      contents = File.read(output_path)
+      expect(contents).to include('<tmx version="1.4">')
+      expect(contents).to include('<seg>Quelltext Nummer 0</seg>')
+      expect(contents).to include('<tuv xml:lang="en"><seg>Target text number 0 (de->en)</seg>')
+    end
+
+    it 'when re-exporting an unchanged translation memory it reuses the completed job' do
+      job = DeepL.translation_memories.export_to_filepath(default_tm_id, output_path)
+      reused = DeepL.translation_memories.create_export(default_tm_id)
+      expect(reused).to be_a(DeepL::Resources::TranslationMemoryExport)
+      expect(reused.reused_existing?).to be(true)
+      expect(reused.job_id).to eq(job.job_id)
+      expect(reused.translation_memory_id).to eq(default_tm_id)
+    end
+  end
+
+  describe '#destroy' do
+    it 'when deleting a translation memory it can no longer be found' do
+      job = DeepL.translation_memories.import_from_filepath(tmx_file_path)
+      translation_memory_id = job.result.translation_memory_id
+
+      expect(DeepL.translation_memories.destroy(translation_memory_id))
+        .to eq(translation_memory_id)
+      expect { DeepL.translation_memories.find(translation_memory_id) }
+        .to raise_error(DeepL::Exceptions::NotFound)
+    end
+  end
+
+  def next_segments_page(page)
+    DeepL.translation_memories.segments(default_tm_id, page_size: 5,
+                                                       page_cursor: page.next_page_cursor)
+  end
+
   def build_test_translation_memory
     tm_data = {
       'translation_memory_id' => 'a74d88fb-ed2a-4943-a664-a4512398b994',

data/spec/integration_tests/translation_memory_error_paths_spec.rb

@@ -0,0 +1,87 @@
+# Copyright 2026 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.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe DeepL::TranslationMemoryApi, :mock_server_only do # rubocop:disable RSpec/SpecFilePathFormat
+  include_context 'with a live mock server'
+
+  let(:default_tm_id) { 'a74d88fb-ed2a-4943-a664-a4512398b994' }
+  let(:missing_uuid) { '00000000-0000-0000-0000-000000000000' }
+
+  describe 'authorization failures' do
+    let(:unauthorized_translation_memories) { described_class.new(unauthorized_api) }
+
+    it 'raises AuthorizationFailed when listing with an invalid auth key' do
+      expect { unauthorized_translation_memories.list }
+        .to raise_error(DeepL::Exceptions::AuthorizationFailed)
+    end
+
+    it 'raises AuthorizationFailed on a read operation (find)' do
+      expect { unauthorized_translation_memories.find(default_tm_id) }
+        .to raise_error(DeepL::Exceptions::AuthorizationFailed)
+    end
+
+    it 'raises AuthorizationFailed on a write operation (create_export)' do
+      expect { unauthorized_translation_memories.create_export(default_tm_id) }
+        .to raise_error(DeepL::Exceptions::AuthorizationFailed)
+    end
+  end
+
+  describe 'not-found failures' do
+    it 'raises NotFound when #find is called with a missing UUID' do
+      expect { DeepL.translation_memories.find(missing_uuid) }
+        .to raise_error(DeepL::Exceptions::NotFound)
+    end
+
+    it 'raises NotFound when #segments is called with a missing UUID' do
+      expect { DeepL.translation_memories.segments(missing_uuid) }
+        .to raise_error(DeepL::Exceptions::NotFound)
+    end
+
+    it 'raises NotFound when #find_job is called with a missing UUID' do
+      expect { DeepL.translation_memories.find_job(missing_uuid) }
+        .to raise_error(DeepL::Exceptions::NotFound)
+    end
+  end
+
+  describe 'bad-request failures' do
+    it 'raises BadRequest when #segments is called with a too short text filter' do
+      expect { DeepL.translation_memories.segments(default_tm_id, filter_text: 'a') }
+        .to raise_error(DeepL::Exceptions::BadRequest)
+    end
+
+    it 'raises an error when #destroy is called with a malformed UUID' do
+      expect { DeepL.translation_memories.destroy('invalid-uuid') }
+        .to raise_error(DeepL::Exceptions::Error)
+    end
+  end
+
+  describe 'client-side validation failures' do
+    it 'raises an error when #find is called with an empty ID' do
+      expect { DeepL.translation_memories.find('') }
+        .to raise_error(DeepL::Exceptions::Error, /must not be empty/)
+    end
+
+    it 'raises an error when #find_job is called with an empty job ID' do
+      expect { DeepL.translation_memories.find_job(nil) }
+        .to raise_error(DeepL::Exceptions::Error, /must not be empty/)
+    end
+
+    it 'raises an error when #import_from_filepath is given a missing file' do
+      expect { DeepL.translation_memories.import_from_filepath('/no/such/file.tmx') }
+        .to raise_error(DeepL::Exceptions::Error, /No file found/)
+    end
+
+    it 'raises an error when #download_export is given an unfinished job' do
+      created = DeepL.translation_memories.create_export(default_tm_id)
+      job = DeepL::Resources::TranslationMemoryJob.new(
+        { 'job_id' => created.job_id, 'results' => [{ 'status' => 'processing' }] }, nil, nil
+      )
+      expect { DeepL.translation_memories.download_export(job, '/tmp/unused.tmx') }
+        .to raise_error(DeepL::Exceptions::Error, /no download URL/)
+    end
+  end
+end

data/spec/integration_tests/usage_api_spec.rb

@@ -0,0 +1,29 @@
+# Copyright 2026 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.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'DeepL.usage' do # rubocop:disable RSpec/DescribeClass
+  describe 'happy path' do
+    it 'returns a Usage resource with integer counters where count does not exceed limit' do
+      usage = DeepL.usage
+
+      expect(usage).to be_a(DeepL::Resources::Usage)
+      expect(usage).to respond_to(:character_count, :character_limit)
+      expect(usage.character_count).to be_an(Integer)
+      expect(usage.character_limit).to be_an(Integer)
+      expect(usage.character_count).to be <= usage.character_limit
+    end
+  end
+
+  describe 'resource shape' do
+    it 'exposes quota_exceeded? consistent with character_count vs character_limit' do
+      usage = DeepL.usage
+
+      expect(usage).to respond_to(:quota_exceeded?)
+      expect(usage.quota_exceeded?).to eq(usage.character_count >= usage.character_limit)
+    end
+  end
+end

data/spec/integration_tests/usage_error_paths_spec.rb

@@ -0,0 +1,18 @@
+# Copyright 2026 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.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'DeepL.usage error paths' do # rubocop:disable RSpec/DescribeClass
+  include_context 'with a live mock server'
+
+  describe 'authorization failures' do
+    it 'raises AuthorizationFailed when the auth key is invalid' do
+      request = DeepL::Requests::Usage.new(unauthorized_api)
+
+      expect { request.request }.to raise_error(DeepL::Exceptions::AuthorizationFailed)
+    end
+  end
+end

data/spec/requests/document/upload_spec.rb

@@ -0,0 +1,130 @@
+# Copyright 2026 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe DeepL::Requests::Document::Upload do
+  subject(:upload) do
+    described_class.new(api, input_file_path, source_lang, target_lang, filename, options)
+  end
+
+  around do |tests|
+    tmp_env = replace_env_preserving_deepl_vars_except_mock_server
+    tests.call
+    ENV.replace(tmp_env)
+  end
+
+  let(:api) { build_deepl_api }
+  let(:input_file_path) { '/tmp/example.txt' }
+  let(:source_lang) { 'EN' }
+  let(:target_lang) { 'DE' }
+  let(:filename) { 'example.txt' }
+  let(:options) { {} }
+  let(:input_file) { instance_double(File) }
+
+  # Builds the multipart form data without performing any network or filesystem IO.
+  def form_data
+    upload.send(:build_base_form_data, input_file)
+  end
+
+  def form_value(form, key)
+    field = form.find { |name, _| name == key }
+    field&.last
+  end
+
+  describe '#initialize' do
+    it 'creates a request object' do
+      expect(upload).to be_a(described_class)
+    end
+  end
+
+  describe 'building the upload form data' do
+    context 'when using the `style_rule` option' do
+      it 'does not append a `style_id` field when not provided' do
+        expect(form_value(form_data, 'style_id')).to be_nil
+      end
+
+      it 'appends a `style_id` field from a style rule ID string' do
+        options[:style_rule] = 'style-123'
+        expect(form_value(form_data, 'style_id')).to eq('style-123')
+      end
+
+      it 'appends a `style_id` field from a StyleRule object' do
+        options[:style_rule] =
+          DeepL::Resources::StyleRule.new({ 'style_id' => 'style-obj' }, nil, nil)
+        expect(form_value(form_data, 'style_id')).to eq('style-obj')
+      end
+    end
+
+    context 'when using the `translation_memory` option' do
+      it 'does not append a `translation_memory_id` field when not provided' do
+        expect(form_value(form_data, 'translation_memory_id')).to be_nil
+      end
+
+      it 'appends a `translation_memory_id` field from a translation memory ID string' do
+        options[:translation_memory] = 'tm-123'
+        expect(form_value(form_data, 'translation_memory_id')).to eq('tm-123')
+      end
+
+      it 'appends a `translation_memory_id` field from a TranslationMemory object' do
+        options[:translation_memory] =
+          DeepL::Resources::TranslationMemory.new({ 'translation_memory_id' => 'tm-obj' }, nil, nil)
+        expect(form_value(form_data, 'translation_memory_id')).to eq('tm-obj')
+      end
+
+      it 'appends a `translation_memory_threshold` field serialized to a string' do
+        options[:translation_memory] = 'tm-123'
+        options[:translation_memory_threshold] = 80
+        form = form_data
+        expect(form_value(form, 'translation_memory_id')).to eq('tm-123')
+        expect(form_value(form, 'translation_memory_threshold')).to eq('80')
+      end
+
+      it 'does not append a `translation_memory_threshold` field when not provided' do
+        options[:translation_memory] = 'tm-123'
+        expect(form_value(form_data, 'translation_memory_threshold')).to be_nil
+      end
+    end
+
+    context 'when using the `glossary_ids` option' do
+      it 'does not append a `glossary_ids` field when not provided' do
+        expect(form_value(form_data, 'glossary_ids')).to be_nil
+      end
+
+      it 'appends a comma-separated `glossary_ids` field from an array of IDs' do
+        options[:glossary_ids] = %w[gid1 gid2 gid3]
+        expect(form_value(form_data, 'glossary_ids')).to eq('gid1,gid2,gid3')
+      end
+
+      it 'appends `glossary_ids` from Glossary objects using their IDs' do
+        options[:glossary_ids] = [
+          DeepL::Resources::Glossary.new({ 'glossary_id' => 'gid-obj' }, nil, nil),
+          'gid-str'
+        ]
+        expect(form_value(form_data, 'glossary_ids')).to eq('gid-obj,gid-str')
+      end
+
+      it 'raises when combined with the singular `glossary_id` option' do
+        options[:glossary_id] = 'single'
+        options[:glossary_ids] = %w[gid1]
+        expect { form_data }.to raise_error(ArgumentError, /cannot be used together/)
+      end
+
+      it 'raises when more than 5 glossary IDs are provided' do
+        options[:glossary_ids] = %w[a b c d e f]
+        expect { form_data }.to raise_error(ArgumentError, /maximum of 5 glossary IDs/)
+      end
+
+      context 'when `source_lang` is not set' do
+        let(:source_lang) { nil }
+
+        it 'raises because `glossary_ids` requires `source_lang`' do
+          options[:glossary_ids] = %w[gid1]
+          expect { form_data }.to raise_error(ArgumentError, /requires `source_lang`/)
+        end
+      end
+    end
+  end
+end