deepl-rb 3.9.0 → 3.10.0

data/spec/offline/translate_text_spec.rb

@@ -0,0 +1,286 @@
+# 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_relative 'offline_helper'
+
+describe 'DeepL.translate' do
+  let(:translation_reply) { reply(translations: [{ text: 'Hallo' }]) }
+
+  # Every translate request asks for the billed characters.
+  def expect_body(body)
+    stub_request(:post, url('/v2/translate'))
+      .with(body: { show_billed_characters: true }.merge(body), headers: json_headers)
+      .to_return(translation_reply)
+  end
+
+  it 'sends no source language for auto-detection' do
+    expect_body(text: ['Hello'], target_lang: 'DE')
+    DeepL.translate('Hello', nil, 'DE')
+  end
+
+  it 'always sends show_billed_characters' do
+    stub_request(:post, url('/v2/translate'))
+      .with(body: { text: ['Hello'], source_lang: 'EN', target_lang: 'DE',
+                    show_billed_characters: true })
+      .to_return(translation_reply)
+
+    DeepL.translate('Hello', 'EN', 'DE')
+  end
+
+  it 'sends no options set to nil' do
+    expect_body(text: ['Hello'], target_lang: 'DE')
+    DeepL.translate('Hello', nil, 'DE', formality: nil, 'context' => nil, glossary: nil,
+                                        translation_memory: nil,
+                                        translation_memory_threshold: nil)
+  end
+
+  it 'sends the source language and several texts' do
+    stub_request(:post, url('/v2/translate'))
+      .with(body: { text: %w[Hello Bye], source_lang: 'EN', target_lang: 'DE',
+                    show_billed_characters: true })
+      .to_return(reply(translations: [{ text: 'Hallo' }, { text: 'Tschüss' }]))
+
+    expect(DeepL.translate(%w[Hello Bye], 'EN', 'DE').map(&:class))
+      .to eq([DeepL::Resources::Text] * 2)
+  end
+
+  it 'sends the additional headers' do
+    stub_request(:post, url('/v2/translate'))
+      .with(headers: json_headers.merge('X-DeepL-Reporting-Tag' => 'tag'))
+      .to_return(translation_reply)
+
+    DeepL.translate('Hello', 'EN', 'DE', {}, { 'X-DeepL-Reporting-Tag' => 'tag' })
+  end
+
+  it 'sends options given with string keys' do
+    expect_body(text: ['Hello'], source_lang: 'EN', target_lang: 'DE', split_sentences: '1',
+                formality: 'less')
+    DeepL.translate('Hello', 'EN', 'DE', 'formality' => 'less', 'split_sentences' => true)
+  end
+
+  describe 'options passed through unchanged' do
+    {
+      formality: 'prefer_more',
+      tag_handling: 'xml',
+      tag_handling_version: 'v2',
+      context: 'A greeting',
+      model_type: 'latency_optimized',
+      glossary_id: 'g-1',
+      show_billed_characters: true
+    }.each do |option, value|
+      it "sends #{option}" do
+        expect_body({ text: ['Hello'], source_lang: 'EN', target_lang: 'DE', option => value })
+        DeepL.translate('Hello', 'EN', 'DE', option => value)
+      end
+    end
+  end
+
+  describe 'option conversions' do
+    { true => '1', false => '0', 'nonewlines' => 'nonewlines' }.each do |value, sent|
+      it "sends split_sentences #{value.inspect} as #{sent.inspect}" do
+        expect_body(text: ['a'], target_lang: 'DE', split_sentences: sent)
+        DeepL.translate('a', nil, 'DE', split_sentences: value)
+      end
+    end
+
+    it 'converts split_sentences false given with a string key' do
+      expect_body(text: ['a'], target_lang: 'DE', split_sentences: '0')
+      DeepL.translate('a', nil, 'DE', 'split_sentences' => false)
+    end
+
+    { '1' => true, '0' => false, true => true }.each do |value, sent|
+      %i[preserve_formatting outline_detection].each do |option|
+        it "sends #{option} #{value.inspect} as #{sent.inspect}" do
+          expect_body({ text: ['a'], target_lang: 'DE', option => sent })
+          DeepL.translate('a', nil, 'DE', option => value)
+        end
+      end
+    end
+
+    it 'sends a custom_instructions string as one instruction' do
+      expect_body(text: ['a'], target_lang: 'DE', custom_instructions: ['Be formal, and short'])
+      DeepL.translate('a', nil, 'DE', custom_instructions: 'Be formal, and short')
+    end
+
+    it 'sends a custom_instructions array unchanged' do
+      expect_body(text: ['a'], target_lang: 'DE', custom_instructions: %w[x y])
+      DeepL.translate('a', nil, 'DE', custom_instructions: %w[x y])
+    end
+
+    %i[splitting_tags non_splitting_tags ignore_tags].each do |option|
+      it "sends a comma separated #{option} string as an array" do
+        expect_body({ text: ['a'], target_lang: 'DE', option => %w[x y] })
+        DeepL.translate('a', nil, 'DE', option => 'x,y')
+      end
+
+      it "sends a #{option} array unchanged" do
+        expect_body({ text: ['a'], target_lang: 'DE', option => %w[x y] })
+        DeepL.translate('a', nil, 'DE', option => %w[x y])
+      end
+    end
+  end
+
+  describe 'style rules and translation memories' do
+    let(:base) { { text: ['a'], source_lang: 'EN', target_lang: 'DE' } }
+
+    it 'sends a style rule ID as style_id' do
+      expect_body(base.merge(style_id: 's-1'))
+      DeepL.translate('a', 'EN', 'DE', style_rule: 's-1')
+    end
+
+    it 'sends the ID of a style rule object as style_id' do
+      expect_body(base.merge(style_id: 's-2'))
+      rule = DeepL::Resources::StyleRule.new({ 'style_id' => 's-2' }, nil, nil)
+      DeepL.translate('a', 'EN', 'DE', style_rule: rule)
+    end
+
+    it 'sends no style_id when the style rule is nil' do
+      expect_body(base)
+      DeepL.translate('a', 'EN', 'DE', style_rule: nil)
+    end
+
+    it 'sends a style profile ID as style_profile_id' do
+      expect_body(base.merge(style_profile_id: 'sp-1'))
+      DeepL.translate('a', 'EN', 'DE', style_profile: 'sp-1')
+    end
+
+    it 'sends the ID of a style profile object as style_profile_id' do
+      expect_body(base.merge(style_profile_id: 'sp-2'))
+      profile = DeepL::Resources::StyleProfile.new({ 'style_profile_id' => 'sp-2' }, nil, nil)
+      DeepL.translate('a', 'EN', 'DE', style_profile: profile)
+    end
+
+    it 'sends no style_profile_id when the option is not set' do
+      expect_body(base)
+      DeepL.translate('a', 'EN', 'DE')
+    end
+
+    it 'sends no style_profile_id when the option is nil' do
+      expect_body(base)
+      DeepL.translate('a', 'EN', 'DE', style_profile: nil)
+    end
+
+    it 'sends a translation memory ID with its threshold' do
+      expect_body(base.merge(translation_memory_id: 'tm-1', translation_memory_threshold: 80))
+      DeepL.translate('a', 'EN', 'DE', translation_memory: 'tm-1',
+                                       translation_memory_threshold: 80)
+    end
+
+    it 'sends the ID of a translation memory object' do
+      memory = DeepL::Resources::TranslationMemory.new({ 'translation_memory_id' => 'tm-2' },
+                                                       nil, nil)
+      expect_body(base.merge(translation_memory_id: 'tm-2'))
+      DeepL.translate('a', 'EN', 'DE', translation_memory: memory)
+    end
+  end
+
+  describe 'glossary' do
+    let(:base) { { text: ['a'], source_lang: 'EN', target_lang: 'DE' } }
+
+    it 'sends a glossary ID as glossary_id' do
+      expect_body(base.merge(glossary_id: 'g-1'))
+      DeepL.translate('a', 'EN', 'DE', glossary: 'g-1')
+    end
+
+    it 'sends the ID of a glossary or multilingual glossary object as glossary_id' do
+      glossary = DeepL::Resources::Glossary.new({ 'glossary_id' => 'g-2' }, nil, nil)
+      multilingual = DeepL::Resources::MultilingualGlossary.new({ 'glossary_id' => 'g-3' }, nil,
+                                                                nil)
+      expect_body(base.merge(glossary_id: 'g-2'))
+      expect_body(base.merge(glossary_id: 'g-3'))
+
+      DeepL.translate('a', 'EN', 'DE', glossary: glossary)
+      DeepL.translate('a', 'EN', 'DE', 'glossary' => multilingual)
+    end
+
+    it 'raises ArgumentError together with glossary_id or glossary_ids' do
+      expect { DeepL.translate('a', 'EN', 'DE', glossary: 'g-1', glossary_id: 'g-2') }
+        .to raise_error(ArgumentError, /`glossary` option cannot be used together/)
+      expect { DeepL.translate('a', 'EN', 'DE', glossary: 'g-1', glossary_ids: ['g-2']) }
+        .to raise_error(ArgumentError, /together with the `glossary` option/)
+    end
+  end
+
+  describe 'result' do
+    def stub_translation(translation)
+      stub_request(:post, url('/v2/translate')).to_return(reply(translations: [translation]))
+    end
+
+    it 'parses billed_characters and tag_handling_version' do
+      stub_translation(text: 'Hallo', detected_source_language: 'EN', billed_characters: 5,
+                       tag_handling_version: 'v2')
+
+      result = DeepL.translate('Hello', nil, 'DE', tag_handling: 'xml')
+      expect([result.billed_characters, result.tag_handling_version]).to eq([5, 'v2'])
+    end
+
+    it 'leaves malformed or missing fields nil and keeps the other fields' do
+      stub_translation(text: 'Hallo', detected_source_language: 'EN', billed_characters: 'five',
+                       tag_handling_version: 2)
+
+      result = DeepL.translate('Hello', nil, 'DE')
+      expect([result.text, result.detected_source_language, result.billed_characters,
+              result.tag_handling_version]).to eq(['Hallo', 'EN', nil, nil])
+    end
+  end
+
+  describe 'glossary_ids' do
+    let(:base) { { text: ['a'], source_lang: 'EN', target_lang: 'DE' } }
+
+    it 'sends glossary IDs, glossary objects and multilingual glossary objects as IDs' do
+      glossary = DeepL::Resources::Glossary.new({ 'glossary_id' => 'g-2' }, nil, nil)
+      multilingual = DeepL::Resources::MultilingualGlossary.new({ 'glossary_id' => 'g-3' }, nil,
+                                                                nil)
+      expect_body(base.merge(glossary_ids: %w[g-1 g-2 g-3]))
+
+      DeepL.translate('a', 'EN', 'DE', glossary_ids: ['g-1', glossary, multilingual])
+    end
+
+    it 'sends glossary_ids without a source language' do
+      expect_body(text: ['a'], target_lang: 'DE', glossary_ids: ['g-1'])
+
+      DeepL.translate('a', nil, 'DE', glossary_ids: ['g-1'])
+    end
+
+    it 'raises ArgumentError together with glossary_id' do
+      expect { DeepL.translate('a', 'EN', 'DE', glossary_ids: ['g-1'], glossary_id: 'g-2') }
+        .to raise_error(ArgumentError, /cannot be used together/)
+    end
+
+    it 'raises ArgumentError for more than 5 glossaries' do
+      expect { DeepL.translate('a', 'EN', 'DE', glossary_ids: %w[1 2 3 4 5 6]) }
+        .to raise_error(ArgumentError, /maximum of 5/)
+    end
+  end
+
+  describe 'extra_body_parameters' do
+    it 'keeps the type of each value' do
+      extra = { flag: true, off: false, count: 42, label: 'x', list: [1, 'a'], nested: { a: 1 } }
+      expect_body({ text: ['a'], target_lang: 'DE' }.merge(extra))
+
+      DeepL.translate('a', nil, 'DE', extra_body_parameters: extra)
+    end
+
+    it 'adds new parameters and overrides built-in ones' do
+      expect_body(text: ['a'], target_lang: 'FR', beta_feature: 'on')
+      DeepL.translate('a', nil, 'DE', extra_body_parameters: { target_lang: 'FR',
+                                                               beta_feature: 'on' })
+    end
+
+    it 'overrides an option of the same name' do
+      expect_body(text: ['a'], target_lang: 'DE', formality: 'more')
+      DeepL.translate('a', nil, 'DE', formality: 'less',
+                                      extra_body_parameters: { formality: 'more' })
+    end
+
+    it 'replaces a built-in parameter given with a string key instead of sending it twice' do
+      stub_request(:post, url('/v2/translate'))
+        .with { |request| request.body.scan('"target_lang"').size == 1 }
+        .to_return(translation_reply)
+
+      DeepL.translate('a', nil, 'DE', extra_body_parameters: { 'target_lang' => 'FR' })
+    end
+  end
+end

data/spec/offline/translation_memories_client_spec.rb

@@ -0,0 +1,256 @@
+# 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_relative 'offline_helper'
+
+describe 'DeepL::Client translation memories' do
+  let(:client) { DeepL::Client.new('client-key', server_url: 'https://client.example.test') }
+  let(:upload_url) { 'https://storage.example.test/upload?sig=abc' }
+  let(:download_url) { 'https://storage.example.test/download?sig=def' }
+  let(:memory) do
+    DeepL::Resources::TranslationMemory.new({ 'translation_memory_id' => 'tm-1' }, nil, nil)
+  end
+  let(:memory_json) do
+    { translation_memory_id: 'tm-1', name: 'memory', source_language: 'de',
+      target_languages: ['en'], segment_count: 3 }
+  end
+
+  def url(path)
+    "https://client.example.test#{path}"
+  end
+
+  def json_headers
+    { 'Authorization' => 'DeepL-Auth-Key client-key', 'Content-Type' => 'application/json' }
+  end
+
+  def job_json(status, **result)
+    { job_id: 'j-1', product: 'translation_memory', operation: 'export',
+      results: [{ status: status }.merge(result)] }
+  end
+
+  def stub_job(*replies)
+    stub_request(:get, url('/v3/translation_memories/jobs/j-1')).with(headers: json_headers)
+                                                                .to_return(*replies)
+  end
+
+  describe '#list_translation_memories' do
+    it 'sends no query by default' do
+      stub_request(:get, url('/v3/translation_memories')).with(headers: json_headers)
+                                                         .to_return(reply(translation_memories:
+                                                                            [memory_json]))
+
+      expect(client.list_translation_memories.map(&:translation_memory_id)).to eq(['tm-1'])
+    end
+
+    it 'sends page and page_size in the query' do
+      stub_request(:get, url('/v3/translation_memories?page=1&page_size=5'))
+        .to_return(reply(translation_memories: []))
+
+      client.list_translation_memories(page: 1, page_size: 5)
+    end
+  end
+
+  describe 'per-memory operations' do
+    it 'sends get and delete for an ID or a TranslationMemory' do
+      stub_request(:get, url('/v3/translation_memories/tm-1')).with(headers: json_headers)
+                                                              .to_return(reply(memory_json))
+      stub_request(:delete, url('/v3/translation_memories/tm-1')).to_return(status: 204)
+
+      expect(client.get_translation_memory(memory).name).to eq('memory')
+      expect(client.delete_translation_memory('tm-1')).to be_nil
+    end
+
+    it 'sends the segment options in the query' do
+      query = 'page_size=5&page_cursor=c-1&filter_text=a%20b&filter_case_sensitive=false'
+      stub_request(:get, url("/v3/translation_memories/tm-1/segments?#{query}"))
+        .with(headers: json_headers).to_return(reply(segment_count: 1, segments: []))
+
+      page = client.list_translation_memory_segments(memory, page_size: 5, page_cursor: 'c-1',
+                                                             filter_text: 'a b',
+                                                             filter_case_sensitive: false)
+
+      expect(page.segment_count).to eq(1)
+    end
+  end
+
+  describe 'import' do
+    include_context 'with a temporary directory'
+
+    it 'sends the import job with the content type, display name and extra body parameters' do # rubocop:disable RSpec/ExampleLength
+      stub_request(:post, url('/v3/translation_memories/import'))
+        .with(body: { source_file: { file_name: 'a.tmx', content_length: 12,
+                                     content_type: 'text/xml' },
+                      parameters: { display_name: 'Legal' }, extra: true },
+              headers: json_headers)
+        .to_return(reply({ job_id: 'j-1', upload_url: upload_url }, 201))
+
+      created = client.create_translation_memory_import('a.tmx', 12, content_type: 'text/xml',
+                                                                     display_name: 'Legal',
+                                                                     extra_body_parameters:
+                                                                       { extra: true })
+
+      expect(created.upload_url).to eq(upload_url)
+    end
+
+    it 'uploads the file without credentials, by default as application/xml' do
+      no_authorization = ->(request) { !request.headers.key?('Authorization') }
+      stub_request(:put, upload_url)
+        .with(body: 'tmx', headers: { 'Content-Type' => 'application/xml' }, &no_authorization)
+        .to_return(status: 200)
+      stub_request(:put, upload_url).with(headers: { 'Content-Type' => 'text/xml' })
+                                    .to_return(status: 200)
+
+      expect(client.upload_translation_memory_file(upload_url, 'tmx')).to be_nil
+      client.upload_translation_memory_file(upload_url, 'tmx', content_type: 'text/xml')
+    end
+
+    it 'raises a plain Error with the status for a storage reply of 403' do
+      stub_request(:put, upload_url).to_return(status: 403, body: 'Request has expired')
+
+      expect { client.upload_translation_memory_file(upload_url, 'tmx') }.to(raise_error do |error|
+        expect([error.class, error.http_status_code, error.should_retry?])
+          .to eq([DeepL::Exceptions::Error, 403, false])
+      end)
+    end
+
+    it 'imports a file: creates the job, uploads with the content type and waits' do # rubocop:disable RSpec/ExampleLength
+      path = File.join(temp_dir, 'memory.tmx')
+      File.write(path, 'tmx')
+      stub_request(:post, url('/v3/translation_memories/import'))
+        .with(body: { source_file: { file_name: 'memory.tmx', content_length: 3,
+                                     content_type: 'text/xml' },
+                      parameters: { display_name: 'Legal' }, extra: 'x' })
+        .to_return(reply({ job_id: 'j-1', upload_url: upload_url }, 201))
+      stub_request(:put, upload_url).with(body: 'tmx', headers: { 'Content-Type' => 'text/xml' })
+                                    .to_return(status: 200)
+      stub_job(reply(job_json('completed', translation_memory_id: 'tm-2')))
+
+      job = client.import_translation_memory_from_filepath(
+        path, display_name: 'Legal', content_type: 'text/xml', timeout_s: 10,
+              extra_body_parameters: { extra: 'x' }
+      )
+
+      expect([job.done?, job.result.translation_memory_id]).to eq([true, 'tm-2'])
+    end
+
+    it 'raises ArgumentError for a missing import file without sending a request' do
+      expect { client.import_translation_memory_from_filepath(File.join(temp_dir, 'missing.tmx')) }
+        .to raise_error(ArgumentError, /No file found/)
+    end
+
+    it 'raises Error with the cause for an unreadable import file without sending a request' do
+      expect { client.import_translation_memory_from_filepath(temp_dir) }
+        .to raise_error(DeepL::Exceptions::Error, /Could not read/) { |error|
+          expect(error.cause).to be_a(Errno::EISDIR)
+        }
+    end
+  end
+
+  describe 'export' do
+    include_context 'with a temporary directory'
+
+    let(:output) { File.join(temp_dir, 'export.tmx') }
+
+    it 'creates the export, gets the job and downloads the file' do
+      stub_request(:post, url('/v3/translation_memories/tm-1/export'))
+        .with(body: '{}', headers: json_headers)
+        .to_return(reply({ job_id: 'j-1', parameters: { translation_memory_id: 'tm-1' } }, 202))
+      stub_job(reply(job_json('completed', download_url: download_url)))
+      stub_request(:get, download_url).to_return(status: 200, body: 'tmx')
+
+      export = client.create_translation_memory_export(memory)
+      job = client.get_translation_memory_job(export.job_id)
+
+      expect([export.translation_memory_id, export.reused_existing?]).to eq(['tm-1', false])
+      expect(client.download_translation_memory_export(job, output)).to be_nil
+      expect(File.read(output)).to eq('tmx')
+    end
+
+    it 'exports to a file: creates the export, waits and downloads' do
+      stub_request(:post, url('/v3/translation_memories/tm-1/export'))
+        .to_return(reply({ job_id: 'j-1' }, 200))
+      stub_job(reply(job_json('completed', download_url: download_url)))
+      stub_request(:get, download_url).to_return(status: 200, body: 'tmx')
+
+      job = client.export_translation_memory_to_filepath('tm-1', output, timeout_s: 10)
+
+      expect([job.status, File.read(output)]).to eq(%w[completed tmx])
+    end
+
+    it 'raises Error for a missing output directory before creating the export job' do
+      missing = File.join(temp_dir, 'missing', 'x.tmx')
+
+      expect { client.export_translation_memory_to_filepath('tm-1', missing) }
+        .to raise_error(DeepL::Exceptions::Error, /does not exist/)
+    end
+
+    it 'raises Error with the cause when the file cannot be written' do
+      stub_request(:get, download_url).to_return(status: 200, body: 'tmx')
+
+      expect do
+        client.download_translation_memory_export(download_url,
+                                                  File.join(temp_dir, 'missing', 'x.tmx'))
+      end.to raise_error(DeepL::Exceptions::Error, /Could not write/) { |error|
+        expect(error.cause).to be_a(Errno::ENOENT)
+      }
+    end
+  end
+
+  describe '#wait_until_translation_memory_job_done' do
+    it 'returns the completed job for an ID or a job' do
+      stub = stub_job(reply(job_json('completed')))
+      job = DeepL::Resources::TranslationMemoryJob.new({ 'job_id' => 'j-1' }, nil, nil)
+
+      expect(client.wait_until_translation_memory_job_done(job).status).to eq('completed')
+      expect(stub).to have_been_requested.once
+    end
+
+    it 'raises Error with the API message when the job failed' do
+      stub_job(reply(job_json('failed', error: { message: 'bad file' })))
+
+      expect { client.wait_until_translation_memory_job_done('j-1') }
+        .to raise_error(DeepL::Exceptions::Error, /bad file/)
+    end
+
+    it 'raises Error when timeout_s expires' do
+      stub_job(reply(job_json('processing')))
+
+      expect { client.wait_until_translation_memory_job_done('j-1', timeout_s: 0) }
+        .to raise_error(DeepL::Exceptions::Error, /timeout of 0s exceeded/)
+    end
+  end
+
+  describe 'storage connection' do
+    it 'uses the proxy of the client for the pre-signed URLs' do
+      client = DeepL::Client.new('client-key', server_url: 'https://client.example.test',
+                                               proxy: 'http://proxy.example.test:8080')
+      stub_request(:put, upload_url).to_return(status: 200)
+
+      expect(Net::HTTP).to receive(:new)
+        .with('storage.example.test', 443, 'proxy.example.test', 8080, nil, nil)
+        .and_call_original
+
+      client.upload_translation_memory_file(upload_url, 'tmx')
+    end
+
+    it 'applies the timeouts and SSL verification of the http_client_options' do # rubocop:disable RSpec/ExampleLength
+      options = DeepL::HTTPClientOptions.new({}, nil, enable_ssl_verification: false,
+                                                      read_timeout: 33)
+      client = DeepL::Client.new('client-key', server_url: 'https://client.example.test',
+                                               http_client_options: options)
+      connections = []
+      allow(Net::HTTP).to receive(:new).and_wrap_original do |original, *args|
+        original.call(*args).tap { |connection| connections << connection }
+      end
+      stub_request(:get, download_url).to_return(status: 200, body: 'tmx')
+
+      client.download_translation_memory_export(download_url, File::NULL)
+
+      expect(connections.last)
+        .to have_attributes(address: 'storage.example.test', read_timeout: 33,
+                            verify_mode: OpenSSL::SSL::VERIFY_NONE)
+    end
+  end
+end