deepl-rb 3.9.0 → 3.10.0

data/lib/deepl/configuration.rb

@@ -6,31 +6,69 @@
 module DeepL
   class Configuration
     ATTRIBUTES = %i[auth_key host logger max_doc_status_queries max_network_retries user_agent
-                    version].freeze
+                    version headers timeout].freeze
 
-    attr_accessor(*ATTRIBUTES)
+    # max_doc_status_queries= is defined below, with its deprecation warning.
+    attr_accessor(*(ATTRIBUTES - %i[max_doc_status_queries]))
+    attr_reader :max_doc_status_queries
 
     DEEPL_SERVER_URL = 'https://api.deepl.com'
     DEEPL_SERVER_URL_FREE = 'https://api-free.deepl.com'
-    private_constant :DEEPL_SERVER_URL, :DEEPL_SERVER_URL_FREE
+    # Net::HTTP's 60-second default, kept for the module-level API; 10 in the next major version.
+    DEFAULT_TIMEOUT = 60.0
+    private_constant :DEEPL_SERVER_URL, :DEEPL_SERVER_URL_FREE, :DEFAULT_TIMEOUT
 
     def initialize(data = {}, app_info_name = nil, app_info_version = nil, send_platform_info = true) # rubocop:disable all
       data.each { |key, value| send("#{key}=", value) }
       @auth_key ||= ENV.fetch('DEEPL_AUTH_KEY', nil)
       @host ||= ENV.fetch('DEEPL_SERVER_URL', nil)
-      @host ||= if self.class.free_account_auth_key?(@auth_key)
-                  DEEPL_SERVER_URL_FREE
-                else
-                  DEEPL_SERVER_URL
-                end
       @version ||= 'v2'
       @user_agent ||= construct_user_agent(send_platform_info, app_info_name, app_info_version)
       @max_network_retries ||= 5
       @logger ||= nil
+      @headers ||= {}
+      @timeout ||= DEFAULT_TIMEOUT
+    end
+
+    # The host is resolved when it is read, so that an auth key set after the configuration was
+    # created (e.g. in a +DeepL.configure+ block) still selects the Free API.
+    def host
+      return @host unless @host.nil?
+
+      self.class.free_account_auth_key?(auth_key) ? DEEPL_SERVER_URL_FREE : DEEPL_SERVER_URL
+    end
+
+    ##
+    # @deprecated Use the +timeout_s:+ of DeepL::Client#translate_document or
+    #   DeepL::Client#translate_document_wait_until_done instead.
+    def max_doc_status_queries=(value)
+      unless value.nil?
+        DeepL::Deprecation.warn_once_at_caller(
+          'DeepL::Configuration#max_doc_status_queries=',
+          '[DEPRECATION] DeepL::Configuration#max_doc_status_queries= is deprecated, use the ' \
+          'timeout_s: of DeepL::Client#translate_document instead.'
+        )
+      end
+      @max_doc_status_queries = value
+    end
+
+    ##
+    # @deprecated The API version is part of each endpoint; this setting will be removed in the
+    #   next major version.
+    def version=(value)
+      unless value.nil? || value == 'v2'
+        DeepL::Deprecation.warn_once('DeepL::Configuration#version=',
+                                     '[DEPRECATION] DeepL::Configuration#version= is deprecated ' \
+                                     'and will be removed in the next major version.')
+      end
+      @version = value
     end
 
     def validate!
-      raise Exceptions::Error, 'auth_key not provided' if auth_key.nil? || auth_key.empty?
+      return unless auth_key.nil? || auth_key.to_s.strip.empty?
+
+      raise Exceptions::Error,
+            'auth_key not provided'
     end
 
     def attributes
@@ -41,8 +79,16 @@ module DeepL
       attributes == other.attributes
     end
 
+    # Redacts the auth key, so that it never shows in the inspect output of objects holding the
+    # configuration.
+    def inspect
+      shown = attributes.merge(auth_key: auth_key.nil? ? nil : '[REDACTED]')
+      "#<#{self.class.name} #{shown.map { |name, value| "#{name}=#{value.inspect}" }.join(', ')}>"
+    end
+
+    # The key is trimmed like the one sent in the Authorization header.
     def self.free_account_auth_key?(key)
-      key&.end_with?(':fx')
+      key.to_s.strip.end_with?(':fx')
     end
 
     def construct_user_agent(send_platform_info, app_info_name, app_info_version)

data/lib/deepl/constants/admin_usage_group_by.rb

@@ -0,0 +1,13 @@
+# 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 Constants
+    class AdminUsageGroupBy < BaseConstant
+      KEY = 'key'
+      KEY_AND_DAY = 'key_and_day'
+    end
+  end
+end

data/lib/deepl/constants/custom_tag_usage_aggregate_by.rb

@@ -0,0 +1,13 @@
+# 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 Constants
+    class CustomTagUsageAggregateBy < BaseConstant
+      PERIOD = 'period'
+      DAY = 'day'
+    end
+  end
+end

data/lib/deepl/constants/document_status_code.rb

@@ -0,0 +1,17 @@
+# 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 Constants
+    # Values of +DeepL::Resources::DocumentTranslationStatus#status+. The status stays a plain
+    # string, so a value the API adds later is kept as it is.
+    class DocumentStatusCode < BaseConstant
+      QUEUED = 'queued'
+      TRANSLATING = 'translating'
+      DONE = 'done'
+      ERROR = 'error'
+    end
+  end
+end

data/lib/deepl/constants/language_include.rb

@@ -0,0 +1,17 @@
+# 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 Constants
+    # Values of the +include+ option of +DeepL::Client#get_languages_for_resource+. Other strings
+    # are accepted and sent unchanged.
+    class LanguageInclude < BaseConstant
+      # Also return beta languages and features.
+      BETA = 'beta'
+      # Also return features that rely on third-party providers.
+      EXTERNAL = 'external'
+    end
+  end
+end

data/lib/deepl/constants/language_resource_name.rb

@@ -0,0 +1,21 @@
+# 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 Constants
+    # Values of the +resource+ argument of +DeepL::Client#get_languages_for_resource+ and of
+    # +DeepL::Resources::LanguageResource#name+. Other strings are accepted and sent unchanged, so
+    # a resource the API adds later can be queried before it is listed here.
+    class LanguageResourceName < BaseConstant
+      TRANSLATE_TEXT = 'translate_text'
+      TRANSLATE_DOCUMENT = 'translate_document'
+      GLOSSARY = 'glossary'
+      VOICE = 'voice'
+      WRITE = 'write'
+      STYLE_RULES = 'style_rules'
+      TRANSLATION_MEMORY = 'translation_memory'
+    end
+  end
+end

data/lib/deepl/constants/tag_handling_version.rb

@@ -0,0 +1,14 @@
+# 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 Constants
+    # Values of the +tag_handling_version+ option. Any other string is sent as given.
+    class TagHandlingVersion < BaseConstant
+      V1 = 'v1'
+      V2 = 'v2'
+    end
+  end
+end

data/lib/deepl/deprecation.rb

@@ -0,0 +1,42 @@
+# 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
+  # @api private
+  module Deprecation
+    @warned = {}
+    @mutex = Mutex.new
+
+    # Prints +message+ once per process for +key+, only while Ruby's deprecation warnings are on
+    # (+ruby -W:deprecated+). +uplevel+ 2 points the warning at the caller of the deprecated
+    # method.
+    def self.warn_once(key, message, uplevel: 2)
+      return unless enabled?
+
+      first = @mutex.synchronize { @warned[key] ? false : (@warned[key] = true) }
+      return unless first
+
+      if RUBY_VERSION >= '3.0'
+        Kernel.warn(message, uplevel: uplevel, category: :deprecated)
+      else
+        Kernel.warn(message, uplevel: uplevel)
+      end
+    end
+
+    # Ruby 2.6 has no Warning.[] and prints no deprecation warnings.
+    def self.enabled?
+      Warning.respond_to?(:[]) && Warning[:deprecated]
+    end
+
+    # Like +warn_once+, but points the warning at the first caller outside the library, for
+    # deprecated options that are read deep inside a request.
+    def self.warn_once_at_caller(key, message)
+      lib_dir = File.expand_path('..', __dir__)
+      locations = caller_locations(1) || []
+      index = locations.index { |loc| !loc.absolute_path.to_s.start_with?(lib_dir) }
+      warn_once(key, message, uplevel: (index || 0) + 2)
+    end
+  end
+end

data/lib/deepl/document_api.rb

@@ -26,16 +26,23 @@ module DeepL
     #                               the different kinds of documents (PDFs, etc). If nil, will use
     #                               the filename of +input_file_path+.
     # @param [Hash] options Additional (body) options for the upload. Notable glossary options:
-    #                       +:glossary_id+ (a single glossary ID) or +:glossary_ids+ (an array of
-    #                       up to 5 glossary IDs, as strings or `DeepL::Resources::Glossary`
-    #                       objects). +:glossary_ids+ requires +source_lang+ to be set, cannot be
-    #                       combined with +:glossary_id+, and raises `ArgumentError` if these rules
-    #                       are violated or more than 5 IDs are provided. Notable style/translation
-    #                       memory options (mirroring text translation): +:style_rule+ (a style rule
-    #                       ID string or a `DeepL::Resources::StyleRule` object),
+    #                       +:glossary+ (a glossary ID, `DeepL::Resources::Glossary` or
+    #                       `DeepL::Resources::MultilingualGlossary`; replaces the deprecated
+    #                       +:glossary_id+) or +:glossary_ids+ (an array of up to 5 glossary IDs
+    #                       or objects).
+    #                       +:glossary_ids+ requires +source_lang+ to be set, cannot be combined
+    #                       with +:glossary+ or +:glossary_id+, and raises `ArgumentError` if
+    #                       these rules are violated or more than 5 IDs are provided. Notable
+    #                       style/translation memory options (mirroring text translation):
+    #                       +:style_rule+ (a style rule ID string or a
+    #                       `DeepL::Resources::StyleRule` object),
+    #                       +:style_profile+ (a style profile ID string or a
+    #                       `DeepL::Resources::StyleProfile` object),
     #                       +:translation_memory+ (a translation memory ID string or a
     #                       `DeepL::Resources::TranslationMemory` object), and
     #                       +:translation_memory_threshold+ (integer 0-100, recommended minimum 75).
+    #                       +:enable_watermark+ (boolean) adds a "Translated by DeepL" watermark;
+    #                       the API applies it to +docx+ and +pdf+ output only.
     # @param [Hash] additional_headers Additional HTTP headers for the upload.
     # @return [DeepL::Resources::DocumentHandle] Document handle for the uploaded document.
 
@@ -76,16 +83,17 @@ module DeepL
     end
 
     ##
-    # Translates a document with the DeepL API, `sleep`ing during waiting periods. Returns the
-    # status that was queried last. This can be either because the document translation terminated
-    # (successfully or with an error) or because the maximum number of status requests have been
-    # made. See the parameter `max_doc_status_queries` for details.
+    # Translates a document with the DeepL API, `sleep`ing during waiting periods, and returns
+    # the number of bytes written once the translated document is downloaded. Polls until the
+    # translation is done or failed; the deprecated `max_doc_status_queries` limits the number of
+    # status requests if it is configured.
     #
-    # @raise [DocumentTranslationError] If any error occurs during the process.
+    # @raise [DocumentTranslationError] If any error occurs during the process, also when the
+    #   translation fails or is not done after `max_doc_status_queries`.
     #
     # @param [String] input_file Path to the file to be translated
-    # @param [String] output_file Path to the file to write to. Will be overwritten if the file
-    #                             already exists.
+    # @param [String] output_file Path to the file to write to. Must not exist; if it does,
+    #                             DocumentTranslationError is raised and the file is kept.
     # @param [String, nil] source_lang Source language to use for the translation. `nil` will cause
     #                                  automatic source langauge detection to be used. Must be
     #                                  formatted as ISO 639-1, 2-letter language codes.
@@ -97,11 +105,13 @@ module DeepL
     #                               the filename of +input_file_path+.
     # @param [Hash] options Additional options for the upload.
     # @param [Hash] additional_headers Additional headers for the upload.
-    # @return [DeepL::Resources::DocumentTranslationStatus] Status of the document translation.
+    # @return [Integer] Number of bytes written
 
     def translate_document(input_file, output_file, source_lang, target_lang, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists
                            filename = nil, options = {}, additional_headers = {})
-      raise IOError 'File already exists at output path' if File.exist?(output_file)
+      if File.exist?(output_file)
+        raise Exceptions::DocumentTranslationError.new('File already exists at output path', nil)
+      end
 
       begin
         handle = upload(input_file, source_lang, target_lang, filename, options,
@@ -110,7 +120,7 @@ module DeepL
       rescue StandardError => e
         FileUtils.rm_f(output_file)
         raise Exceptions::DocumentTranslationError.new(
-          "Error occurred during document translation: #{e.message}", handle
+          "Error occurred during document translation: #{e.message}", handle, e
         )
       end
     end
@@ -118,13 +128,22 @@ module DeepL
     private
 
     def translate_document_wait_and_download(document_handle, output_file)
-      doc_status = document_handle.wait_until_document_translation_finished
+      doc_status = Utils::DocumentPoller.wait_until_finished(
+        @api, document_handle, max_queries: @api.configuration.max_doc_status_queries
+      )
+      unless doc_status.done?
+        raise Exceptions::DocumentTranslationError.new(not_done_message(doc_status),
+                                                       document_handle)
+      end
+
+      download(document_handle, output_file)
+    end
+
+    def not_done_message(doc_status)
       if doc_status.error?
-        raise Exceptions::DocumentTranslationError.new(
-          "Exception when querying document status #{doc_status.error_message}", document_handle
-        )
+        "Exception when querying document status #{doc_status.error_message}"
       else
-        download(document_handle, output_file)
+        "Document translation not done after max_doc_status_queries (#{doc_status.status})"
       end
     end
   end

data/lib/deepl/exceptions/bad_request.rb

@@ -7,9 +7,7 @@ module DeepL
   module Exceptions
     class BadRequest < RequestError
       def to_s
-        JSON.parse(response.body)['message']
-      rescue JSON::ParserError
-        response.body
+        body_message.to_s
       end
     end
   end

data/lib/deepl/exceptions/connection_error.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 Exceptions
+    ##
+    # Raised by DeepL::Client and DeepL::AdminClient for a network failure without a complete
+    # HTTP response from the API (DNS, connection, TLS, proxy, timeout or a body cut off
+    # mid-read), after the retries are used up. Transient failures (DNS, connection, timeout,
+    # cut-off body) are retried and have +should_retry?+ true; TLS failures, proxy failures and
+    # malformed responses are raised at once and have +should_retry?+ false. The original
+    # exception is available as +cause+. The module-level API raises the original exception.
+    class ConnectionError < Error
+      # Raised from a +rescue+ block, so the original exception becomes +cause+.
+      # +should_retry: false+ marks a request that is unsafe to repeat once sent.
+      def self.from_network_error(error, should_retry: true)
+        new("Connection to the DeepL API failed: #{error.message}",
+            should_retry: should_retry && transient?(error))
+      end
+
+      def self.transient?(error)
+        Requests::Base::RETRYABLE_NETWORK_ERRORS.any? { |type| error.is_a?(type) }
+      end
+
+      def initialize(message = nil, should_retry: true)
+        super(message)
+        @should_retry = should_retry
+      end
+
+      def should_retry?
+        @should_retry
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/document_not_ready_error.rb

@@ -0,0 +1,17 @@
+# 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 Exceptions
+    # HTTP 503 on a document download: the translated document is not ready yet. Raised after
+    # the retries.
+    class DocumentNotReadyError < ServerError
+      def to_s
+        message = body_message
+        message ? "Document not ready: #{message}" : 'Document not ready.'
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/document_translation_error.rb

@@ -6,9 +6,25 @@
 module DeepL
   module Exceptions
     class DocumentTranslationError < Error
-      def initialize(message, handle)
+      # @return [DeepL::Resources::DocumentHandle, nil] Handle of the uploaded document, +nil+ if
+      #   the upload failed. Use it to query the status or download the document later.
+      attr_reader :document_handle
+
+      # +error+ is the failure being wrapped; the HTTP status and retryability of a DeepL error
+      # are copied from it.
+      def initialize(message, handle, error = nil)
         super(message)
         @handle = handle
+        @document_handle = handle
+        return unless error.is_a?(Error)
+
+        @http_status_code = error.http_status_code
+        @should_retry = error.should_retry?
+      end
+
+      # @return [Boolean] +should_retry?+ of the wrapped DeepL error, +false+ without one.
+      def should_retry?
+        @should_retry || false
       end
     end
   end

data/lib/deepl/exceptions/error.rb

@@ -6,8 +6,20 @@
 module DeepL
   module Exceptions
     class Error < StandardError
+      # @return [Integer, nil] HTTP status of the failed response, +nil+ if there was none.
+      attr_reader :http_status_code
+
+      # @param [String, nil] message
+      # @param [Integer, nil] http_status_code HTTP status of the failed response.
+      # @param [Boolean] should_retry Whether repeating the request may succeed.
+      def initialize(message = nil, http_status_code: nil, should_retry: false)
+        super(message)
+        @http_status_code = http_status_code
+        @should_retry = should_retry
+      end
+
       def should_retry?
-        false
+        @should_retry || false
       end
     end
   end

data/lib/deepl/exceptions/not_found.rb

@@ -6,10 +6,15 @@
 module DeepL
   module Exceptions
     class NotFound < RequestError
+      # @param [String, nil] message Replaces the API's message, for a not-found condition the
+      #   SDK detects in a successful response.
+      def initialize(response, request = nil, message = nil)
+        super(response, request)
+        @message = message
+      end
+
       def to_s
-        JSON.parse(response.body)['message']
-      rescue JSON::ParserError
-        response.body
+        (@message || body_message).to_s
       end
     end
   end

data/lib/deepl/exceptions/not_supported.rb

@@ -5,8 +5,14 @@
 
 module DeepL
   module Exceptions
+    # @deprecated Only the module-level API raises it, from
+    #   +DeepL::Resources::Language#supports_formality?+ for a source language; DeepL::Client
+    #   returns +nil+ instead.
     class NotSupported < Error
       def initialize(msg = 'The feature is not supported')
+        Deprecation.warn_once('DeepL::Exceptions::NotSupported',
+                              '[DEPRECATION] DeepL::Exceptions::NotSupported is deprecated, ' \
+                              'only the module-level API raises it.')
         super
       end
     end

data/lib/deepl/exceptions/request_error.rb

@@ -8,13 +8,30 @@ module DeepL
     class RequestError < Error
       attr_reader :request, :response
 
-      def initialize(response)
+      def initialize(response, request = nil)
         super()
         @response = response
+        @request = request
+        @http_status_code = response.code.to_i if response.respond_to?(:code)
       end
 
       def to_s
-        'Unknown error.'
+        message = body_message
+        status = "HTTP status #{http_status_code}"
+        message ? "Request failed with #{status}: #{message}" : "Request failed with #{status}."
+      end
+
+      private
+
+      # The +message+ of a JSON object body, else the raw body; +nil+ for an empty body.
+      def body_message
+        body = response&.body
+        return nil if body.nil? || body.to_s.strip.empty?
+
+        data = JSON.parse(body)
+        data.is_a?(Hash) && data['message'].is_a?(String) ? data['message'] : body
+      rescue JSON::ParserError
+        body
       end
     end
   end

data/lib/deepl/exceptions/server_error.rb

@@ -6,12 +6,18 @@
 module DeepL
   module Exceptions
     class ServerError < RequestError
+      # @param [Boolean] should_retry False for a request that is unsafe to repeat once sent.
+      def initialize(response, request = nil, should_retry: true)
+        super(response, request)
+        @should_retry = should_retry
+      end
+
       def to_s
         'An internal server error occured. Try again after waiting a short period.'
       end
 
       def should_retry?
-        true
+        @should_retry
       end
     end
   end

data/lib/deepl/exceptions/validation_error.rb

@@ -0,0 +1,14 @@
+# 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 Exceptions
+    ##
+    # An invalid argument detected before any request is sent: an invalid glossary or spoken
+    # terms term, a malformed glossary TSV line, or an unsupported +DeepL.languages+ type.
+    class ValidationError < Error
+    end
+  end
+end