deepl-rb 3.9.0 → 3.10.0

data/lib/deepl.rb

@@ -4,11 +4,16 @@
 # frozen_string_literal: true
 
 # -- Dependencies
+require 'fileutils'
 require 'json'
 require 'net/http'
 
+# -- Deprecation
+require_relative 'deepl/deprecation'
+
 # -- Exceptions
 require_relative 'deepl/exceptions/error'
+require_relative 'deepl/exceptions/validation_error'
 require_relative 'deepl/exceptions/request_error'
 require_relative 'deepl/exceptions/authorization_failed'
 require_relative 'deepl/exceptions/bad_request'
@@ -19,6 +24,8 @@ require_relative 'deepl/exceptions/not_supported'
 require_relative 'deepl/exceptions/request_entity_too_large'
 require_relative 'deepl/exceptions/document_translation_error'
 require_relative 'deepl/exceptions/server_error'
+require_relative 'deepl/exceptions/document_not_ready_error'
+require_relative 'deepl/exceptions/connection_error'
 
 # -- Requests
 require_relative 'deepl/requests/base'
@@ -31,6 +38,16 @@ require_relative 'deepl/requests/glossary/entries'
 require_relative 'deepl/requests/glossary/find'
 require_relative 'deepl/requests/glossary/language_pairs'
 require_relative 'deepl/requests/glossary/list'
+require_relative 'deepl/requests/multilingual_glossary/helpers'
+require_relative 'deepl/requests/multilingual_glossary/create'
+require_relative 'deepl/requests/multilingual_glossary/destroy'
+require_relative 'deepl/requests/multilingual_glossary/destroy_dictionary'
+require_relative 'deepl/requests/multilingual_glossary/entries'
+require_relative 'deepl/requests/multilingual_glossary/find'
+require_relative 'deepl/requests/multilingual_glossary/list'
+require_relative 'deepl/requests/multilingual_glossary/replace_dictionary'
+require_relative 'deepl/requests/multilingual_glossary/update'
+require_relative 'deepl/requests/style_rule/helpers'
 require_relative 'deepl/requests/style_rule/list'
 require_relative 'deepl/requests/style_rule/create'
 require_relative 'deepl/requests/style_rule/find'
@@ -41,6 +58,21 @@ require_relative 'deepl/requests/style_rule/create_custom_instruction'
 require_relative 'deepl/requests/style_rule/find_custom_instruction'
 require_relative 'deepl/requests/style_rule/update_custom_instruction'
 require_relative 'deepl/requests/style_rule/destroy_custom_instruction'
+require_relative 'deepl/requests/spoken_terms/helpers'
+require_relative 'deepl/requests/spoken_terms/create'
+require_relative 'deepl/requests/spoken_terms/list'
+require_relative 'deepl/requests/spoken_terms/find'
+require_relative 'deepl/requests/spoken_terms/update'
+require_relative 'deepl/requests/spoken_terms/entries'
+require_relative 'deepl/requests/spoken_terms/replace_term_list'
+require_relative 'deepl/requests/spoken_terms/destroy'
+require_relative 'deepl/requests/spoken_terms/destroy_term_list'
+require_relative 'deepl/requests/style_profile/base'
+require_relative 'deepl/requests/style_profile/list'
+require_relative 'deepl/requests/style_profile/create'
+require_relative 'deepl/requests/style_profile/find'
+require_relative 'deepl/requests/style_profile/update'
+require_relative 'deepl/requests/style_profile/destroy'
 require_relative 'deepl/requests/translation_memory/base'
 require_relative 'deepl/requests/translation_memory/storage_base'
 require_relative 'deepl/requests/translation_memory/list'
@@ -53,16 +85,29 @@ require_relative 'deepl/requests/translation_memory/create_export'
 require_relative 'deepl/requests/translation_memory/find_job'
 require_relative 'deepl/requests/translation_memory/download_export'
 require_relative 'deepl/requests/languages'
+require_relative 'deepl/requests/languages_for_resource'
+require_relative 'deepl/requests/language_resources'
 require_relative 'deepl/requests/translate'
 require_relative 'deepl/requests/usage'
+require_relative 'deepl/requests/write_improvements'
 require_relative 'deepl/requests/rephrase'
+require_relative 'deepl/requests/correct'
+require_relative 'deepl/requests/admin/base'
+require_relative 'deepl/requests/admin/usage_analytics'
+require_relative 'deepl/requests/admin/custom_tag_usage_analytics'
+require_relative 'deepl/requests/admin/create_developer_key'
+require_relative 'deepl/requests/admin/list_developer_keys'
+require_relative 'deepl/requests/admin/update_developer_key'
 
 # -- Responses and resources
 require_relative 'deepl/resources/base'
 require_relative 'deepl/resources/document_handle'
 require_relative 'deepl/resources/document_translation_status'
 require_relative 'deepl/resources/glossary'
+require_relative 'deepl/resources/multilingual_glossary'
 require_relative 'deepl/resources/style_rule'
+require_relative 'deepl/resources/spoken_terms'
+require_relative 'deepl/resources/style_profile'
 require_relative 'deepl/resources/translation_memory'
 require_relative 'deepl/resources/translation_memory_segments'
 require_relative 'deepl/resources/translation_memory_import'
@@ -70,22 +115,38 @@ require_relative 'deepl/resources/translation_memory_export'
 require_relative 'deepl/resources/translation_memory_job'
 require_relative 'deepl/resources/language'
 require_relative 'deepl/resources/language_pair'
+require_relative 'deepl/resources/language_resource'
+require_relative 'deepl/resources/language_support'
 require_relative 'deepl/resources/text'
 require_relative 'deepl/resources/usage'
+require_relative 'deepl/resources/developer_key'
+require_relative 'deepl/resources/admin_usage_report'
+require_relative 'deepl/resources/custom_tag_usage_report'
 
 # -- Utils
 require_relative 'deepl/utils/exception_builder'
+require_relative 'deepl/utils/http_client_builder'
+require_relative 'deepl/utils/client_builder'
 require_relative 'deepl/utils/backoff_timer'
 require_relative 'deepl/utils/time_parser'
+require_relative 'deepl/utils/number_parser'
+require_relative 'deepl/utils/term_validator'
+require_relative 'deepl/utils/document_poller'
 
 # -- Constants
 require_relative 'deepl/constants/base_constant'
+require_relative 'deepl/constants/document_status_code'
 require_relative 'deepl/constants/formality'
+require_relative 'deepl/constants/language_include'
+require_relative 'deepl/constants/language_resource_name'
 require_relative 'deepl/constants/model_type'
 require_relative 'deepl/constants/split_sentences'
 require_relative 'deepl/constants/tag_handling'
+require_relative 'deepl/constants/tag_handling_version'
 require_relative 'deepl/constants/tone'
 require_relative 'deepl/constants/writing_style'
+require_relative 'deepl/constants/admin_usage_group_by'
+require_relative 'deepl/constants/custom_tag_usage_aggregate_by'
 
 # -- HTTP Utils
 require_relative 'http_client_options'
@@ -100,19 +161,32 @@ require_relative 'deepl/document_api'
 require_relative 'deepl/glossary_api'
 require_relative 'deepl/style_rule_api'
 require_relative 'deepl/translation_memory_api'
+require_relative 'deepl/app_info'
+require_relative 'deepl/client'
+require_relative 'deepl/admin_client'
 
 # -- Gem interface
+#
+# The module-level API (+DeepL.configure+, +DeepL.translate+, +DeepL.glossaries+, ...) keeps its
+# configuration in module state. It is deprecated in favour of DeepL::Client and will be removed
+# in the next major version.
 module DeepL
   extend self
 
   ## -- API shortcuts
 
+  # @deprecated Use DeepL::Client instead.
   def api
-    @api ||= API.new(configuration)
+    deprecated(:api, 'DeepL::Client')
+    module_api
   end
 
+  # @deprecated Use DeepL::Client#get_source_languages or DeepL::Client#get_target_languages
+  #   instead.
   def languages(options = {})
-    Requests::Languages.new(api, options).request
+    deprecated(:languages,
+               'DeepL::Client#get_source_languages or DeepL::Client#get_target_languages')
+    Requests::Languages.new(module_api, options).request
   end
 
   ##
@@ -122,88 +196,139 @@ module DeepL
   # @param [String, nil] source_lang Source language. `nil` enables automatic detection.
   # @param [String] target_lang Target language.
   # @param [Hash] options Additional (body) options for the translation. Notable options:
-  #   * +:glossary_id+ - A single glossary ID (string) to use for the translation. Requires
-  #     +source_lang+ to be set. Cannot be combined with +:glossary_ids+.
-  #   * +:glossary_ids+ - An array of up to 5 glossary IDs (strings or
-  #     `DeepL::Resources::Glossary` objects) to use for the translation. Glossaries are applied
-  #     in order (first match wins). Requires +source_lang+ to be set. Cannot be combined with
-  #     +:glossary_id+. Raises `ArgumentError` if these rules are violated or more than 5 IDs are
-  #     provided.
+  #   * +:glossary+ - A glossary ID, `DeepL::Resources::Glossary` or
+  #     `DeepL::Resources::MultilingualGlossary` to use for the translation, sent as
+  #     +glossary_id+. Cannot be combined with +:glossary_id+ or +:glossary_ids+.
+  #   * +:glossary_id+ - Deprecated, use +:glossary+. A single glossary ID (string).
+  #   * +:glossary_ids+ - An array of up to 5 glossary IDs (strings,
+  #     `DeepL::Resources::Glossary` or `DeepL::Resources::MultilingualGlossary` objects) to
+  #     use for the translation. Glossaries are applied in order (first match wins). Without
+  #     +source_lang+, the API detects it. Cannot be combined with +:glossary+ or
+  #     +:glossary_id+. Raises `ArgumentError` if these rules are violated or more than 5 IDs
+  #     are provided.
+  #   * +: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. Applies the profile's glossaries, style rule lists and translation memories.
   # @param [Hash] additional_headers Additional HTTP headers for the translation.
   # @return [DeepL::Resources::Text, Array<DeepL::Resources::Text>] Translated text resource(s).
+  # @deprecated Use DeepL::Client#translate_text instead.
   def translate(text, source_lang, target_lang, options = {}, additional_headers = {})
-    configure if @configuration.nil?
-    Requests::Translate.new(api, text, source_lang, target_lang, options,
+    deprecated(:translate, 'DeepL::Client#translate_text')
+    ensure_configured
+    Requests::Translate.new(module_api, text, source_lang, target_lang, options,
                             additional_headers).request
   end
 
+  # @deprecated Use DeepL::Client instead.
   def document(options = {})
-    configure if @configuration.nil?
-    DocumentApi.new(api, options)
+    deprecated(:document, 'DeepL::Client')
+    ensure_configured
+    DocumentApi.new(module_api, options)
   end
 
+  # @deprecated Use DeepL::Client instead.
   def glossaries(options = {})
-    configure if @configuration.nil?
-    GlossaryApi.new(api, options)
+    deprecated(:glossaries, 'DeepL::Client')
+    ensure_configured
+    GlossaryApi.new(module_api, options)
   end
 
+  # @deprecated Use DeepL::Client instead.
   def style_rules(options = {})
-    configure if @configuration.nil?
-    StyleRuleApi.new(api, options)
+    deprecated(:style_rules, 'DeepL::Client')
+    ensure_configured
+    StyleRuleApi.new(module_api, options)
   end
 
+  # @deprecated Use DeepL::Client instead.
   def translation_memories(options = {})
-    configure if @configuration.nil?
-    TranslationMemoryApi.new(api, options)
+    deprecated(:translation_memories, 'DeepL::Client')
+    ensure_configured
+    TranslationMemoryApi.new(module_api, options)
   end
 
+  # @deprecated Use DeepL::Client#rephrase_text instead.
   def rephrase(text, target_lang = nil, writing_style = nil, tone = nil, options = {}, # rubocop:disable Metrics/ParameterLists
                additional_headers = {})
-    configure if @configuration.nil?
-    Requests::Rephrase.new(api, text, target_lang, writing_style, tone, options,
+    deprecated(:rephrase, 'DeepL::Client#rephrase_text')
+    ensure_configured
+    Requests::Rephrase.new(module_api, text, target_lang, writing_style, tone, options,
                            additional_headers).request
   end
 
+  # @deprecated Use DeepL::Client#get_usage instead.
   def usage(options = {})
-    configure if @configuration.nil?
-    Requests::Usage.new(api, options).request
+    deprecated(:usage, 'DeepL::Client#get_usage')
+    ensure_configured
+    Requests::Usage.new(module_api, options).request
   end
 
+  # @deprecated Use DeepL::Client with +http_client_options:+ instead.
   def http_client
+    deprecated(:http_client, 'DeepL::Client')
     @http_client
   end
 
-  def with_session(client_options = HTTPClientOptions.new()) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-    raise ArgumentError 'This method requires a block to be passed in which contains the actual API calls, see README for example usage.' unless block_given? # rubocop:disable Layout/LineLength
+  # @deprecated Use DeepL::Client with +http_client_options:+ instead.
+  def with_session(client_options = HTTPClientOptions.new) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+    raise ArgumentError, 'This method requires a block to be passed in which contains the actual API calls, see README for example usage.' unless block_given? # rubocop:disable Layout/LineLength
 
-    has_proxy = client_options.proxy.key?('proxy_addr') and client_options.proxy.key?('proxy_port')
+    deprecated(:with_session, 'DeepL::Client')
+    previous_api_client = module_api.http_client
+    previous_api_options = module_api.http_client_options
+    previous_http_client = @http_client
     begin
-      uri = URI(configuration.host)
-      http = Net::HTTP.new(uri.host, uri.port, has_proxy ? client_options.proxy['proxy_addr'] : nil,
-                           has_proxy ? client_options.proxy['proxy_port'] : nil)
-      http.use_ssl = client_options.enable_ssl_verification
-      http.ca_file = client_options.cert_path if client_options.cert_path
-      http.open_timeout = client_options.open_timeout unless client_options.open_timeout.nil?
-      http.read_timeout = client_options.read_timeout unless client_options.read_timeout.nil?
-      http.write_timeout = client_options.write_timeout unless client_options.write_timeout.nil?
-      http.ssl_timeout = client_options.ssl_timeout unless client_options.ssl_timeout.nil?
-      http.start
+      http = Utils::HTTPClientBuilder.build(module_configuration.host, client_options)
+      start_session(http, client_options)
       @http_client = http
-      api.update_http_client(http)
+      module_api.update_http_client(http, client_options)
       yield
     ensure
-      http.finish
+      module_api.update_http_client(previous_api_client, previous_api_options)
+      @http_client = previous_http_client
+      http.finish if http&.started?
     end
   end
 
   # -- Configuration
 
+  # @deprecated Use DeepL::Client.new instead.
   def configuration
-    @configuration ||= Configuration.new
+    deprecated(:configuration, 'DeepL::Client.new')
+    module_configuration
   end
 
+  # @deprecated Use DeepL::Client.new instead.
   def configure
-    yield configuration if block_given?
-    configuration.validate!
+    deprecated(:configure, 'DeepL::Client.new')
+    yield module_configuration if block_given?
+    module_configuration.validate!
+  end
+
+  private
+
+  def module_configuration
+    @configuration ||= Configuration.new # rubocop:disable Naming/MemoizedInstanceVariableName
+  end
+
+  def module_api
+    @api ||= API.new(module_configuration) # rubocop:disable Naming/MemoizedInstanceVariableName
+  end
+
+  # Opens the session connection within the configured timeout, unless the options set one.
+  def start_session(http, client_options)
+    timeout = module_configuration.timeout
+    http.open_timeout = timeout if client_options.open_timeout.nil? && timeout
+    http.start
+  end
+
+  def ensure_configured
+    module_configuration.validate! if @configuration.nil?
+  end
+
+  def deprecated(name, replacement)
+    Deprecation.warn_once("DeepL.#{name}",
+                          "[DEPRECATION] DeepL.#{name} is deprecated, use #{replacement} instead.",
+                          uplevel: 3)
   end
 end

data/lib/http_client_options.rb

@@ -8,7 +8,7 @@ module DeepL
     attr_reader :proxy, :send_platform_info, :enable_ssl_verification, :cert_path, :open_timeout,
                 :read_timeout, :write_timeout, :ssl_timeout
 
-    def initialize(proxy, cert_path, enable_ssl_verification: true, open_timeout: nil, # rubocop:disable Metrics/ParameterLists
+    def initialize(proxy = {}, cert_path = nil, enable_ssl_verification: true, open_timeout: nil, # rubocop:disable Metrics/ParameterLists
                    read_timeout: nil, write_timeout: nil, ssl_timeout: nil)
       @proxy = proxy
       @enable_ssl_verification = enable_ssl_verification
@@ -18,5 +18,25 @@ module DeepL
       @write_timeout = write_timeout
       @ssl_timeout = ssl_timeout
     end
+
+    # Hides the user info of a proxy URL: +http://user:pass@host:port+ becomes
+    # +http://[REDACTED]@host:port+.
+    def self.redact_proxy(proxy)
+      if proxy.is_a?(String)
+        return proxy.sub(%r{\A([a-z][a-z0-9+.-]*://)?[^/@]*@}i,
+                         '\1[REDACTED]@')
+      end
+      return proxy unless proxy.is_a?(Hash)
+
+      proxy.to_h { |key, value| [key, key.to_s =~ /user|pass/i ? '[REDACTED]' : value] }
+    end
+
+    # Leaves out the proxy credentials.
+    def inspect
+      shown = { proxy: self.class.redact_proxy(proxy), cert_path: cert_path,
+                enable_ssl_verification: enable_ssl_verification, open_timeout: open_timeout,
+                read_timeout: read_timeout, write_timeout: write_timeout, ssl_timeout: ssl_timeout }
+      "#<#{self.class.name} #{shown.map { |name, value| "#{name}=#{value.inspect}" }.join(', ')}>"
+    end
   end
 end

data/lib/version.rb

@@ -4,5 +4,5 @@
 # frozen_string_literal: true
 
 module DeepL
-  VERSION = '3.9.0'
+  VERSION = '3.10.0'
 end

data/spec/fixtures.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 file.
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+# Fixtures shared by the offline and the real-API specs.
+module Fixtures
+  EXAMPLE_TMX = <<~TMX
+    <?xml version="1.0" encoding="UTF-8"?>
+    <tmx version="1.4"><header creationtool="deepl-rb-spec" creationtoolversion="1"
+      segtype="sentence" o-tmf="plain" adminlang="en" srclang="en" datatype="plaintext"/>
+    <body><tu><tuv xml:lang="en"><seg>Segment number 1</seg></tuv>
+    <tuv xml:lang="de"><seg>Segment Nummer 1</seg></tuv></tu></body></tmx>
+  TMX
+
+  # Every byte value, to check that downloads are written unchanged.
+  BINARY_CONTENT = (0..255).map(&:chr).join.b.freeze
+
+  # Writes an example .txt document in +dir+. Returns the input path and a free output path.
+  def create_text_document(dir)
+    input = File.join(dir, 'example_document.txt')
+    File.write(input, 'proton beam')
+    [input, File.join(dir, 'output_document.txt')]
+  end
+end
+
+RSpec.shared_context 'with a temporary directory' do
+  let(:temp_dir) { Dir.mktmpdir('deepl-rspec-') }
+
+  after { FileUtils.remove_entry(temp_dir) }
+end