deepl-rb 3.9.0 → 3.10.0

data/lib/deepl/requests/correct.rb

@@ -0,0 +1,57 @@
+# 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
+
+module DeepL
+  module Requests
+    class Correct < Base
+      include WriteImprovements
+
+      attr_reader :text, :target_lang
+
+      def initialize(api, text, target_lang = nil, options = {}, additional_headers = {})
+        super(api, options, additional_headers)
+        @text = text
+        @target_lang = target_lang
+        validate_text!
+      end
+
+      def request
+        payload = { text: text_arrayified }
+        payload[:target_lang] = target_lang unless target_lang.nil?
+        build_texts(*execute_request_with_retries(post_request(payload)))
+      end
+
+      def details
+        "HTTP Headers: #{loggable_headers}\nPayload #{{ text: text, target_lang: target_lang }}"
+      end
+
+      def to_s
+        "POST #{uri.request_uri}"
+      end
+
+      private
+
+      def text_arrayified
+        text.is_a?(Array) ? text : [text]
+      end
+
+      def validate_text!
+        return unless text_arrayified.empty? || text_arrayified.any? { |t| t.to_s.empty? }
+
+        raise ArgumentError,
+              '`text` must be a non-empty string or a non-empty array of non-empty strings'
+      end
+
+      def build_texts(request, response)
+        texts = build_improvements(text_arrayified.size, request, response)
+        text.is_a?(Array) ? texts : texts.first
+      end
+
+      def path
+        'write/correct'
+      end
+    end
+  end
+end

data/lib/deepl/requests/document/download.rb

@@ -22,7 +22,7 @@ module DeepL
         end
 
         def details
-          "HTTP Headers: #{headers}\nPayload #{{ document_key: document_key }}"
+          "HTTP Headers: #{loggable_headers}\nPayload #{{ document_key: document_key }}"
         end
 
         def to_s
@@ -31,12 +31,20 @@ module DeepL
 
         private
 
+        # Binary mode: text mode would convert newlines on Windows and transcode the bytes when
+        # Encoding.default_internal is set.
         def extract_file(_request, response)
-          File.write(@output_file, response.body)
+          File.binwrite(@output_file, response.body)
+        end
+
+        def validate_response!(response, request = nil)
+          raise Exceptions::DocumentNotReadyError.new(response, request) if response.code == '503'
+
+          super
         end
 
         def path
-          "document/#{document_id}/result"
+          "document/#{escape_path_segment(document_id)}/result"
         end
       end
     end

data/lib/deepl/requests/document/get_status.rb

@@ -21,7 +21,7 @@ module DeepL
         end
 
         def details
-          "HTTP Headers: #{headers}\nPayload #{{ document_key: document_key }}"
+          "HTTP Headers: #{loggable_headers}\nPayload #{{ document_key: document_key }}"
         end
 
         def to_s
@@ -36,7 +36,7 @@ module DeepL
         end
 
         def path
-          "document/#{document_id}"
+          "document/#{escape_path_segment(document_id)}"
         end
       end
     end

data/lib/deepl/requests/document/upload.rb

@@ -9,11 +9,12 @@ module DeepL
       class Upload < Base
         attr_reader :input_file_path, :source_lang, :target_lang, :filename
 
-        SUPPORTED_OPTIONS = %w[formality glossary_id output_format].freeze
+        SUPPORTED_OPTIONS = %w[formality glossary_id output_format enable_watermark].freeze
 
         def initialize(api, input_file_path, source_lang, target_lang, filename = nil, # rubocop:disable Metrics/ParameterLists
                        options = {}, additional_headers = {})
-          super(api, options, additional_headers)
+          # Options set to nil are unset and not sent.
+          super(api, options.compact, additional_headers)
           @input_file_path = input_file_path
           @source_lang = source_lang
           @target_lang = target_lang
@@ -30,7 +31,7 @@ module DeepL
         end
 
         def details
-          "HTTP Headers: #{headers}\nPayload #{[
+          "HTTP Headers: #{loggable_headers}\nPayload #{[
             ['file', "File at #{input_file_path} opened in binary mode"],
             ['source_lang', source_lang], ['target_lang', target_lang], ['filename', filename]
           ]}"
@@ -43,10 +44,9 @@ module DeepL
         private
 
         def build_base_form_data(input_file)
-          form_data = [
-            ['file', input_file], ['source_lang', source_lang],
-            ['target_lang', target_lang]
-          ]
+          form_data = [['file', input_file]]
+          form_data.push(['source_lang', source_lang]) unless source_lang.nil?
+          form_data.push(['target_lang', target_lang])
           filename_param = filename || File.basename(input_file_path)
           form_data.push(['filename', filename_param]) unless filename_param.nil?
           add_extra_options_to_form(form_data)
@@ -56,7 +56,9 @@ module DeepL
         def add_extra_options_to_form(form_data)
           add_supported_options_to_form(form_data)
           add_glossary_ids_to_form(form_data)
+          add_glossary_to_form(form_data)
           add_style_rule_to_form(form_data)
+          add_style_profile_to_form(form_data)
           add_translation_memory_to_form(form_data)
           add_translation_memory_threshold_to_form(form_data)
         end
@@ -66,10 +68,22 @@ module DeepL
         # comma-separated `glossary_ids` field. Requires `source_lang`, cannot be combined with
         # the singular `glossary_id` option, and allows at most 5 IDs.
         def add_glossary_ids_to_form(form_data)
-          glossary_ids = build_glossary_ids_param(source_lang)
+          glossary_ids = build_glossary_ids_param
+          # Text translation detects the source language for glossaries; documents do not.
+          if !glossary_ids.nil? && source_lang.nil?
+            raise ArgumentError, 'The `glossary_ids` option requires `source_lang` to be set'
+          end
+
           form_data.push(['glossary_ids', glossary_ids.join(',')]) unless glossary_ids.nil?
         end
 
+        # Resolves the `glossary` option (an ID string, a `DeepL::Resources::Glossary` or a
+        # `DeepL::Resources::MultilingualGlossary`) and appends it as a `glossary_id` field.
+        def add_glossary_to_form(form_data)
+          glossary_id = build_glossary_param
+          form_data.push(['glossary_id', glossary_id]) unless glossary_id.nil?
+        end
+
         # Serializes the `style_rule` option and appends it to the form data as a `style_id`
         # field. Mirrors text translation: accepts either a style rule ID string or a
         # `DeepL::Resources::StyleRule` object.
@@ -77,10 +91,24 @@ module DeepL
           return unless option?(:style_rule)
 
           rule = delete_option(:style_rule)
+          return if rule.nil?
+
           style_id = rule.is_a?(DeepL::Resources::StyleRule) ? rule.style_id : rule
           form_data.push(['style_id', style_id.to_s])
         end
 
+        # Serializes the `style_profile` option (a style profile ID string or a
+        # `DeepL::Resources::StyleProfile` object) as a `style_profile_id` field.
+        def add_style_profile_to_form(form_data)
+          return unless option?(:style_profile)
+
+          profile = delete_option(:style_profile)
+          return if profile.nil?
+
+          profile = profile.style_profile_id if profile.is_a?(DeepL::Resources::StyleProfile)
+          form_data.push(['style_profile_id', profile.to_s])
+        end
+
         # Serializes the `translation_memory` option and appends it to the form data as a
         # `translation_memory_id` field. Mirrors text translation: the `translation_memory`
         # option accepts either a translation memory ID string or a
@@ -89,6 +117,8 @@ module DeepL
           return unless option?(:translation_memory)
 
           tm = delete_option(:translation_memory)
+          return if tm.nil?
+
           tm_id = tm.is_a?(DeepL::Resources::TranslationMemory) ? tm.translation_memory_id : tm
           form_data.push(['translation_memory_id', tm_id.to_s])
         end
@@ -99,20 +129,23 @@ module DeepL
           return unless option?(:translation_memory_threshold)
 
           threshold = delete_option(:translation_memory_threshold)
+          return if threshold.nil?
+
           form_data.push(['translation_memory_threshold', threshold.to_s])
         end
 
         def add_supported_options_to_form(form_data)
           SUPPORTED_OPTIONS.each do |option_name|
             option_value = option(option_name)
-            form_data.push([option_name, option_value]) unless option_value.nil?
+            form_data.push([option_name, option_value.to_s]) unless option_value.nil?
           end
         end
 
         def build_doc_handle(request, response)
           parsed_response = JSON.parse(response.body)
           Resources::DocumentHandle.new(parsed_response['document_id'],
-                                        parsed_response['document_key'], request, response)
+                                        parsed_response['document_key'], request, response,
+                                        api: api)
         end
 
         def path

data/lib/deepl/requests/glossary/create.rb

@@ -27,7 +27,7 @@ module DeepL
         end
 
         def details
-          "HTTP Headers: #{headers}\nPayload #{{
+          "HTTP Headers: #{loggable_headers}\nPayload #{{
             name: name, source_lang: source_lang, target_lang: target_lang, entries: entries_to_tsv,
             entries_format: entries_format
           }}"
@@ -42,7 +42,11 @@ module DeepL
         def entries_to_tsv
           return entries if entries.is_a?(String)
 
-          entries.reduce('') { |tsv, entry| "#{tsv}#{entry.first}\t#{entry.last}\n" }
+          entries.reduce('') do |tsv, entry|
+            source = Utils::TermValidator.validate!(entry.first)
+            target = Utils::TermValidator.validate!(entry.last)
+            "#{tsv}#{source}\t#{target}\n"
+          end
         end
 
         def build_glossary(request, response)

data/lib/deepl/requests/glossary/language_pairs.rb

@@ -23,14 +23,30 @@ module DeepL
 
         def build_language_pair_list(request, response)
           data = JSON.parse(response.body)
-          data['supported_languages'].map do |language_pair|
-            Resources::LanguagePair.new(language_pair['source_lang'], language_pair['target_lang'],
-                                        request, response)
+          sources = langs_where(data, 'usable_as_source')
+          targets = langs_where(data, 'usable_as_target')
+
+          sources.product(targets).each_with_object([]) do |(source, target), pairs|
+            next if source == target
+
+            pairs << Resources::LanguagePair.new(source, target, request, response)
           end
         end
 
+        def langs_where(data, usable_key)
+          data.select { |language| language[usable_key] }.map { |language| language['lang'] }
+        end
+
+        def uri
+          @uri ||= URI("#{host}/v3/#{path}?resource=glossary")
+        end
+
+        def get_request # rubocop:disable Naming/AccessorMethodName
+          Net::HTTP::Get.new(uri.request_uri, add_json_content_type(headers))
+        end
+
         def path
-          'glossary-language-pairs'
+          'languages'
         end
       end
     end

data/lib/deepl/requests/language_resources.rb

@@ -0,0 +1,41 @@
+# 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
+
+module DeepL
+  module Requests
+    class LanguageResources < Base
+      def initialize(api, options = {})
+        super
+      end
+
+      def request
+        build_language_resource_list(*execute_request_with_retries(get_request))
+      end
+
+      def to_s
+        "GET #{uri.request_uri}"
+      end
+
+      private
+
+      def build_language_resource_list(request, response)
+        data = JSON.parse(response.body)
+        data.map { |resource| Resources::LanguageResource.new(resource, request, response) }
+      end
+
+      def uri
+        @uri ||= URI("#{host}/v3/#{path}")
+      end
+
+      def get_request # rubocop:disable Naming/AccessorMethodName
+        Net::HTTP::Get.new(uri.request_uri, add_json_content_type(headers))
+      end
+
+      def path
+        'languages/resources'
+      end
+    end
+  end
+end

data/lib/deepl/requests/languages.rb

@@ -6,8 +6,15 @@
 module DeepL
   module Requests
     class Languages < Base
+      SUPPORTED_TYPES = %w[source target].freeze
+
       def initialize(api, options = {})
         super
+        @type = (delete_option(:type) || :source).to_s
+        return if SUPPORTED_TYPES.include?(@type)
+
+        raise Exceptions::ValidationError, "Unsupported `type` option: #{@type.inspect} " \
+                                           "(supported: #{SUPPORTED_TYPES.join(', ')})"
       end
 
       def request
@@ -20,15 +27,32 @@ module DeepL
 
       private
 
+      def target?
+        @type == 'target'
+      end
+
       def build_languages(request, response)
         data = JSON.parse(response.body)
-        data.map do |language|
-          Resources::Language.new(language['language'], language['name'],
-                                  language['supports_formality'],
-                                  request, response)
+        usable_key = target? ? 'usable_as_target' : 'usable_as_source'
+        data.select { |language| language[usable_key] }.map do |language|
+          build_language(language, request, response)
         end
       end
 
+      def build_language(language, request, response)
+        supports_formality = target? ? language.fetch('features', {}).to_h.key?('formality') : nil
+        Resources::Language.new(language['lang'].upcase, language['name'], supports_formality,
+                                request, response, client: api.client?)
+      end
+
+      def uri
+        @uri ||= URI("#{host}/v3/#{path}?resource=translate_text")
+      end
+
+      def get_request # rubocop:disable Naming/AccessorMethodName
+        Net::HTTP::Get.new(uri.request_uri, add_json_content_type(headers))
+      end
+
       def path
         'languages'
       end

data/lib/deepl/requests/languages_for_resource.rb

@@ -0,0 +1,54 @@
+# 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
+
+module DeepL
+  module Requests
+    class LanguagesForResource < Base
+      def initialize(api, resource, options = {})
+        super(api, options)
+        @resource = resource.to_s
+        raise ArgumentError, 'resource must not be empty' if @resource.empty?
+      end
+
+      def request
+        build_language_support_list(*execute_request_with_retries(get_request))
+      end
+
+      def to_s
+        "GET #{uri.request_uri}"
+      end
+
+      private
+
+      def build_language_support_list(request, response)
+        data = JSON.parse(response.body)
+        data.map { |language| Resources::LanguageSupport.new(language, request, response) }
+      end
+
+      def uri
+        @uri ||= begin
+          base_uri = URI("#{host}/v3/#{path}")
+          base_uri.query = build_query_string
+          base_uri
+        end
+      end
+
+      # include is sent as repeated include=<value> parameters
+      def build_query_string
+        params = [['resource', @resource]]
+        Array(option(:include)).each { |value| params << ['include', value.to_s] }
+        encode_query(params)
+      end
+
+      def get_request # rubocop:disable Naming/AccessorMethodName
+        Net::HTTP::Get.new(uri.request_uri, add_json_content_type(headers))
+      end
+
+      def path
+        'languages'
+      end
+    end
+  end
+end

data/lib/deepl/requests/multilingual_glossary/create.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
+
+module DeepL
+  module Requests
+    module MultilingualGlossary
+      class Create < Base
+        include Helpers
+
+        attr_reader :name, :dictionaries
+
+        def initialize(api, name, dictionaries, options = {})
+          super(api, options)
+          @name = name
+          @dictionaries = dictionaries.map { |dictionary| dictionary_payload(dictionary) }
+        end
+
+        def request
+          payload = { name: name, dictionaries: dictionaries }
+          build_glossary(*execute_request_with_retries(post_request(payload)))
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
+        end
+
+        private
+
+        def path
+          'glossaries'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/multilingual_glossary/destroy.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
+
+module DeepL
+  module Requests
+    module MultilingualGlossary
+      class Destroy < Base
+        include Helpers
+
+        attr_reader :id
+
+        def initialize(api, id, options = {})
+          super(api, options)
+          @id = glossary_id(id)
+        end
+
+        def request
+          execute_request_with_retries(delete_request)
+          nil
+        end
+
+        def to_s
+          "DELETE #{uri.request_uri}"
+        end
+
+        private
+
+        def path
+          glossary_path(id)
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/multilingual_glossary/destroy_dictionary.rb

@@ -0,0 +1,51 @@
+# 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
+
+module DeepL
+  module Requests
+    module MultilingualGlossary
+      class DestroyDictionary < Base
+        include Helpers
+
+        attr_reader :id, :source_lang, :target_lang
+
+        def initialize(api, id, source_lang, target_lang, options = {})
+          super(api, options)
+          @id = glossary_id(id)
+          @source_lang = source_lang
+          @target_lang = target_lang
+        end
+
+        def request
+          execute_request_with_retries(delete_request)
+          nil
+        end
+
+        def to_s
+          "DELETE #{uri.request_uri}"
+        end
+
+        private
+
+        def delete_request
+          http_headers = add_json_content_type(headers)
+          Net::HTTP::Delete.new(uri.request_uri, http_headers)
+        end
+
+        def uri
+          @uri ||= begin
+            base_uri = URI("#{host}/v3/#{path}")
+            base_uri.query = encode_query(source_lang: source_lang, target_lang: target_lang)
+            base_uri
+          end
+        end
+
+        def path
+          glossary_path(id, 'dictionaries')
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/multilingual_glossary/entries.rb

@@ -0,0 +1,66 @@
+# 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
+
+module DeepL
+  module Requests
+    module MultilingualGlossary
+      class Entries < Base
+        include Helpers
+
+        attr_reader :id, :source_lang, :target_lang
+
+        def initialize(api, id, source_lang, target_lang, options = {})
+          super(api, options)
+          @id = glossary_id(id)
+          @source_lang = source_lang
+          @target_lang = target_lang
+        end
+
+        def request
+          build_entries(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
+        end
+
+        private
+
+        def get_request # rubocop:disable Naming/AccessorMethodName
+          http_headers = add_json_content_type(headers)
+          Net::HTTP::Get.new(uri.request_uri, http_headers)
+        end
+
+        # The API wraps the dictionary in a list, which is empty if the glossary has no
+        # dictionary for the language pair.
+        def build_entries(request, response)
+          dictionary = (JSON.parse(response.body)['dictionaries'] || []).first
+          if dictionary.nil?
+            raise Exceptions::NotFound.new(
+              response, request,
+              "Glossary #{id} has no dictionary for #{source_lang} -> #{target_lang}"
+            )
+          end
+
+          Resources::MultilingualGlossaryDictionaryEntries.from_response(
+            dictionary, request, response
+          )
+        end
+
+        def uri
+          @uri ||= begin
+            base_uri = URI("#{host}/v3/#{path}")
+            base_uri.query = encode_query(source_lang: source_lang, target_lang: target_lang)
+            base_uri
+          end
+        end
+
+        def path
+          glossary_path(id, 'entries')
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/multilingual_glossary/find.rb

@@ -0,0 +1,35 @@
+# 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
+
+module DeepL
+  module Requests
+    module MultilingualGlossary
+      class Find < Base
+        include Helpers
+
+        attr_reader :id
+
+        def initialize(api, id, options = {})
+          super(api, options)
+          @id = glossary_id(id)
+        end
+
+        def request
+          build_glossary(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
+        end
+
+        private
+
+        def path
+          glossary_path(id)
+        end
+      end
+    end
+  end
+end