deepl-rb 3.8.0 → 3.9.0

data/spec/requests/translation_memory/find_job_spec.rb

@@ -0,0 +1,37 @@
+# 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::TranslationMemory::FindJob do
+  subject(:translation_memory_find_job) { described_class.new(api, job_id, options) }
+
+  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(:job_id) { '5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d' }
+  let(:options) { {} }
+
+  describe '#initialize' do
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(translation_memory_find_job).to be_a(described_class)
+      end
+    end
+  end
+
+  describe '#to_s' do
+    context 'when building a request' do
+      it 'requests the job below the v3 prefix' do
+        expect(translation_memory_find_job.to_s)
+          .to eq("GET /v3/translation_memories/jobs/#{job_id}")
+      end
+    end
+  end
+end

data/spec/requests/translation_memory/find_spec.rb

@@ -0,0 +1,36 @@
+# 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::TranslationMemory::Find do
+  subject(:translation_memory_find) { described_class.new(api, id, options) }
+
+  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(:id) { 'a74d88fb-ed2a-4943-a664-a4512398b994' }
+  let(:options) { {} }
+
+  describe '#initialize' do
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(translation_memory_find).to be_a(described_class)
+      end
+    end
+  end
+
+  describe '#to_s' do
+    context 'when building a request' do
+      it 'requests the translation memory below the v3 prefix' do
+        expect(translation_memory_find.to_s).to eq("GET /v3/translation_memories/#{id}")
+      end
+    end
+  end
+end

data/spec/requests/translation_memory/segments_spec.rb

@@ -0,0 +1,58 @@
+# 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::TranslationMemory::Segments do
+  subject(:translation_memory_segments) { described_class.new(api, id, options) }
+
+  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(:id) { 'a74d88fb-ed2a-4943-a664-a4512398b994' }
+  let(:options) { {} }
+
+  describe '#initialize' do
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(translation_memory_segments).to be_a(described_class)
+      end
+    end
+  end
+
+  describe '#to_s' do
+    context 'when no options are given' do
+      it 'requests the segments below the v3 prefix without a query string' do
+        expect(translation_memory_segments.to_s)
+          .to eq("GET /v3/translation_memories/#{id}/segments")
+      end
+    end
+
+    context 'when the supported options are given' do
+      let(:options) { { page_size: 10, page_cursor: 'NQ', filter_case_sensitive: true } }
+
+      it 'adds the options to the query string' do
+        expect(translation_memory_segments.to_s)
+          .to eq("GET /v3/translation_memories/#{id}/segments" \
+                 '?page_size=10&page_cursor=NQ&filter_case_sensitive=true')
+      end
+    end
+
+    context 'when the text filter contains characters that must be escaped' do
+      let(:options) { { filter_text: 'a b+c' } }
+
+      # A space must be percent-encoded in a URI query string; `+` only means a space in a form
+      # body, and a literal `+` has to survive as %2B.
+      it 'percent-encodes the spaces instead of writing them as a plus' do
+        expect(translation_memory_segments.to_s)
+          .to eq("GET /v3/translation_memories/#{id}/segments?filter_text=a%20b%2Bc")
+      end
+    end
+  end
+end

data/spec/requests/translation_memory/upload_file_spec.rb

@@ -0,0 +1,55 @@
+# 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::TranslationMemory::UploadFile do
+  subject(:upload_file) { described_class.new(api, upload_url, file_content) }
+
+  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(:upload_url) { 'https://storage.example.com/upload/tm?signature=abc' }
+  let(:file_content) { '<tmx version="1.4"/>' }
+
+  describe '#initialize' do
+    context 'when building a request' do
+      it 'creates a request object' do
+        expect(upload_file).to be_a(described_class)
+        expect(upload_file.content_type).to eq(described_class::DEFAULT_CONTENT_TYPE)
+      end
+    end
+
+    context 'when no upload URL is given' do
+      let(:upload_url) { '' }
+
+      it 'raises an error' do
+        expect { upload_file }.to raise_error(DeepL::Exceptions::Error, /must not be empty/)
+      end
+    end
+  end
+
+  describe '#to_s' do
+    context 'when building a request' do
+      it 'puts to the pre-signed storage URL' do
+        expect(upload_file.to_s).to eq('PUT /upload/tm?signature=abc')
+      end
+    end
+  end
+
+  describe '#details' do
+    context 'when building a request' do
+      # The upload URL points outside of the DeepL API, so the auth key must not be sent there.
+      it 'does not send the DeepL authorization header' do
+        expect(upload_file.details).not_to include('Authorization')
+        expect(upload_file.details).to include('User-Agent')
+      end
+    end
+  end
+end

data/spec/resources/translation_memory_export_spec.rb

@@ -0,0 +1,38 @@
+# 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::Resources::TranslationMemoryExport do
+  subject(:translation_memory_export) { described_class.new(response, false, nil, nil) }
+
+  let(:response) do
+    {
+      'job_id' => '5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d',
+      'parameters' => { 'translation_memory_id' => 'a74d88fb-ed2a-4943-a664-a4512398b994' }
+    }
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(translation_memory_export).to be_a(described_class)
+    end
+
+    it 'assigns the attributes of a newly created export' do
+      expect(translation_memory_export.job_id).to eq('5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+      expect(translation_memory_export.translation_memory_id)
+        .to eq('a74d88fb-ed2a-4943-a664-a4512398b994')
+      expect(translation_memory_export.reused_existing?).to be(false)
+    end
+
+    context 'when the API reused a previously completed export' do
+      subject(:translation_memory_export) { described_class.new(response, true, nil, nil) }
+
+      it 'reports the export as reused' do
+        expect(translation_memory_export.reused_existing?).to be(true)
+      end
+    end
+  end
+end

data/spec/resources/translation_memory_import_spec.rb

@@ -0,0 +1,30 @@
+# 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::Resources::TranslationMemoryImport do
+  subject(:translation_memory_import) do
+    described_class.new({
+                          'job_id' => '5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d',
+                          'upload_url' => 'https://storage.example.com/upload',
+                          'expires_at' => '2026-01-01T00:00:00Z'
+                        }, nil, nil)
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(translation_memory_import).to be_a(described_class)
+    end
+
+    it 'assigns the attributes' do
+      expect(translation_memory_import.job_id).to eq('5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+      expect(translation_memory_import.upload_url).to eq('https://storage.example.com/upload')
+      expect(translation_memory_import.expires_at).to eq(Time.parse('2026-01-01T00:00:00Z'))
+      expect(translation_memory_import.to_s)
+        .to eq('TranslationMemoryImport: ID: 5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+    end
+  end
+end

data/spec/resources/translation_memory_job_spec.rb

@@ -0,0 +1,109 @@
+# 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::Resources::TranslationMemoryJob do
+  subject(:job) { described_class.new(response, nil, nil) }
+
+  let(:response) do
+    {
+      'job_id' => '5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d',
+      'product' => 'translation_memory',
+      'operation' => 'import',
+      'creation_time' => '2026-01-01T00:00:00Z',
+      'updated_time' => '2026-01-02T00:00:00Z',
+      'source_file' => { 'content_type' => 'application/xml', 'content_length' => 128 },
+      'parameters' => { 'display_name' => 'Legal' },
+      'results' => [
+        { 'status' => 'completed', 'translation_memory_id' => 'tm-1',
+          'skipped_segment_count' => 2 }
+      ]
+    }
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(job).to be_a(described_class)
+    end
+
+    it 'assigns the job level attributes' do
+      expect(job.job_id).to eq('5b1a0a52-1f3b-4b7f-9f6b-9d4d3f5b6c7d')
+      expect(job.product).to eq('translation_memory')
+      expect(job.operation).to eq('import')
+      expect(job.creation_time).to eq(Time.parse('2026-01-01T00:00:00Z'))
+      expect(job.updated_time).to eq(Time.parse('2026-01-02T00:00:00Z'))
+      expect(job.display_name).to eq('Legal')
+      expect(job.source_content_type).to eq('application/xml')
+      expect(job.source_content_length).to eq(128)
+    end
+
+    it 'maps the single result and delegates the status helpers to it' do
+      expect(job.result).to be_a(DeepL::Resources::TranslationMemoryJobResult)
+      expect(job.status).to eq('completed')
+      expect(job.finished?).to be(true)
+      expect(job.awaiting_input?).to be(false)
+      expect(job.error?).to be(false)
+      expect(job.result.translation_memory_id).to eq('tm-1')
+      expect(job.result.skipped_segment_count).to eq(2)
+    end
+  end
+
+  context 'when the job is awaiting its file upload' do
+    let(:response) do
+      { 'job_id' => 'job-1', 'operation' => 'import',
+        'results' => [{ 'status' => 'awaiting_input',
+                        'status_metadata' => { 'required_action' => 'Waiting for upload' } }] }
+    end
+
+    it 'exposes the required action and does not report the job as finished' do
+      expect(job.awaiting_input?).to be(true)
+      expect(job.finished?).to be(false)
+      expect(job.result.required_action).to eq('Waiting for upload')
+    end
+  end
+
+  context 'when the export job completed' do
+    let(:response) do
+      { 'job_id' => 'job-2', 'operation' => 'export',
+        'parameters' => { 'translation_memory_id' => 'tm-1' },
+        'results' => [{ 'status' => 'completed', 'download_url' => 'https://example.com/tmx',
+                        'expires_at' => '2026-01-03T00:00:00Z' }] }
+    end
+
+    it 'exposes the download URL and its expiry' do
+      expect(job.translation_memory_id).to eq('tm-1')
+      expect(job.result.download_url).to eq('https://example.com/tmx')
+      expect(job.result.expires_at).to eq(Time.parse('2026-01-03T00:00:00Z'))
+      expect(job.to_s).to eq('TranslationMemoryJob: export - ID: job-2 - Status: completed')
+    end
+  end
+
+  context 'when the job failed' do
+    let(:response) do
+      { 'job_id' => 'job-3', 'operation' => 'import',
+        'results' => [{ 'status' => 'failed', 'error' => { 'message' => 'Invalid TMX' } }] }
+    end
+
+    it 'reports the error and treats the job as finished' do
+      expect(job.error?).to be(true)
+      expect(job.finished?).to be(true)
+      expect(job.error_message).to eq('Invalid TMX')
+    end
+  end
+
+  context 'when the API returned no result' do
+    let(:response) { { 'job_id' => 'job-4', 'operation' => 'import' } }
+
+    it 'reports neither a status nor an error' do
+      expect(job.result).to be_nil
+      expect(job.status).to be_nil
+      expect(job.finished?).to be(false)
+      expect(job.awaiting_input?).to be(false)
+      expect(job.error?).to be(false)
+      expect(job.error_message).to be_nil
+    end
+  end
+end

data/spec/resources/translation_memory_segments_spec.rb

@@ -0,0 +1,78 @@
+# 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::Resources::TranslationMemorySegments do
+  subject(:segments_page) { described_class.new(response, nil, nil) }
+
+  let(:response) do
+    {
+      'segments' => [
+        {
+          'source_segment_id' => 'tm-1-source-0',
+          'source_text' => 'Quelltext Nummer 0',
+          'creation_time' => '2026-01-01T00:00:00Z',
+          'updated_time' => '2026-01-02T00:00:00Z',
+          'last_used_time' => '2026-01-03T00:00:00Z',
+          'targets' => [
+            {
+              'target_segment_id' => 'tm-1-target-en-0',
+              'target_language' => 'en',
+              'target_text' => 'Source text number 0',
+              'creation_time' => '2026-01-01T00:00:00Z',
+              'updated_time' => '2026-01-02T00:00:00Z',
+              'last_used_time' => '2026-01-03T00:00:00Z'
+            }
+          ]
+        }
+      ],
+      'segment_count' => 12,
+      'next_page_cursor' => 'NQ'
+    }
+  end
+
+  describe '#initialize' do
+    it 'creates a resource' do
+      expect(segments_page).to be_a(described_class)
+    end
+
+    it 'assigns the page level attributes' do
+      expect(segments_page.segment_count).to eq(12)
+      expect(segments_page.next_page_cursor).to eq('NQ')
+      expect(segments_page.next_page?).to be(true)
+      expect(segments_page.to_s).to eq('1 of 12 segment(s)')
+    end
+
+    it 'maps the segments into resources' do
+      segment = segments_page.segments.first
+      expect(segment).to be_a(DeepL::Resources::TranslationMemorySegment)
+      expect(segment.source_segment_id).to eq('tm-1-source-0')
+      expect(segment.source_text).to eq('Quelltext Nummer 0')
+      expect(segment.creation_time).to eq(Time.parse('2026-01-01T00:00:00Z'))
+      expect(segment.updated_time).to eq(Time.parse('2026-01-02T00:00:00Z'))
+      expect(segment.last_used_time).to eq(Time.parse('2026-01-03T00:00:00Z'))
+    end
+
+    it 'maps the target segments into resources' do
+      target = segments_page.segments.first.targets.first
+      expect(target).to be_a(DeepL::Resources::TranslationMemoryTargetSegment)
+      expect(target.target_segment_id).to eq('tm-1-target-en-0')
+      expect(target.target_language).to eq('en')
+      expect(target.target_text).to eq('Source text number 0')
+      expect(target.to_s).to eq('en: Source text number 0')
+    end
+  end
+
+  context 'when the response is the last page' do
+    let(:response) { { 'segments' => [], 'segment_count' => 12 } }
+
+    it 'reports no further page' do
+      expect(segments_page.segments).to eq([])
+      expect(segments_page.next_page_cursor).to be_nil
+      expect(segments_page.next_page?).to be(false)
+    end
+  end
+end

data/spec/resources/translation_memory_spec.rb

@@ -12,7 +12,9 @@ describe DeepL::Resources::TranslationMemory do
                           'name' => 'Legal',
                           'source_language' => 'en',
                           'target_languages' => %w[es de],
-                          'segment_count' => 3542
+                          'segment_count' => 3542,
+                          'creation_time' => '2026-01-01T00:00:00Z',
+                          'updated_time' => '2026-01-02T00:00:00Z'
                         }, nil, nil)
   end
 
@@ -29,6 +31,21 @@ describe DeepL::Resources::TranslationMemory do
         expect(translation_memory.source_language).to eq('en')
         expect(translation_memory.target_languages).to eq(%w[es de])
         expect(translation_memory.segment_count).to eq(3542)
+        expect(translation_memory.creation_time).to eq(Time.parse('2026-01-01T00:00:00Z'))
+        expect(translation_memory.updated_time).to eq(Time.parse('2026-01-02T00:00:00Z'))
+      end
+    end
+
+    context 'when the optional timestamps are missing' do
+      subject(:translation_memory) do
+        described_class.new({ 'translation_memory_id' => 'tm-1', 'name' => 'Legal' }, nil, nil)
+      end
+
+      it 'leaves the timestamps nil and defaults the collections' do
+        expect(translation_memory.creation_time).to be_nil
+        expect(translation_memory.updated_time).to be_nil
+        expect(translation_memory.target_languages).to eq([])
+        expect(translation_memory.segment_count).to eq(0)
       end
     end
   end

data/spec/support/managed_glossary.rb

@@ -4,6 +4,11 @@
 # frozen_string_literal: true
 
 module ManagedGlossary
+  # Bounded retry budget for tolerating a freshly-created glossary that is not
+  # yet resolvable on the real API (eventual consistency): up to ~10 seconds.
+  GLOSSARY_RETRY_ATTEMPTS = 20
+  GLOSSARY_RETRY_DELAY = 0.5
+
   def with_managed_glossary(name:, source_lang:, target_lang:, entries:, options: {})
     glossary = DeepL.glossaries.create(name, source_lang, target_lang, entries, options)
     yield glossary
@@ -14,4 +19,47 @@ module ManagedGlossary
       nil
     end
   end
+
+  # A just-created glossary is not always immediately resolvable by id on the
+  # real API (eventual consistency). Poll #find until each glossary is
+  # retrievable so subsequent calls (e.g. translate with glossary_ids) do not
+  # fail with a transient "Glossary <uuid> not found" error.
+  #
+  # Note: no keyword arguments here — Ruby 2.7 would fold a trailing options
+  # hash from callers into keywords, breaking positional-hash APIs.
+  def wait_until_glossaries_ready(*glossaries)
+    glossaries.each do |glossary|
+      remaining = GLOSSARY_RETRY_ATTEMPTS
+      begin
+        DeepL.glossaries.find(glossary.id)
+      rescue DeepL::Exceptions::RequestError
+        raise if (remaining -= 1) <= 0
+
+        sleep(GLOSSARY_RETRY_DELAY)
+        retry
+      end
+    end
+  end
+
+  # Translate with a bounded retry that tolerates a transient
+  # "Glossary <uuid> not found" error caused by eventual consistency on a
+  # freshly created glossary. Depending on timing the real API returns this as
+  # either a 400 or a 404, so match on the message rather than the status.
+  # Any other error is re-raised immediately.
+  #
+  # `options` is an explicit positional hash (matching DeepL.translate) rather
+  # than keyword arguments, so passing `{ glossary_ids: [...] }` works on Ruby
+  # 2.7 as well as 3.x.
+  def translate_retrying_missing_glossary(text, source_lang, target_lang, options = {})
+    remaining = GLOSSARY_RETRY_ATTEMPTS
+    begin
+      DeepL.translate(text, source_lang, target_lang, options)
+    rescue DeepL::Exceptions::RequestError => e
+      raise unless e.to_s.match?(/glossary .* not found/i)
+      raise if (remaining -= 1) <= 0
+
+      sleep(GLOSSARY_RETRY_DELAY)
+      retry
+    end
+  end
 end

data/spec/support/managed_translation_memory.rb

@@ -4,4 +4,52 @@
 # frozen_string_literal: true
 
 module ManagedTranslationMemory
+  # A minimal, valid TMX document to import in the translation memory specs.
+  EXAMPLE_TMX = <<~TMX
+    <?xml version="1.0" encoding="UTF-8"?>
+    <tmx version="1.4">
+      <header creationtool="deepl-rb-spec" srclang="de" segtype="sentence"
+              adminlang="en" datatype="plaintext" o-tmf="TMX"/>
+      <body>
+        <tu>
+          <tuv xml:lang="de"><seg>Quelltext Nummer 0</seg></tuv>
+          <tuv xml:lang="en"><seg>Source text number 0</seg></tuv>
+        </tu>
+      </body>
+    </tmx>
+  TMX
+
+  # Imports the TMX file at +input_file_path+ and yields the finished import job, deleting the
+  # resulting translation memory afterwards.
+  def with_managed_translation_memory(input_file_path, display_name: nil)
+    job = DeepL.translation_memories.import_from_filepath(input_file_path,
+                                                          display_name: display_name)
+    yield job
+  ensure
+    begin
+      DeepL.translation_memories.destroy(job.result.translation_memory_id) if job
+    rescue StandardError
+      nil
+    end
+  end
+
+  # Creates an import job for the TMX file at +input_file_path+ through +translation_memories+
+  # and uploads the file, then returns the created import. The mock server keeps the job in the
+  # `awaiting_input` status for +processing_polls+ status queries before completing it, standing
+  # in for the live API detecting the upload asynchronously.
+  def create_uploaded_import(translation_memories, input_file_path, processing_polls:)
+    file_content = File.binread(input_file_path)
+    created = translation_memories.create_import(
+      File.basename(input_file_path), file_content.bytesize,
+      additional_headers: tm_job_processing_polls_header(processing_polls)
+    )
+    translation_memories.upload_file(created, file_content)
+    created
+  end
+
+  # Writes the example TMX document to +path+ and returns the path.
+  def write_example_tmx(path)
+    File.write(path, EXAMPLE_TMX)
+    path
+  end
 end