deepl-rb 3.6.0 → 3.7.0

data/lib/deepl/resources/style_rule.rb

@@ -0,0 +1,86 @@
+# Copyright 2025 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
+
+require 'time'
+
+module DeepL
+  module Resources
+    class ConfiguredRules
+      attr_reader :dates_and_times, :formatting, :numbers, :punctuation,
+                  :spelling_and_grammar, :style_and_tone, :vocabulary
+
+      def initialize(configured_rules_data)
+        @dates_and_times = extract_rule(configured_rules_data, 'dates_and_times')
+        @formatting = extract_rule(configured_rules_data, 'formatting')
+        @numbers = extract_rule(configured_rules_data, 'numbers')
+        @punctuation = extract_rule(configured_rules_data, 'punctuation')
+        @spelling_and_grammar = extract_rule(configured_rules_data, 'spelling_and_grammar')
+        @style_and_tone = extract_rule(configured_rules_data, 'style_and_tone')
+        @vocabulary = extract_rule(configured_rules_data, 'vocabulary')
+      end
+
+      private
+
+      def extract_rule(data, key)
+        data[key] || {}
+      end
+    end
+
+    class CustomInstruction
+      attr_reader :id, :label, :prompt, :source_language
+
+      def initialize(custom_instruction_data)
+        @id = custom_instruction_data['id']
+        @label = custom_instruction_data['label']
+        @prompt = custom_instruction_data['prompt']
+        @source_language = custom_instruction_data['source_language']
+      end
+    end
+
+    class StyleRule < Base
+      attr_reader :style_id, :name, :creation_time, :updated_time, :language, :version,
+                  :configured_rules, :custom_instructions
+
+      def initialize(style_rule, *args)
+        super(*args)
+        extract_basic_fields(style_rule)
+        extract_configured_rules(style_rule)
+        extract_custom_instructions(style_rule)
+      end
+
+      private
+
+      def extract_basic_fields(style_rule)
+        @style_id = style_rule['style_id']
+        @name = style_rule['name']
+        @creation_time = parse_time(style_rule['creation_time'])
+        @updated_time = parse_time(style_rule['updated_time'])
+        @language = style_rule['language']
+        @version = style_rule['version']
+      end
+
+      def extract_configured_rules(style_rule)
+        configured_rules_data = style_rule['configured_rules']
+        @configured_rules = configured_rules_data ? ConfiguredRules.new(configured_rules_data) : nil
+      end
+
+      def extract_custom_instructions(style_rule)
+        @custom_instructions = style_rule['custom_instructions']&.map do |ci|
+          CustomInstruction.new(ci)
+        end
+      end
+
+      def to_s
+        "#{style_id} - #{name}"
+      end
+
+      def parse_time(time_string)
+        return nil unless time_string
+
+        Time.parse(time_string)
+      end
+    end
+  end
+end

data/lib/deepl/resources/text.rb

@@ -0,0 +1,24 @@
+# Copyright 2018 Daniel Herzog
+# 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 Resources
+    class Text < Base
+      attr_reader :text, :detected_source_language, :model_type_used
+
+      def initialize(text, detected_source_language, model_type_used, *args)
+        super(*args)
+
+        @text = text
+        @detected_source_language = detected_source_language
+        @model_type_used = model_type_used
+      end
+
+      def to_s
+        text
+      end
+    end
+  end
+end

data/lib/deepl/resources/translation_memory.rb

@@ -0,0 +1,25 @@
+# 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 Resources
+    class TranslationMemory < Base
+      attr_reader :translation_memory_id, :name, :source_language, :target_languages, :segment_count
+
+      def initialize(translation_memory, *args)
+        super(*args)
+        @translation_memory_id = translation_memory['translation_memory_id']
+        @name = translation_memory['name']
+        @source_language = translation_memory['source_language']
+        @target_languages = translation_memory['target_languages'] || []
+        @segment_count = translation_memory['segment_count'] || 0
+      end
+
+      def to_s
+        "#{translation_memory_id} - #{name}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/usage.rb

@@ -0,0 +1,27 @@
+# Copyright 2018 Daniel Herzog
+# 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 Resources
+    class Usage < Base
+      attr_reader :character_count, :character_limit
+
+      def initialize(character_count, character_limit, *args)
+        super(*args)
+
+        @character_count = character_count
+        @character_limit = character_limit
+      end
+
+      def to_s
+        "#{character_count} / #{character_limit}"
+      end
+
+      def quota_exceeded?
+        character_count >= character_limit
+      end
+    end
+  end
+end

data/lib/deepl/style_rule_api.rb

@@ -0,0 +1,61 @@
+# Copyright 2025 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
+  class StyleRuleApi
+    def initialize(api, options = {})
+      @api = api
+      @options = options
+    end
+
+    def list(options = {})
+      DeepL::Requests::StyleRule::List.new(@api, options).request
+    end
+
+    def create(name, language, options = {})
+      DeepL::Requests::StyleRule::Create.new(@api, name, language, options).request
+    end
+
+    def find(style_id, options = {})
+      DeepL::Requests::StyleRule::Find.new(@api, style_id, options).request
+    end
+
+    def update_name(style_id, name, options = {})
+      DeepL::Requests::StyleRule::Update.new(@api, style_id, name, options).request
+    end
+
+    def destroy(style_id, options = {})
+      DeepL::Requests::StyleRule::Destroy.new(@api, style_id, options).request
+    end
+
+    def update_configured_rules(style_id, configured_rules, options = {})
+      DeepL::Requests::StyleRule::UpdateConfiguredRules.new(@api, style_id, configured_rules,
+                                                            options).request
+    end
+
+    def create_custom_instruction(style_id, label, prompt, source_language = nil, options = {})
+      DeepL::Requests::StyleRule::CreateCustomInstruction.new(@api, style_id, label, prompt,
+                                                              source_language, options).request
+    end
+
+    def find_custom_instruction(style_id, instruction_id, options = {})
+      DeepL::Requests::StyleRule::FindCustomInstruction.new(@api, style_id, instruction_id,
+                                                            options).request
+    end
+
+    def update_custom_instruction(style_id, instruction_id, label,
+                                  prompt, source_language = nil,
+                                  options = {})
+      DeepL::Requests::StyleRule::UpdateCustomInstruction.new(@api, style_id, instruction_id,
+                                                              label, prompt, source_language,
+                                                              options).request
+    end
+
+    def destroy_custom_instruction(style_id, instruction_id, options = {})
+      DeepL::Requests::StyleRule::DestroyCustomInstruction.new(@api, style_id, instruction_id,
+                                                               options).request
+    end
+  end
+end

data/lib/deepl/translation_memory_api.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
+  class TranslationMemoryApi
+    def initialize(api, options = {})
+      @api = api
+      @options = options
+    end
+
+    def list(options = {})
+      DeepL::Requests::TranslationMemory::List.new(@api, options).request
+    end
+  end
+end

data/lib/deepl/utils/backoff_timer.rb

@@ -0,0 +1,46 @@
+# Copyright 2024 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
+    class BackoffTimer
+      # Implements exponential-backoff strategy.
+      # This strategy is based on the GRPC Connection Backoff Protocol:
+      # https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md
+
+      BACKOFF_INITIAL = 1.0
+      BACKOFF_MAX = 120.0
+      BACKOFF_JITTER = 0.23
+      BACKOFF_MULTIPLIER = 1.6
+
+      attr_reader :num_retries
+
+      def initialize(min_connection_timeout = 10.0)
+        @num_retries = 0
+        @backoff = BACKOFF_INITIAL
+        @deadline = Time.now.to_f + @backoff
+        @min_connection_timeout = min_connection_timeout
+      end
+
+      def current_request_timeout
+        [time_until_deadline, @min_connection_timeout].max
+      end
+
+      def time_until_deadline
+        [@deadline - Time.now.to_f, 0.0].max
+      end
+
+      def sleep_until_deadline
+        sleep(time_until_deadline)
+        # Apply multiplier to current backoff time
+        @backoff = [@backoff * BACKOFF_MULTIPLIER, BACKOFF_MAX].min
+        # Get deadline by applying jitter as a proportion of backoff:
+        # if jitter is 0.1, then multiply backoff by random value in [0.9, 1.1]
+        @deadline = Time.now.to_f + (@backoff * (1 + (BACKOFF_JITTER * rand(-1.0..1.0))))
+        @num_retries += 1
+      end
+    end
+  end
+end

data/lib/deepl/utils/exception_builder.rb

@@ -0,0 +1,34 @@
+# Copyright 2022 Daniel Herzog
+# 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
+    class ExceptionBuilder
+      attr_reader :request, :response
+
+      def self.error_class_from_response_code(code) # rubocop:disable Metrics/CyclomaticComplexity
+        case code
+        when 400 then Exceptions::BadRequest
+        when 401, 403 then Exceptions::AuthorizationFailed
+        when 404 then Exceptions::NotFound
+        when 413 then Exceptions::RequestEntityTooLarge
+        when 429 then Exceptions::LimitExceeded
+        when 456 then Exceptions::QuotaExceeded
+        when 500..599 then Exceptions::ServerError
+        else Exceptions::RequestError
+        end
+      end
+
+      def initialize(response)
+        @response = response
+      end
+
+      def build
+        error_class = self.class.error_class_from_response_code(response.code.to_i)
+        error_class.new(response)
+      end
+    end
+  end
+end

data/lib/deepl.rb

@@ -0,0 +1,175 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+# -- Dependencies
+require 'json'
+require 'net/http'
+
+# -- Exceptions
+require_relative 'deepl/exceptions/error'
+require_relative 'deepl/exceptions/request_error'
+require_relative 'deepl/exceptions/authorization_failed'
+require_relative 'deepl/exceptions/bad_request'
+require_relative 'deepl/exceptions/limit_exceeded'
+require_relative 'deepl/exceptions/quota_exceeded'
+require_relative 'deepl/exceptions/not_found'
+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'
+
+# -- Requests
+require_relative 'deepl/requests/base'
+require_relative 'deepl/requests/document/download'
+require_relative 'deepl/requests/document/get_status'
+require_relative 'deepl/requests/document/upload'
+require_relative 'deepl/requests/glossary/create'
+require_relative 'deepl/requests/glossary/destroy'
+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/style_rule/list'
+require_relative 'deepl/requests/style_rule/create'
+require_relative 'deepl/requests/style_rule/find'
+require_relative 'deepl/requests/style_rule/update'
+require_relative 'deepl/requests/style_rule/destroy'
+require_relative 'deepl/requests/style_rule/update_configured_rules'
+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/translation_memory/list'
+require_relative 'deepl/requests/languages'
+require_relative 'deepl/requests/translate'
+require_relative 'deepl/requests/usage'
+require_relative 'deepl/requests/rephrase'
+
+# -- 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/style_rule'
+require_relative 'deepl/resources/translation_memory'
+require_relative 'deepl/resources/language'
+require_relative 'deepl/resources/language_pair'
+require_relative 'deepl/resources/text'
+require_relative 'deepl/resources/usage'
+
+# -- Utils
+require_relative 'deepl/utils/exception_builder'
+require_relative 'deepl/utils/backoff_timer'
+
+# -- Constants
+require_relative 'deepl/constants/base_constant'
+require_relative 'deepl/constants/formality'
+require_relative 'deepl/constants/model_type'
+require_relative 'deepl/constants/split_sentences'
+require_relative 'deepl/constants/tag_handling'
+require_relative 'deepl/constants/tone'
+require_relative 'deepl/constants/writing_style'
+
+# -- HTTP Utils
+require_relative 'http_client_options'
+
+# -- Version
+require_relative 'version'
+
+# -- Other wrappers
+require_relative 'deepl/api'
+require_relative 'deepl/configuration'
+require_relative 'deepl/document_api'
+require_relative 'deepl/glossary_api'
+require_relative 'deepl/style_rule_api'
+require_relative 'deepl/translation_memory_api'
+
+# -- Gem interface
+module DeepL
+  extend self
+
+  ## -- API shortcuts
+
+  def api
+    @api ||= API.new(configuration)
+  end
+
+  def languages(options = {})
+    Requests::Languages.new(api, options).request
+  end
+
+  def translate(text, source_lang, target_lang, options = {})
+    configure if @configuration.nil?
+    Requests::Translate.new(api, text, source_lang, target_lang, options).request
+  end
+
+  def document(options = {})
+    configure if @configuration.nil?
+    DocumentApi.new(api, options)
+  end
+
+  def glossaries(options = {})
+    configure if @configuration.nil?
+    GlossaryApi.new(api, options)
+  end
+
+  def style_rules(options = {})
+    configure if @configuration.nil?
+    StyleRuleApi.new(api, options)
+  end
+
+  def translation_memories(options = {})
+    configure if @configuration.nil?
+    TranslationMemoryApi.new(api, options)
+  end
+
+  def rephrase(text, target_lang = nil, writing_style = nil, tone = nil, options = {}) # rubocop:disable Metrics/ParameterLists
+    configure if @configuration.nil?
+    Requests::Rephrase.new(api, text, target_lang, writing_style, tone, options).request
+  end
+
+  def usage(options = {})
+    configure if @configuration.nil?
+    Requests::Usage.new(api, options).request
+  end
+
+  def http_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
+
+    has_proxy = client_options.proxy.key?('proxy_addr') and client_options.proxy.key?('proxy_port')
+    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_client = http
+      api.update_http_client(http)
+      yield
+    ensure
+      http.finish
+    end
+  end
+
+  # -- Configuration
+
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  def configure
+    yield configuration if block_given?
+    configuration.validate!
+  end
+end

data/lib/http_client_options.rb

@@ -0,0 +1,22 @@
+# Copyright 2024 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
+  class HTTPClientOptions
+    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
+                   read_timeout: nil, write_timeout: nil, ssl_timeout: nil)
+      @proxy = proxy
+      @enable_ssl_verification = enable_ssl_verification
+      @cert_path = cert_path
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @write_timeout = write_timeout
+      @ssl_timeout = ssl_timeout
+    end
+  end
+end

data/lib/version.rb

@@ -0,0 +1,8 @@
+# Copyright 2025 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
+  VERSION = '3.7.0'
+end

data/spec/api/api_spec.rb

@@ -0,0 +1,20 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe DeepL::API do
+  subject(:api) { described_class.new(configuration) }
+
+  let(:configuration) { DeepL::Configuration.new }
+
+  describe '#initialize' do
+    context 'when building an API object' do
+      it 'saves the configuration' do
+        expect(api.configuration).to be(configuration)
+      end
+    end
+  end
+end

data/spec/api/configuration_spec.rb

@@ -0,0 +1,122 @@
+# Copyright 2018 Daniel Herzog
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+require 'logger'
+require 'spec_helper'
+
+describe DeepL::Configuration do
+  subject(:config) { described_class.new(attributes) }
+
+  let(:attributes) { {} }
+
+  around do |tests|
+    tmp_env = ENV.to_hash
+    ENV.clear
+    tests.call
+    ENV.replace(tmp_env)
+  end
+
+  describe '#initialize' do
+    context 'when using default configuration attributes' do
+      it 'uses default attributes' do
+        expect(config.auth_key).to eq(ENV.fetch('DEEPL_AUTH_KEY', nil))
+        expect(config.host).to eq('https://api.deepl.com')
+        expect(config.max_doc_status_queries).to be_nil
+        expect(config.version).to eq('v2')
+      end
+
+      it 'sends platform information' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).to include('(')
+        expect(config.user_agent).to include(')')
+        expect(config.user_agent).to include(' ruby/')
+      end
+    end
+
+    context 'when using custom configuration attributes' do
+      let(:logger) { Logger.new($stdout) }
+      let(:attributes) { { auth_key: 'SAMPLE', host: 'https://api-free.deepl.com', logger: logger, max_doc_status_queries: 42, max_network_retries: 43, version: 'v1' } }
+
+      it 'uses custom attributes' do
+        expect(config.auth_key).to eq(attributes[:auth_key])
+        expect(config.host).to eq(attributes[:host])
+        expect(config.max_doc_status_queries).to eq(attributes[:max_doc_status_queries])
+        expect(config.max_network_retries).to eq(attributes[:max_network_retries])
+        expect(config.version).to eq(attributes[:version])
+      end
+    end
+
+    context 'when using a free key' do
+      let(:attributes) { { auth_key: '123e4567-e89b-12d3-a456-426614174000:fx' } }
+
+      it 'uses the free API URL' do
+        expect(config.host).to eq('https://api-free.deepl.com')
+      end
+    end
+
+    context 'when using a pro key' do
+      let(:attributes) { { auth_key: '123e4567-e89b-12d3-a456-426614174000' } }
+
+      it 'uses the pro API URL' do
+        expect(config.host).to eq('https://api.deepl.com')
+      end
+    end
+
+    context 'when opting out of sending platform info' do
+      subject(:config) { described_class.new(attributes, nil, nil, false) }
+
+      it 'does not send platform information' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).not_to include('(')
+        expect(config.user_agent).not_to include(')')
+        expect(config.user_agent).not_to include(' ruby/')
+      end
+    end
+
+    context 'when registering an app and sending platform info' do
+      subject(:config) { described_class.new(attributes, 'MyTestApp', '0.1.3', true) }
+
+      it 'sends platform and app info' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).to include('(')
+        expect(config.user_agent).to include(')')
+        expect(config.user_agent).to include(' ruby/')
+        expect(config.user_agent).to include('MyTestApp/0.1.3')
+      end
+    end
+
+    context 'when registering an app and not sending platform info' do
+      subject(:config) { described_class.new(attributes, 'MyTestApp', '0.1.3', false) }
+
+      it 'sends app, but not platform info' do
+        expect(config.user_agent).to include('deepl-ruby/')
+        expect(config.user_agent).not_to include('(')
+        expect(config.user_agent).not_to include(')')
+        expect(config.user_agent).not_to include(' ruby/')
+        expect(config.user_agent).to include('MyTestApp/0.1.3')
+      end
+    end
+  end
+
+  describe '#validate!' do
+    let(:auth_message) { 'auth_key not provided' }
+
+    context 'when providing a valid auth key' do
+      let(:attributes) { { auth_key: '' } }
+
+      it 'raises an error' do
+        expect { config.validate! }.to raise_error(DeepL::Exceptions::Error, auth_message)
+      end
+    end
+
+    context 'when providing an invalid auth key' do
+      let(:attributes) { { auth_key: 'not-empty' } }
+
+      it 'does not raise an error' do
+        expect { config.validate! }.not_to raise_error
+      end
+    end
+  end
+end