deepl-rb 3.9.0 → 3.10.0

data/lib/deepl/translation_memory_api.rb

@@ -4,6 +4,7 @@
 # frozen_string_literal: true
 
 module DeepL
+  # @deprecated Use the translation memory methods of DeepL::Client instead.
   class TranslationMemoryApi # rubocop:disable Metrics/ClassLength
     # Time to wait between two status queries of an import or export job.
     JOB_POLLING_INTERVAL_SECONDS = 5
@@ -19,6 +20,8 @@ module DeepL
     # @param [Hash] options Additional options for the request. Supports `page` (page number for
     #                       pagination, 0-indexed) and `page_size` (number of items per page).
     # @return [Array<DeepL::Resources::TranslationMemory>] The translation memories of the page.
+    #
+    # @deprecated Use DeepL::Client#list_translation_memories instead.
 
     def list(options = {})
       DeepL::Requests::TranslationMemory::List.new(@api, options).request
@@ -31,6 +34,8 @@ module DeepL
     #                                                                         ID or object.
     # @param [Hash] options Additional options for the request.
     # @return [DeepL::Resources::TranslationMemory] The requested translation memory.
+    #
+    # @deprecated Use DeepL::Client#get_translation_memory instead.
 
     def find(translation_memory, options = {})
       DeepL::Requests::TranslationMemory::Find.new(
@@ -52,6 +57,8 @@ module DeepL
     #                       `filter_case_sensitive` (whether the filter is case-sensitive,
     #                       defaults to false).
     # @return [DeepL::Resources::TranslationMemorySegments] The requested page of segments.
+    #
+    # @deprecated Use DeepL::Client#list_translation_memory_segments instead.
 
     def segments(translation_memory, options = {})
       DeepL::Requests::TranslationMemory::Segments.new(
@@ -66,6 +73,8 @@ module DeepL
     #                                                                         ID or object.
     # @param [Hash] options Additional options for the request.
     # @return [String] The ID of the deleted translation memory.
+    #
+    # @deprecated Use DeepL::Client#delete_translation_memory instead.
 
     def destroy(translation_memory, options = {})
       DeepL::Requests::TranslationMemory::Destroy.new(
@@ -83,14 +92,19 @@ module DeepL
     # @param [String, nil] content_type MIME type of the file, defaults to "application/xml".
     # @param [String, nil] display_name Name of the resulting translation memory, defaults to the
     #                                   file name.
+    # @param [Hash, nil] extra_body_parameters Fields added to the request body last; they
+    #                                         replace fields of the same name.
     # @param [Hash] additional_headers Additional HTTP headers for the request.
     # @return [DeepL::Resources::TranslationMemoryImport] The job ID and the upload URL.
+    #
+    # @deprecated Use DeepL::Client#create_translation_memory_import instead.
 
     def create_import(file_name, content_length, content_type: nil, display_name: nil,
-                      additional_headers: {})
+                      extra_body_parameters: nil, additional_headers: {})
+      options = { content_type: content_type, display_name: display_name,
+                  extra_body_parameters: extra_body_parameters }.compact
       DeepL::Requests::TranslationMemory::CreateImport.new(
-        @api, file_name, content_length,
-        { content_type: content_type, display_name: display_name }.compact, additional_headers
+        @api, file_name, content_length, options, additional_headers
       ).request
     end
 
@@ -99,12 +113,18 @@ module DeepL
     # upload URL is a pre-signed storage URL outside of the DeepL API, so no authorization header
     # is sent with this request.
     #
+    # @raise [DeepL::Exceptions::RequestError] If the storage URL replies with a non-2xx status:
+    #                                          the API error class for that status, e.g.
+    #                                          `AuthorizationFailed` for 401 and 403.
+    #
     # @param [String, DeepL::Resources::TranslationMemoryImport] translation_memory_import Import
     #        returned by `create_import`, or its upload URL.
     # @param [String] file_content Content of the TMX file.
     # @param [String] content_type MIME type of the file. Must match the `content_type` declared
     #                              when the import job was created.
     # @return [nil]
+    #
+    # @deprecated Use DeepL::Client#upload_translation_memory_file instead.
 
     def upload_file(translation_memory_import, file_content,
                     content_type: Requests::TranslationMemory::UploadFile::DEFAULT_CONTENT_TYPE)
@@ -122,6 +142,8 @@ module DeepL
     # @param [Hash] options Additional options for the request.
     # @return [DeepL::Resources::TranslationMemoryExport] The job ID, and whether the API reused a
     #                                                     previously completed export.
+    #
+    # @deprecated Use DeepL::Client#create_translation_memory_export instead.
 
     def create_export(translation_memory, options = {})
       DeepL::Requests::TranslationMemory::CreateExport.new(
@@ -135,6 +157,8 @@ module DeepL
     # @param [String, DeepL::Resources::TranslationMemoryJob] job Job ID or object.
     # @param [Hash] options Additional options for the request.
     # @return [DeepL::Resources::TranslationMemoryJob] The current status of the job.
+    #
+    # @deprecated Use DeepL::Client#get_translation_memory_job instead.
 
     def find_job(job, options = {})
       DeepL::Requests::TranslationMemory::FindJob.new(@api, extract_job_id(job), options).request
@@ -154,19 +178,20 @@ module DeepL
     #
     # @param [String, DeepL::Resources::TranslationMemoryJob] job Job ID or object.
     # @param [Hash] options Additional options for the status queries.
-    # @param [Numeric, nil] timeout_s Maximum time in seconds to wait for the job to finish. Note
-    #                                 that this is not accurate to the second, the status is only
-    #                                 queried every five seconds.
+    # @param [Numeric, nil] timeout_s Maximum time in seconds to wait for the job to finish. The
+    #                                 status is queried every five seconds; the last wait is cut
+    #                                 so that the call never waits past `timeout_s`.
     # @return [DeepL::Resources::TranslationMemoryJob] The finished job.
+    #
+    # @deprecated Use DeepL::Client#wait_until_translation_memory_job_done instead.
 
     def wait_until_job_done(job, options = {}, timeout_s: nil)
+      deadline = timeout_s.nil? ? nil : monotonic_time + timeout_s
       job_status = find_job(job, options)
-      started_at = monotonic_time
       until job_status.finished?
-        raise_timeout_error(timeout_s) if timeout_exceeded?(started_at, timeout_s)
-
-        log_job_polling
-        sleep(JOB_POLLING_INTERVAL_SECONDS)
+        interval = polling_interval_until(deadline, timeout_s)
+        log_job_polling(interval)
+        sleep(interval)
         job_status = find_job(job, options)
       end
       raise_job_error(job_status) if job_status.error?
@@ -180,11 +205,17 @@ module DeepL
     #
     # @raise [DeepL::Exceptions::Error] If the job carries no download URL, for example because
     #                                   it has not completed yet.
+    # @raise [DeepL::Exceptions::RequestError] If the storage URL replies with a non-2xx status:
+    #                                          the API error class for that status, e.g.
+    #                                          `AuthorizationFailed` for 401 and 403.
+    # @raise [SystemCallError, IOError] If the file cannot be written.
     #
     # @param [DeepL::Resources::TranslationMemoryJob, String] job Completed export job carrying
     #        the download URL, or the download URL itself.
     # @param [String] output_path Path to the file to write to. Will be overwritten if the file
     #                             already exists.
+    #
+    # @deprecated Use DeepL::Client#download_translation_memory_export instead.
 
     def download_export(job, output_path)
       DeepL::Requests::TranslationMemory::DownloadExport.new(@api, extract_download_url(job),
@@ -195,7 +226,9 @@ module DeepL
     # Imports a TMX file as a new translation memory: creates the import job, uploads the file
     # and waits for the processing to finish.
     #
-    # @raise [DeepL::Exceptions::Error] If the import fails.
+    # @raise [DeepL::Exceptions::Error] If no file exists at `input_file_path` (before any request
+    #                                   is sent) or the import fails.
+    # @raise [SystemCallError, IOError] If the file cannot be read.
     #
     # @param [String] input_file_path Path to the TMX file to import.
     # @param [String, nil] display_name Name of the resulting translation memory, defaults to the
@@ -203,18 +236,23 @@ module DeepL
     # @param [Numeric, nil] timeout_s Maximum time in seconds to wait for the import to finish.
     #                                 Note that the API keeps reporting `awaiting_input` for a
     #                                 while after the upload, so allow for a generous timeout.
+    # @param [String, nil] content_type MIME type of the file, declared in the import job and sent
+    #                                   with the upload. Defaults to "application/xml".
+    # @param [Hash, nil] extra_body_parameters Fields added to the body of the import job request
+    #                                         last; they replace fields of the same name.
     # @return [DeepL::Resources::TranslationMemoryJob] The finished import job, its result carries
     #                                                  the ID of the new translation memory.
+    #
+    # @deprecated Use DeepL::Client#import_translation_memory_from_filepath instead.
 
-    def import_from_filepath(input_file_path, display_name: nil, timeout_s: nil)
-      unless File.exist?(input_file_path)
-        raise Exceptions::Error, "No file found at #{input_file_path}"
-      end
-
-      file_content = File.binread(input_file_path)
+    def import_from_filepath(input_file_path, display_name: nil, timeout_s: nil,
+                             content_type: nil, extra_body_parameters: nil)
+      check_input_file(input_file_path)
+      file_content = read_input_file(input_file_path)
       created = create_import(File.basename(input_file_path), file_content.bytesize,
-                              display_name: display_name)
-      upload_file(created, file_content)
+                              content_type: content_type, display_name: display_name,
+                              extra_body_parameters: extra_body_parameters)
+      upload_file(created, file_content, content_type: content_type)
       wait_until_job_done(created.job_id, timeout_s: timeout_s)
     end
 
@@ -222,7 +260,10 @@ module DeepL
     # Exports a translation memory to a TMX file: creates the export job, waits for it to finish
     # and writes the result to +output_path+.
     #
+    # @raise [Errno::ENOENT] If the directory of `output_path` does not exist, checked before the
+    #                        export job is created.
     # @raise [DeepL::Exceptions::Error] If the export fails.
+    # @raise [SystemCallError, IOError] If the file cannot be written.
     #
     # @param [String, DeepL::Resources::TranslationMemory] translation_memory Translation memory
     #                                                                         ID or object.
@@ -230,8 +271,11 @@ module DeepL
     #                             already exists.
     # @param [Numeric, nil] timeout_s Maximum time in seconds to wait for the export to finish.
     # @return [DeepL::Resources::TranslationMemoryJob] The finished export job.
+    #
+    # @deprecated Use DeepL::Client#export_translation_memory_to_filepath instead.
 
     def export_to_filepath(translation_memory, output_path, timeout_s: nil)
+      check_output_directory(output_path)
       created = create_export(translation_memory)
       job = wait_until_job_done(created.job_id, timeout_s: timeout_s)
       download_export(job, output_path)
@@ -282,17 +326,53 @@ module DeepL
       value.nil? || value.empty?
     end
 
-    def log_job_polling
+    # Until the next major version, the module-level API raises the error classes of v3.9.0 for
+    # local file failures; DeepL::Client raises ArgumentError and wrapped errors.
+    def check_input_file(input_file_path)
+      return if File.exist?(input_file_path)
+
+      message = "No file found at #{input_file_path}"
+      raise ArgumentError, message if @api.client?
+
+      raise Exceptions::Error, message
+    end
+
+    def read_input_file(input_file_path)
+      File.binread(input_file_path)
+    rescue SystemCallError, IOError => e
+      raise e unless @api.client?
+
+      raise Exceptions::Error, "Could not read #{input_file_path}: #{e.message}"
+    end
+
+    def check_output_directory(output_path)
+      directory = File.dirname(output_path)
+      return if File.directory?(directory)
+
+      message = "Output directory #{directory} does not exist"
+      raise Exceptions::Error, message if @api.client?
+
+      raise Errno::ENOENT, message
+    end
+
+    def log_job_polling(interval)
       @api.configuration.logger&.info('Rechecking translation memory job status after sleeping ' \
-                                      "for #{JOB_POLLING_INTERVAL_SECONDS} seconds.")
+                                      "for #{format('%.2f', interval)} seconds.")
     end
 
     def monotonic_time
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
-    def timeout_exceeded?(started_at, timeout_s)
-      !timeout_s.nil? && (monotonic_time - started_at) > timeout_s
+    # The polling interval, cut to the time left until +deadline+ so that a wait never runs
+    # past +timeout_s+.
+    def polling_interval_until(deadline, timeout_s)
+      return JOB_POLLING_INTERVAL_SECONDS if deadline.nil?
+
+      remaining = deadline - monotonic_time
+      raise_timeout_error(timeout_s) if remaining <= 0
+
+      [JOB_POLLING_INTERVAL_SECONDS, remaining].min
     end
 
     def raise_timeout_error(timeout_s)

data/lib/deepl/utils/client_builder.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.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Utils
+    # Builds the API connection of a DeepL::Client or DeepL::AdminClient from its constructor
+    # options. Nothing is read from the environment or from module state.
+    # @api private
+    module ClientBuilder
+      extend self
+
+      def build_api(key, key_name:, server_url:, default_server_url:, headers:, max_retries:,
+                    timeout:, proxy:, send_platform_info:, app_info:, http_client_options:, logger:) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/ParameterLists
+        key = key.to_s.strip
+        raise ArgumentError, "#{key_name} must not be empty" if key.empty?
+
+        headers = (headers || {}).to_h
+        app_info = AppInfo.from(app_info)
+        configuration = Configuration.new(
+          { auth_key: key, host: server_url || default_server_url,
+            max_network_retries: max_retries, timeout: timeout, logger: logger,
+            headers: headers.reject { |name, _| user_agent_header?(name) },
+            user_agent: headers.find { |name, _| user_agent_header?(name) }&.last },
+          app_info&.app_name, app_info&.app_version, send_platform_info
+        )
+        API.new(configuration, merge_proxy(http_client_options, proxy), client: true)
+      end
+
+      private
+
+      def user_agent_header?(name)
+        name.to_s.casecmp?('user-agent')
+      end
+
+      def merge_proxy(options, proxy) # rubocop:disable Metrics/MethodLength
+        return options if proxy.nil?
+        if options && !(options.proxy.nil? || options.proxy.empty?)
+          raise ArgumentError,
+                'Set the proxy either with proxy: or in http_client_options:, not both'
+        end
+        return HTTPClientOptions.new(proxy) if options.nil?
+
+        HTTPClientOptions.new(proxy, options.cert_path,
+                              enable_ssl_verification: options.enable_ssl_verification,
+                              open_timeout: options.open_timeout,
+                              read_timeout: options.read_timeout,
+                              write_timeout: options.write_timeout,
+                              ssl_timeout: options.ssl_timeout)
+      end
+    end
+  end
+end

data/lib/deepl/utils/document_poller.rb

@@ -0,0 +1,70 @@
+# 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 Utils
+    # @api private
+    # Polls the status of a document translation every 5 seconds.
+    module DocumentPoller
+      INTERVAL_S = 5
+
+      extend self
+
+      # Polls until the translation is done and returns that status. Raises
+      # DeepL::Exceptions::Error with the API's message when the translation fails, and when
+      # +timeout_s+ is set and expires. An unknown status keeps polling.
+      def wait_until_done(api, handle, timeout_s: nil)
+        deadline = timeout_s.nil? ? nil : monotonic_now + timeout_s
+        loop do
+          status = get_status(api, handle)
+          return status if status.done?
+
+          raise_if_failed(status)
+
+          sleep(interval_until(deadline, timeout_s))
+        end
+      end
+
+      # Polls until the translation is done or failed and returns that status, or the last status
+      # after +max_queries+ + 1 queries if +max_queries+ is set.
+      def wait_until_finished(api, handle, max_queries: nil)
+        num_queries = 0
+        loop do
+          sleep(INTERVAL_S) if num_queries.positive?
+          num_queries += 1
+          status = get_status(api, handle)
+          return status if status.finished? || (!max_queries.nil? && num_queries > max_queries)
+        end
+      end
+
+      private
+
+      def raise_if_failed(status)
+        return unless status.error?
+
+        raise Exceptions::Error, "Document translation failed: #{status.error_message}"
+      end
+
+      def get_status(api, handle)
+        Requests::Document::GetStatus.new(api, handle.document_id, handle.document_key).request
+      end
+
+      def interval_until(deadline, timeout_s)
+        return INTERVAL_S if deadline.nil?
+
+        remaining = deadline - monotonic_now
+        if remaining <= 0
+          raise Exceptions::Error, "Document translation did not finish within #{timeout_s} seconds"
+        end
+
+        [INTERVAL_S, remaining].min
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/deepl/utils/exception_builder.rb

@@ -21,13 +21,14 @@ module DeepL
         end
       end
 
-      def initialize(response)
+      def initialize(response, request = nil)
         @response = response
+        @request = request
       end
 
       def build
         error_class = self.class.error_class_from_response_code(response.code.to_i)
-        error_class.new(response)
+        error_class.new(response, request)
       end
     end
   end

data/lib/deepl/utils/http_client_builder.rb

@@ -0,0 +1,79 @@
+# 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 Utils
+    module HTTPClientBuilder
+      extend self
+
+      ##
+      # Builds an unstarted Net::HTTP client for +host+ configured with +options+. Net::HTTP does
+      # not retry on its own (+max_retries+ 0): only the library's retries apply.
+      #
+      # @param [String] host Base URL of the API.
+      # @param [DeepL::HTTPClientOptions] options Proxy, SSL and timeout options.
+      # @return [Net::HTTP]
+      def build(host, options) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        uri = URI(host)
+        http = Net::HTTP.new(uri.host, uri.port, *proxy_arguments(options.proxy))
+        http.use_ssl = uri.scheme == 'https'
+        disable_lenient_defaults(http)
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE unless options.enable_ssl_verification
+        http.ca_file = options.cert_path if options.cert_path
+        http.open_timeout = options.open_timeout unless options.open_timeout.nil?
+        http.read_timeout = options.read_timeout unless options.read_timeout.nil?
+        http.write_timeout = options.write_timeout unless options.write_timeout.nil?
+        http.ssl_timeout = options.ssl_timeout unless options.ssl_timeout.nil?
+        http
+      end
+
+      ##
+      # Net::HTTP would re-send idempotent requests once on its own, outside max_retries, and would
+      # return a body shorter than its Content-Length as complete (+ignore_eof+, net-http 0.3+).
+      def disable_lenient_defaults(http)
+        http.max_retries = 0
+        http.ignore_eof = false if http.respond_to?(:ignore_eof=)
+        http
+      end
+
+      private
+
+      # The proxy is either a URL string, e.g. +http://user:pass@proxy.example:8080+, or a hash
+      # with +proxy_addr+ and +proxy_port+. Returns the proxy arguments of +Net::HTTP.new+.
+      def proxy_arguments(proxy)
+        if proxy.is_a?(String) && !proxy.empty?
+          proxy_uri = parse_proxy_url(proxy)
+
+          return [proxy_uri.host, proxy_uri.port, decode(proxy_uri.user),
+                  decode(proxy_uri.password)]
+        end
+        unless proxy.is_a?(Hash) && proxy.key?('proxy_addr') && proxy.key?('proxy_port')
+          return [nil,
+                  nil]
+        end
+
+        [proxy['proxy_addr'], proxy['proxy_port']]
+      end
+
+      # Error messages show the URL without its user info; the URI error, which repeats the URL,
+      # is not kept as cause.
+      def parse_proxy_url(proxy)
+        proxy_uri = begin
+          URI(proxy)
+        rescue URI::InvalidURIError
+          nil
+        end
+        return proxy_uri unless proxy_uri&.host.nil?
+
+        raise ArgumentError, "Invalid proxy URL: #{HTTPClientOptions.redact_proxy(proxy)}",
+              cause: nil
+      end
+
+      def decode(value)
+        value && URI::DEFAULT_PARSER.unescape(value)
+      end
+    end
+  end
+end

data/lib/deepl/utils/number_parser.rb

@@ -0,0 +1,34 @@
+# 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 Utils
+    ##
+    # Reads numbers from API responses without failing on unexpected values.
+    module NumberParser
+      extend self
+
+      # @return [Integer] The value if it is an Integer, otherwise 0.
+      def count(value)
+        value.is_a?(Integer) ? value : 0
+      end
+
+      # @return [Float] The value as a Float if it is numeric, otherwise 0.0.
+      def minutes(value)
+        value.is_a?(Numeric) ? value.to_f : 0.0
+      end
+
+      # @return [Float, nil] The value as a Float if it is numeric, otherwise nil.
+      def optional_minutes(value)
+        value.is_a?(Numeric) ? value.to_f : nil
+      end
+
+      # @return [Integer, nil] The value if it is an Integer, otherwise nil.
+      def optional_count(value)
+        value.is_a?(Integer) ? value : nil
+      end
+    end
+  end
+end

data/lib/deepl/utils/term_validator.rb

@@ -0,0 +1,33 @@
+# 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 Utils
+    module TermValidator
+      extend self
+
+      # C0 and C1 control characters plus the Unicode line and paragraph separators.
+      INVALID_CHARACTERS = /[\u0000-\u001F\u0080-\u009F

]/.freeze
+
+      ##
+      # Strips surrounding whitespace from a single glossary or spoken term, then checks it
+      # before it is serialized into a request.
+      #
+      # @param [String] term The term to check.
+      # @return [String] The stripped term, which is what the request sends.
+      # @raise [DeepL::Exceptions::ValidationError] If the stripped term is empty or contains a
+      #   control character.
+      def validate!(term)
+        term = term.to_s.strip
+        raise Exceptions::ValidationError, 'Term must not be empty' if term.empty?
+        if INVALID_CHARACTERS.match?(term)
+          raise Exceptions::ValidationError, "Term #{term.inspect} contains an invalid character"
+        end
+
+        term
+      end
+    end
+  end
+end

data/lib/deepl/utils/time_parser.rb

@@ -21,6 +21,20 @@ module DeepL
 
         Time.parse(time_string)
       end
+
+      ##
+      # Like +parse_optional_time+, but treats timestamps without a zone offset as UTC.
+      #
+      # @param [Object] time_string Timestamp in ISO 8601 format, or nil.
+      # @return [Time, nil] The parsed time, or nil if no valid timestamp was given.
+      def parse_optional_utc_time(time_string)
+        return nil unless time_string.is_a?(String) && !time_string.empty?
+        return Time.parse(time_string) if Date._parse(time_string).key?(:offset)
+
+        Time.parse("#{time_string}Z")
+      rescue ArgumentError
+        nil
+      end
     end
   end
 end