deepl-rb 3.9.0 → 3.10.0

data/spec/offline/multilingual_glossaries_spec.rb

@@ -0,0 +1,358 @@
+# 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 'multilingual glossaries' do
+  # The client has its own key and server, different from the module configuration, so a request
+  # that falls back to module state hits no stub.
+  describe 'DeepL::Client' do
+    let(:client) { DeepL::Client.new('client-key', server_url: 'https://client.example.test') }
+    let(:glossary_json) do
+      { glossary_id: 'g-1', name: 'terms', creation_time: '2026-10-23T17:15:53.434769Z',
+        dictionaries: [{ source_lang: 'en', target_lang: 'de', entry_count: 2 }] }
+    end
+    let(:dictionary_json) { { source_lang: 'en', target_lang: 'de', entry_count: 1 } }
+    let(:apple) do
+      DeepL::Resources::MultilingualGlossaryDictionaryEntries.new('EN', 'DE', [%w[Apple Apfel]])
+    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 auth_headers
+      { 'Authorization' => 'DeepL-Auth-Key client-key' }
+    end
+
+    def no_body
+      ->(body) { body.to_s.empty? }
+    end
+
+    def glossary
+      stub_request(:get, url('/v3/glossaries/g-1')).to_return(reply(glossary_json))
+      client.get_multilingual_glossary('g-1')
+    end
+
+    describe '#create_multilingual_glossary' do
+      it 'takes MultilingualGlossaryDictionaryEntries objects and sends them as TSV' do
+        stub_request(:post, url('/v3/glossaries')).with(
+          body: { name: 'terms', dictionaries: [{ source_lang: 'EN', target_lang: 'DE',
+                                                  entries: "Apple\tApfel", entries_format: 'tsv' }],
+                  beta: true },
+          headers: json_headers
+        ).to_return(reply(glossary_json, 201))
+
+        client.create_multilingual_glossary('terms', [apple], extra_body_parameters: { beta: true })
+      end
+
+      it 'trims the terms of MultilingualGlossaryDictionaryEntries given as a TSV string' do
+        dictionary = { source_lang: 'EN', target_lang: 'DE', entries: "Apple\tApfel",
+                       entries_format: 'tsv' }
+        stub_request(:post, url('/v3/glossaries'))
+          .with(body: { name: 'terms', dictionaries: [dictionary] })
+          .to_return(reply(glossary_json, 201))
+        entries_class = DeepL::Resources::MultilingualGlossaryDictionaryEntries
+        entries = entries_class.new('EN', 'DE', "Apple \tApfel\n")
+
+        client.create_multilingual_glossary('terms', [entries])
+      end
+
+      it 'accepts dictionaries with string keys and a string of entries' do
+        stub_request(:post, url('/v3/glossaries')).with(
+          body: { name: 'terms',
+                  dictionaries: [{ source_lang: 'EN', target_lang: 'FR', entries: "a\tb",
+                                   entries_format: 'tsv' }] }
+        ).to_return(reply(glossary_json, 201))
+
+        client.create_multilingual_glossary(
+          'terms', [{ 'source_lang' => 'EN', 'target_lang' => 'FR', 'entries' => "a\tb" }]
+        )
+      end
+
+      it 'trims the terms of a TSV string of entries and skips blank lines' do
+        stub_request(:post, url('/v3/glossaries')).with(
+          body: { name: 'terms',
+                  dictionaries: [{ source_lang: 'EN', target_lang: 'DE',
+                                   entries: "Apple\tApfel\nBanana\tBanane",
+                                   entries_format: 'tsv' }] }
+        ).to_return(reply(glossary_json, 201))
+
+        client.create_multilingual_glossary(
+          'terms', [{ source_lang: 'EN', target_lang: 'DE',
+                      entries: " Apple \t Apfel\r\n\n  Banana\tBanane \n" }]
+        )
+      end
+
+      [[%W[Apple\tPie Apfel]], [%W[Apple Apfel\nKuchen]], "Apple\tApfel\tKuchen", "Apple\n",
+       " \tApfel", "Apple\tAp\u0001fel", "Apple\tAp\u2028fel"].each do |entries|
+        it "raises ValidationError for #{entries.inspect} and sends no request" do
+          dictionaries = [{ source_lang: 'EN', target_lang: 'DE', entries: entries }]
+
+          expect { client.create_multilingual_glossary('terms', dictionaries) }
+            .to raise_error(DeepL::Exceptions::ValidationError)
+          expect(a_request(:any, /.*/)).not_to have_been_made
+        end
+      end
+
+      { 'a duplicate source term' => [%w[Apple Apfel], [' Apple', 'Apfel2']],
+        'a one-element pair' => [['Apple']] }.each do |label, pairs|
+        it "raises ValidationError for #{label} and sends no request" do
+          entries_class = DeepL::Resources::MultilingualGlossaryDictionaryEntries
+
+          expect do
+            client.create_multilingual_glossary('terms', [entries_class.new('EN', 'DE', pairs)])
+          end.to raise_error(DeepL::Exceptions::ValidationError, /Apple/)
+          expect(a_request(:any, /.*/)).not_to have_been_made
+        end
+      end
+
+      it 'parses the creation time as a UTC Time' do
+        stub_request(:post, url('/v3/glossaries')).to_return(reply(glossary_json, 201))
+
+        created = client.create_multilingual_glossary('terms', [])
+
+        expect(created.creation_time)
+          .to eq(Time.utc(2026, 10, 23, 17, 15, Rational(53_434_769, 1_000_000)))
+      end
+    end
+
+    describe '#create_multilingual_glossary_from_csv' do
+      it 'sends the CSV content of a string or an IO with the csv entries format' do
+        body = { name: 'terms', dictionaries: [{ source_lang: 'EN', target_lang: 'DE',
+                                                 entries: "a,b\n", entries_format: 'csv' }] }
+        stub_request(:post, url('/v3/glossaries')).with(body: body)
+                                                  .to_return(reply(glossary_json, 201))
+
+        client.create_multilingual_glossary_from_csv('terms', 'EN', 'DE', "a,b\n")
+        client.create_multilingual_glossary_from_csv('terms', 'EN', 'DE', StringIO.new("a,b\n"))
+      end
+    end
+
+    describe '#list_multilingual_glossaries and #get_multilingual_glossary' do
+      it 'send GET requests and take a glossary object' do
+        stub_request(:get, url('/v3/glossaries')).with(headers: auth_headers)
+                                                 .to_return(reply(glossaries: [glossary_json]))
+
+        expect(client.list_multilingual_glossaries.map(&:id)).to eq(['g-1'])
+        expect(client.get_multilingual_glossary(glossary).name).to eq('terms')
+      end
+    end
+
+    describe '#update_multilingual_glossary' do
+      it 'sends the name and the dictionaries' do
+        stub_request(:patch, url('/v3/glossaries/g-1')).with(
+          body: { name: 'new', dictionaries: [{ source_lang: 'EN', target_lang: 'FR',
+                                                entries: "a\tb", entries_format: 'tsv' }] },
+          headers: json_headers
+        ).to_return(reply(glossary_json))
+
+        client.update_multilingual_glossary(
+          'g-1', name: 'new', dictionaries: [{ source_lang: 'EN', target_lang: 'FR',
+                                               entries: [%w[a b]] }]
+        )
+      end
+
+      it 'sends an empty object when no argument is given' do
+        stub_request(:patch, url('/v3/glossaries/g-1')).with(body: '{}')
+                                                       .to_return(reply(glossary_json))
+
+        client.update_multilingual_glossary('g-1')
+      end
+    end
+
+    describe '#update_multilingual_glossary_name and #update_multilingual_glossary_dictionary' do
+      it 'send a PATCH with only the name or only the dictionary' do
+        stub_request(:patch, url('/v3/glossaries/g-1')).with(body: { name: 'new' })
+                                                       .to_return(reply(glossary_json))
+        stub_request(:patch, url('/v3/glossaries/g-1')).with(
+          body: { dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entries: "Apple\tApfel",
+                                   entries_format: 'tsv' }] }
+        ).to_return(reply(glossary_json))
+
+        client.update_multilingual_glossary_name(glossary, 'new')
+        client.update_multilingual_glossary_dictionary(glossary, apple)
+      end
+
+      it 'sends CSV content with the csv entries format' do
+        stub_request(:patch, url('/v3/glossaries/g-1')).with(
+          body: { dictionaries: [{ source_lang: 'EN', target_lang: 'DE', entries: "a,b\n",
+                                   entries_format: 'csv' }] }
+        ).to_return(reply(glossary_json))
+
+        client.update_multilingual_glossary_dictionary_from_csv('g-1', 'EN', 'DE', "a,b\n")
+      end
+    end
+
+    describe '#replace_multilingual_glossary_dictionary' do
+      it 'sends a PUT with one dictionary given as a hash' do
+        stub_request(:put, url('/v3/glossaries/g-1/dictionaries')).with(
+          body: { source_lang: 'EN', target_lang: 'DE', entries: "a\tb", entries_format: 'tsv' },
+          headers: json_headers
+        ).to_return(reply(dictionary_json))
+
+        replaced = client.replace_multilingual_glossary_dictionary(
+          'g-1', { source_lang: 'EN', target_lang: 'DE', entries: [%w[a b]] }
+        )
+
+        expect([replaced.source_lang, replaced.target_lang, replaced.entry_count])
+          .to eq(['en', 'de', 1])
+      end
+
+      it 'sends CSV content with the csv entries format' do
+        stub_request(:put, url('/v3/glossaries/g-1/dictionaries')).with(
+          body: { source_lang: 'EN', target_lang: 'DE', entries: "a,b\n", entries_format: 'csv' }
+        ).to_return(reply(dictionary_json))
+
+        client.replace_multilingual_glossary_dictionary_from_csv('g-1', 'EN', 'DE', "a,b\n")
+      end
+    end
+
+    describe 'entries_format with converted entries' do
+      operations = {
+        'create' => [:post, '/v3/glossaries', lambda { |client, dictionary|
+          client.create_multilingual_glossary('terms', [dictionary])
+        }, ->(sent) { { name: 'terms', dictionaries: [sent] } }],
+        'update' => [:patch, '/v3/glossaries/g-1', lambda { |client, dictionary|
+          client.update_multilingual_glossary('g-1', dictionaries: [dictionary])
+        }, ->(sent) { { dictionaries: [sent] } }],
+        'replace' => [:put, '/v3/glossaries/g-1/dictionaries', lambda { |client, dictionary|
+          client.replace_multilingual_glossary_dictionary('g-1', dictionary)
+        }, ->(sent) { sent }]
+      }
+
+      operations.each do |name, (method, path, call, body)|
+        { 'a hash' => { 'Hello' => 'Hallo' }, 'pairs' => [%w[Hello Hallo]] }.each do |kind, entries|
+          it "#{name} sends #{kind} given with entries_format csv as TSV" do
+            sent = { source_lang: 'en', target_lang: 'de', entries: "Hello\tHallo",
+                     entries_format: 'tsv' }
+            stub = stub_request(method, url(path)).with(body: body.call(sent))
+                                                  .to_return(reply(glossary_json))
+
+            call.call(client, { source_lang: 'en', target_lang: 'de', entries: entries,
+                                entries_format: 'csv' })
+
+            expect(stub).to have_been_requested
+          end
+        end
+
+        it "#{name} sends a CSV string given with entries_format csv unchanged" do
+          sent = { source_lang: 'en', target_lang: 'de', entries: "Hello,Hallo\n",
+                   entries_format: 'csv' }
+          stub = stub_request(method, url(path)).with(body: body.call(sent))
+                                                .to_return(reply(glossary_json))
+
+          call.call(client, sent)
+
+          expect(stub).to have_been_requested
+        end
+      end
+    end
+
+    describe '#get_multilingual_glossary_dictionary_entries' do
+      it 'encodes a space in a query value as %20' do
+        expect(Net::HTTP::Get).to receive(:new)
+          .with('/v3/glossaries/g-1/entries?source_lang=E%20N&target_lang=DE', anything)
+          .and_call_original
+        stub_request(:get, url('/v3/glossaries/g-1/entries?source_lang=E%20N&target_lang=DE'))
+          .to_return(reply(dictionaries: [{ source_lang: 'en', target_lang: 'de', entries: '',
+                                            entries_format: 'tsv' }]))
+
+        client.get_multilingual_glossary_dictionary_entries('g-1', 'E N', 'DE')
+      end
+
+      it 'returns the one dictionary with its entries as a hash' do
+        stub_request(:get, url('/v3/glossaries/g-1/entries?source_lang=EN&target_lang=DE'))
+          .with(headers: json_headers)
+          .to_return(reply(dictionaries: [{ source_lang: 'en', target_lang: 'de',
+                                            entries: "Apple\tApfel\nBanana\tBanane\n",
+                                            entries_format: 'tsv' }]))
+
+        result = client.get_multilingual_glossary_dictionary_entries('g-1', 'EN', 'DE')
+
+        expect([result.source_lang, result.target_lang, result.entries])
+          .to eq(['en', 'de', { 'Apple' => 'Apfel', 'Banana' => 'Banane' }])
+      end
+
+      it 'returns entries that update and replace send back as TSV' do # rubocop:disable RSpec/ExampleLength
+        stub_request(:get, url('/v3/glossaries/g-1/entries?source_lang=EN&target_lang=DE'))
+          .to_return(reply(dictionaries: [{ source_lang: 'en', target_lang: 'de',
+                                            entries: "Hello\tHallo", entries_format: 'tsv' }]))
+        dictionary = { source_lang: 'en', target_lang: 'de', entries: "Hello\tHallo",
+                       entries_format: 'tsv' }
+        stub_request(:patch, url('/v3/glossaries/g-1'))
+          .with(body: { dictionaries: [dictionary] }).to_return(reply(glossary_json))
+        stub_request(:put, url('/v3/glossaries/g-1/dictionaries'))
+          .with(body: dictionary).to_return(reply(dictionary_json))
+
+        entries = client.get_multilingual_glossary_dictionary_entries('g-1', 'EN', 'DE')
+        client.update_multilingual_glossary_dictionary('g-1', entries)
+        client.replace_multilingual_glossary_dictionary('g-1', entries)
+        expect(entries.entries).to eq('Hello' => 'Hallo')
+      end
+
+      it 'raises NotFound when the glossary has no dictionary for the language pair' do
+        stub_request(:get, url('/v3/glossaries/g-1/entries?source_lang=EN&target_lang=JA'))
+          .to_return(reply(dictionaries: []))
+
+        expect { client.get_multilingual_glossary_dictionary_entries('g-1', 'EN', 'JA') }
+          .to raise_error(DeepL::Exceptions::NotFound, /no dictionary for EN -> JA/)
+      end
+
+      it 'returns entries that can be sent to another glossary' do
+        stub_request(:get, url('/v3/glossaries/g-1/entries?source_lang=EN&target_lang=DE'))
+          .to_return(reply(dictionaries: [{ source_lang: 'en', target_lang: 'de',
+                                            entries: "a\tb", entries_format: 'tsv' }]))
+        stub_request(:post, url('/v3/glossaries')).with(
+          body: { name: 'copy', dictionaries: [{ source_lang: 'en', target_lang: 'de',
+                                                 entries: "a\tb", entries_format: 'tsv' }] }
+        ).to_return(reply(glossary_json, 201))
+
+        entries = client.get_multilingual_glossary_dictionary_entries('g-1', 'EN', 'DE')
+        client.create_multilingual_glossary('copy', [entries])
+      end
+    end
+
+    describe '#delete_multilingual_glossary_dictionary and #delete_multilingual_glossary' do
+      it 'send DELETE requests and return nil' do
+        stub_request(:delete, url('/v3/glossaries/g-1/dictionaries?source_lang=EN&target_lang=FR'))
+          .with(headers: json_headers, body: no_body).to_return(status: 204)
+        stub_request(:delete, url('/v3/glossaries/g-1')).with(headers: auth_headers)
+                                                        .to_return(status: 204)
+
+        expect(client.delete_multilingual_glossary_dictionary(glossary, 'EN', 'FR')).to be_nil
+        expect(client.delete_multilingual_glossary(glossary)).to be_nil
+      end
+    end
+
+    describe 'glossary IDs' do
+      before do
+        encoded = url('/v3/glossaries/a%20b%2Fc')
+        stub_request(:get, encoded).to_return(reply(glossary_json))
+        stub_request(:patch, encoded).to_return(reply(glossary_json))
+        stub_request(:delete, encoded).to_return(status: 204)
+        stub_request(:get, "#{encoded}/entries?source_lang=EN&target_lang=DE")
+          .to_return(reply(dictionaries: [{ source_lang: 'en', target_lang: 'de', entries: '' }]))
+        stub_request(:put, "#{encoded}/dictionaries").to_return(reply(dictionary_json))
+        stub_request(:delete, "#{encoded}/dictionaries?source_lang=EN&target_lang=DE")
+          .to_return(status: 204)
+      end
+
+      it 'are URL-encoded in every path' do
+        id = 'a b/c'
+        client.get_multilingual_glossary(id)
+        client.update_multilingual_glossary_name(id, 'x')
+        client.delete_multilingual_glossary(id)
+        client.get_multilingual_glossary_dictionary_entries(id, 'EN', 'DE')
+        client.replace_multilingual_glossary_dictionary(id, apple)
+        client.delete_multilingual_glossary_dictionary(id, 'EN', 'DE')
+      end
+    end
+  end
+end

data/spec/offline/offline_helper.rb

@@ -0,0 +1,71 @@
+# 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
+
+if defined?(RealApiHelper)
+  raise 'spec/offline and spec/real_api cannot run in one process: WebMock blocks the network'
+end
+
+require_relative '../spec_helper'
+require_relative '../fixtures'
+require 'webmock/rspec'
+
+# The offline suite never touches the network: every request is declared with WebMock and
+# asserted exactly.
+WebMock.disable_net_connect!
+
+module OfflineHelper
+  HOST = 'https://api.deepl.com'
+  AUTH_KEY = 'k'
+
+  def url(path)
+    "#{HOST}#{path}"
+  end
+
+  # Headers of a request with a JSON Content-Type.
+  def json_headers
+    { 'Authorization' => "DeepL-Auth-Key #{AUTH_KEY}", 'Content-Type' => 'application/json' }
+  end
+
+  # Headers of a request without a body.
+  def auth_headers
+    { 'Authorization' => "DeepL-Auth-Key #{AUTH_KEY}" }
+  end
+
+  # True for a request sent without a body and without a Content-Type, as GET and DELETE are.
+  def bodyless?(request)
+    request.body.to_s.empty? && !request.headers.key?('Content-Type')
+  end
+
+  def reply(body = {}, status = 200)
+    { status: status, body: body.is_a?(String) ? body : body.to_json }
+  end
+
+  def usage_reply
+    reply(character_count: 1, character_limit: 10)
+  end
+end
+
+RSpec.configure do |config|
+  config.include OfflineHelper
+  config.include Fixtures
+
+  config.before do
+    DeepL.configure do |c|
+      c.auth_key = OfflineHelper::AUTH_KEY
+      c.host = OfflineHelper::HOST
+      c.logger = nil
+      c.max_doc_status_queries = nil
+      c.headers = {}
+      # The default of 5 retries would sleep for about 16 seconds in every retry example.
+      c.max_network_retries = 2
+    end
+  end
+
+  # A declared request that the SDK never sent is a failure. webmock/rspec resets the stubs
+  # in an around hook, which runs after this one.
+  config.after do
+    expect(WebMock::StubRegistry.instance.request_stubs).to all(have_been_requested.at_least_once)
+  end
+end

data/spec/offline/rephrase_text_spec.rb

@@ -0,0 +1,73 @@
+# 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.rephrase' do
+  def stub_rephrase(body = nil)
+    request = stub_request(:post, url('/v2/write/rephrase'))
+    request = request.with(body: body, headers: json_headers) unless body.nil?
+    request
+  end
+
+  it 'sends only the text when no other argument is given' do
+    stub_rephrase(text: ['Hello']).to_return(reply(improvements: [{ text: 'Hi' }]))
+    DeepL.rephrase('Hello')
+  end
+
+  it 'sends the target language, writing style and tone' do
+    stub_rephrase(text: %w[a b], target_lang: 'en-GB', writing_style: 'business',
+                  tone: 'diplomatic')
+      .to_return(reply(improvements: [{ text: 'x' }, { text: 'y' }]))
+
+    DeepL.rephrase(%w[a b], 'en-GB', 'business', 'diplomatic')
+  end
+
+  it 'sends the additional headers' do
+    stub_request(:post, url('/v2/write/rephrase'))
+      .with(headers: { 'X-DeepL-Reporting-Tag' => 'tag' })
+      .to_return(reply(improvements: [{ text: 'Hi' }]))
+
+    DeepL.rephrase('Hello', nil, nil, nil, {}, { 'X-DeepL-Reporting-Tag' => 'tag' })
+  end
+
+  it 'overrides built-in parameters with extra_body_parameters' do
+    stub_rephrase(text: ['Hello'], target_lang: 'de', beta: true)
+      .to_return(reply(improvements: [{ text: 'Hallo' }]))
+
+    DeepL.rephrase('Hello', 'en', nil, nil,
+                   extra_body_parameters: { target_lang: 'de', beta: true })
+  end
+
+  it 'returns a text for a string' do
+    stub_rephrase.to_return(reply(improvements: [{ text: 'Hi' }]))
+
+    expect(DeepL.rephrase('Hello')).to be_a(DeepL::Resources::Text)
+  end
+
+  it 'parses the target language of each improvement' do
+    stub_rephrase.to_return(reply(improvements: [
+                                    { text: 'x', detected_source_language: 'en',
+                                      target_language: 'en-GB' }, { text: 'y', target_language: 1 }
+                                  ]))
+
+    expect(DeepL.rephrase(%w[a b]).map(&:target_language)).to eq(['en-GB', nil])
+  end
+
+  it 'returns an array of texts for an array' do
+    stub_rephrase.to_return(reply(improvements: [{ text: 'x' }, { text: 'y' }]))
+
+    expect(DeepL.rephrase(%w[a b]).map(&:class)).to eq([DeepL::Resources::Text] * 2)
+  end
+
+  [['Hello', []], [%w[a b], [{ text: 'x' }]]].each do |text, improvements|
+    it "raises DeepL::Exceptions::Error for #{improvements.size} improvements of #{text.inspect}" do
+      stub_rephrase.to_return(reply(improvements: improvements))
+
+      expect { DeepL.rephrase(text) }
+        .to raise_error(an_instance_of(DeepL::Exceptions::Error), /expected \d improvements/)
+    end
+  end
+end