deepl-rb 3.6.0 → 3.6.1

data/lib/deepl/requests/rephrase.rb

@@ -0,0 +1,55 @@
+# 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
+  module Requests
+    class Rephrase < Base
+      attr_reader :text, :target_lang, :writing_style, :tone
+
+      def initialize(api, text, target_lang = nil, writing_style = nil, tone = nil, options = {}) # rubocop:disable Metrics/ParameterLists
+        super(api, options)
+        @text = text
+        @target_lang = target_lang
+        @writing_style = writing_style
+        @tone = tone
+      end
+
+      def request # rubocop:disable Metrics/AbcSize
+        text_arrayified = text.is_a?(Array) ? text : [text]
+        payload = { text: text_arrayified }
+        payload[:target_lang] = target_lang unless target_lang.nil?
+        payload[:writing_style] = writing_style unless writing_style.nil?
+        payload[:tone] = tone unless tone.nil?
+        build_texts(*execute_request_with_retries(post_request(payload)))
+      end
+
+      def details
+        "HTTP Headers: #{headers}\nPayload #{{ text: text, target_lang: target_lang,
+                                               writing_style: writing_style, tone: tone }}"
+      end
+
+      def to_s
+        "POST #{uri.request_uri}"
+      end
+
+      private
+
+      def build_texts(request, response)
+        data = JSON.parse(response.body)
+
+        texts = data['improvements'].map do |improvement|
+          Resources::Text.new(improvement['text'], improvement['detected_source_language'], nil,
+                              request, response)
+        end
+
+        texts.size == 1 ? texts.first : texts
+      end
+
+      def path
+        'write/rephrase'
+      end
+    end
+  end
+end

data/lib/deepl/requests/style_rule/list.rb

@@ -0,0 +1,59 @@
+# 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
+  module Requests
+    module StyleRule
+      class List < Base
+        def initialize(api, options = {})
+          super
+        end
+
+        def request
+          build_style_rule_list(*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
+
+        def build_style_rule_list(request, response)
+          data = JSON.parse(response.body)
+          data['style_rules'].map do |style_rule|
+            Resources::StyleRule.new(style_rule, request, response)
+          end
+        end
+
+        def uri
+          @uri ||= begin
+            base_uri = URI("#{host}/v3/#{path}")
+            query_string = build_query_string
+            base_uri.query = query_string unless query_string.empty?
+            base_uri
+          end
+        end
+
+        def build_query_string
+          params = {}
+          params['page'] = option(:page).to_s if option?(:page)
+          params['page_size'] = option(:page_size).to_s if option?(:page_size)
+          params['detailed'] = option(:detailed).to_s.downcase if option?(:detailed)
+          URI.encode_www_form(params)
+        end
+
+        def path
+          'style_rules'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translate.rb

@@ -0,0 +1,93 @@
+# 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 Requests
+    class Translate < Base
+      STRING_TO_BOOLEAN_MAP = { '1' => true, '0' => false }.freeze
+      BOOLEAN_TO_STRING_MAP = { true => '1', false => '0' }.freeze
+      STRING_TO_BOOLEAN_CONVERSION = ->(value) { STRING_TO_BOOLEAN_MAP[value] }
+      BOOLEAN_TO_STRING_CONVERSION = ->(value) { BOOLEAN_TO_STRING_MAP[value] }
+      STRING_TO_ARRAY_CONVERSION = lambda { |value|
+        if value.nil?
+          nil
+        else
+          (value.is_a?(Array) ? value : value.split(','))
+        end
+      }.freeze
+      OPTIONS_CONVERSIONS = {
+        split_sentences: BOOLEAN_TO_STRING_CONVERSION,
+        preserve_formatting: STRING_TO_BOOLEAN_CONVERSION,
+        outline_detection: STRING_TO_BOOLEAN_CONVERSION,
+        splitting_tags: STRING_TO_ARRAY_CONVERSION,
+        non_splitting_tags: STRING_TO_ARRAY_CONVERSION,
+        ignore_tags: STRING_TO_ARRAY_CONVERSION,
+        custom_instructions: STRING_TO_ARRAY_CONVERSION
+      }.freeze
+
+      attr_reader :text, :source_lang, :target_lang, :ignore_tags, :splitting_tags,
+                  :non_splitting_tags, :model_type, :custom_instructions, :tag_handling_version
+
+      def initialize(api, text, source_lang, target_lang, options = {})
+        super(api, options)
+        @text = text
+        @source_lang = source_lang
+        @target_lang = target_lang
+
+        tweak_parameters!
+      end
+
+      def request # rubocop:disable Metrics/MethodLength
+        text_arrayified = text.is_a?(Array) ? text : [text]
+        payload = { text: text_arrayified, source_lang: source_lang, target_lang: target_lang }
+
+        if option?(:style_rule)
+          style_rule = option(:style_rule)
+          payload[:style_id] = if style_rule.is_a?(DeepL::Resources::StyleRule)
+                                 style_rule.style_id
+                               else
+                                 style_rule.to_s
+                               end
+        end
+
+        build_texts(*execute_request_with_retries(post_request(payload)))
+      end
+
+      def details
+        "HTTP Headers: #{headers}\nPayload #{{ text: text, source_lang: source_lang,
+                                               target_lang: target_lang }}"
+      end
+
+      def to_s
+        "POST #{uri.request_uri}"
+      end
+
+      private
+
+      def tweak_parameters!
+        OPTIONS_CONVERSIONS.each do |param, converter|
+          next unless option?(param) && !converter[option(param)].nil?
+
+          set_option(param, converter[option(param)])
+        end
+      end
+
+      def build_texts(request, response)
+        data = JSON.parse(response.body)
+
+        texts = data['translations'].map do |translation|
+          Resources::Text.new(translation['text'], translation['detected_source_language'],
+                              translation['model_type_used'], request, response)
+        end
+
+        texts.size == 1 ? texts.first : texts
+      end
+
+      def path
+        'translate'
+      end
+    end
+  end
+end

data/lib/deepl/requests/usage.rb

@@ -0,0 +1,33 @@
+# 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 Requests
+    class Usage < Base
+      def initialize(api, options = {})
+        super
+      end
+
+      def request
+        build_usage(*execute_request_with_retries(get_request))
+      end
+
+      def to_s
+        "GET #{uri.request_uri}"
+      end
+
+      private
+
+      def build_usage(request, response)
+        data = JSON.parse(response.body)
+        Resources::Usage.new(data['character_count'], data['character_limit'], request, response)
+      end
+
+      def path
+        'usage'
+      end
+    end
+  end
+end

data/lib/deepl/resources/base.rb

@@ -0,0 +1,17 @@
+# 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 Base
+      attr_reader :request, :response
+
+      def initialize(request, response)
+        @request = request
+        @response = response
+      end
+    end
+  end
+end

data/lib/deepl/resources/document_handle.rb

@@ -0,0 +1,57 @@
+# 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 Resources
+    class DocumentHandle < Base
+      attr_reader :document_id, :document_key
+
+      def initialize(document_id, document_key, *args)
+        super(*args)
+
+        @document_id = document_id
+        @document_key = document_key
+      end
+
+      def to_s
+        "DocumentHandle: ID: #{document_id} - Key: #{document_key}"
+      end
+
+      ##
+      # For this DocumentHandle, waits until the document translation is finished and returns the
+      # final status of the document.
+      #
+      # @return [DeepL::Resources::DocumentTranslationStatus] Final status of the document
+      #                                                       translation.
+
+      def wait_until_document_translation_finished
+        doc_status = nil
+        max_tries = max_doc_status_queries
+        num_tries = 0
+        loop do
+          num_tries += 1
+          sleep(calculate_waiting_time(doc_status)) unless doc_status.nil?
+          doc_status = DeepL.document.get_status(self)
+          break if doc_status.finished? || num_tries > max_tries
+        end
+        doc_status
+      end
+
+      private
+
+      def calculate_waiting_time(_resp)
+        # ignore _resp.seconds_remaining for now, while it is unreliable
+        5
+      end
+
+      def max_doc_status_queries
+        configured_value = DeepL.configuration.max_doc_status_queries
+        return configured_value unless configured_value.nil?
+
+        10
+      end
+    end
+  end
+end

data/lib/deepl/resources/document_translation_status.rb

@@ -0,0 +1,54 @@
+# 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 Resources
+    class DocumentTranslationStatus < Base
+      attr_reader :document_id, :status, :seconds_remaining, :billed_characters, :error_message
+
+      def initialize(response, *args)
+        super(*args)
+
+        @document_id = response['document_id']
+        @status = response['status']
+        @seconds_remaining = response['seconds_remaining']
+        @billed_characters = response['billed_characters']
+        @error_message = response['error_message']
+      end
+
+      def to_s
+        "DocumentTranslationStatus: ID: #{document_id} - Status: #{status} " \
+          "- Error message: #{error_message}"
+      end
+
+      ##
+      # Checks if the translation finished successfully
+      #
+      # @return [true] if so
+
+      def successful?
+        status == 'done'
+      end
+
+      ##
+      # Checks if there was an error during translation
+      #
+      # @return [true] if so
+
+      def error?
+        status == 'error'
+      end
+
+      ##
+      # Checks if the translation process terminated. Note that this could be due to an error as
+      # well, but means no further waiting is necessary.
+      #
+      # @return [true] if so
+      def finished?
+        successful? || error?
+      end
+    end
+  end
+end

data/lib/deepl/resources/glossary.rb

@@ -0,0 +1,28 @@
+# 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 Resources
+    class Glossary < Base
+      attr_reader :id, :name, :ready, :source_lang, :target_lang, :creation_time, :entry_count
+
+      def initialize(glossary, *args)
+        super(*args)
+
+        @id = glossary['glossary_id']
+        @name = glossary['name']
+        @ready = glossary['ready']
+        @source_lang = glossary['source_lang']
+        @target_lang = glossary['target_lang']
+        @creation_time = glossary['creation_time']
+        @entry_count = glossary['entry_count']
+      end
+
+      def to_s
+        "#{id} - #{name}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/language.rb

@@ -0,0 +1,30 @@
+# Copyright 2021 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 Language < Base
+      attr_reader :code, :name
+
+      def initialize(code, name, supports_formality, *args)
+        super(*args)
+
+        @code = code
+        @name = name
+        @supports_formality = supports_formality
+      end
+
+      def to_s
+        "#{code} - #{name}"
+      end
+
+      def supports_formality?
+        return @supports_formality unless @supports_formality.nil?
+
+        raise Exceptions::NotSupported, 'Support formality is only available on target languages'
+      end
+    end
+  end
+end

data/lib/deepl/resources/language_pair.rb

@@ -0,0 +1,23 @@
+# 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 Resources
+    class LanguagePair < Base
+      attr_reader :source_lang, :target_lang
+
+      def initialize(source_lang, target_lang, *args)
+        super(*args)
+
+        @source_lang = source_lang
+        @target_lang = target_lang
+      end
+
+      def to_s
+        "#{source_lang} - #{target_lang}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/style_rule.rb

@@ -0,0 +1,85 @@
+# 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 :label, :prompt, :source_language
+
+      def initialize(custom_instruction_data)
+        @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/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,17 @@
+# 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
+  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