deepl-rb 3.6.0 → 3.7.0

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

@@ -0,0 +1,41 @@
+# 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 Requests
+    module StyleRule
+      class FindCustomInstruction < Base
+        def initialize(api, style_id, instruction_id, options = {})
+          super(api, options)
+          @style_id = style_id
+          @instruction_id = instruction_id
+        end
+
+        def request
+          build_custom_instruction(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
+        end
+
+        private
+
+        def build_custom_instruction(_request, response)
+          data = JSON.parse(response.body)
+          DeepL::Resources::CustomInstruction.new(data)
+        end
+
+        def uri
+          @uri ||= URI("#{host}/v3/#{path}")
+        end
+
+        def path
+          "style_rules/#{@style_id}/custom_instructions/#{@instruction_id}"
+        end
+      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/style_rule/update.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
+  module Requests
+    module StyleRule
+      class Update < Base
+        def initialize(api, style_id, name, options = {})
+          super(api, options)
+          @style_id = style_id
+          @name = name
+        end
+
+        def request
+          payload = { name: @name }
+          build_style_rule(*execute_request_with_retries(patch_request(payload)))
+        end
+
+        def to_s
+          "PATCH #{uri.request_uri}"
+        end
+
+        private
+
+        def build_style_rule(request, response)
+          data = JSON.parse(response.body)
+          DeepL::Resources::StyleRule.new(data, request, response)
+        end
+
+        def uri
+          @uri ||= URI("#{host}/v3/#{path}")
+        end
+
+        def path
+          "style_rules/#{@style_id}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# 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 Requests
+    module StyleRule
+      class UpdateConfiguredRules < Base
+        def initialize(api, style_id, configured_rules, options = {})
+          super(api, options)
+          @style_id = style_id
+          @configured_rules = configured_rules
+        end
+
+        def request
+          build_style_rule(*execute_request_with_retries(put_request(@configured_rules)))
+        end
+
+        def to_s
+          "PUT #{uri.request_uri}"
+        end
+
+        private
+
+        def build_style_rule(request, response)
+          data = JSON.parse(response.body)
+          DeepL::Resources::StyleRule.new(data, request, response)
+        end
+
+        def uri
+          @uri ||= URI("#{host}/v3/#{path}")
+        end
+
+        def path
+          "style_rules/#{@style_id}/configured_rules"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# 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 Requests
+    module StyleRule
+      class UpdateCustomInstruction < Base
+        def initialize(api, style_id, instruction_id, label, prompt, # rubocop:disable Metrics/ParameterLists
+                       source_language = nil, options = {})
+          super(api, options)
+          @style_id = style_id
+          @instruction_id = instruction_id
+          @label = label
+          @prompt = prompt
+          @source_language = source_language
+        end
+
+        def request
+          payload = { label: @label, prompt: @prompt }
+          payload[:source_language] = @source_language if @source_language
+          build_custom_instruction(*execute_request_with_retries(put_request(payload)))
+        end
+
+        def to_s
+          "PUT #{uri.request_uri}"
+        end
+
+        private
+
+        def build_custom_instruction(_request, response)
+          data = JSON.parse(response.body)
+          DeepL::Resources::CustomInstruction.new(data)
+        end
+
+        def uri
+          @uri ||= URI("#{host}/v3/#{path}")
+        end
+
+        def path
+          "style_rules/#{@style_id}/custom_instructions/#{@instruction_id}"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translate.rb

@@ -0,0 +1,106 @@
+# 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/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+        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 = delete_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
+
+        if option?(:translation_memory)
+          tm = delete_option(:translation_memory)
+          payload[:translation_memory_id] = if tm.is_a?(DeepL::Resources::TranslationMemory)
+                                              tm.translation_memory_id
+                                            else
+                                              tm.to_s
+                                            end
+        end
+
+        if option?(:translation_memory_threshold)
+          payload[:translation_memory_threshold] = delete_option(:translation_memory_threshold)
+        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/translation_memory/list.rb

@@ -0,0 +1,58 @@
+# 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 Requests
+    module TranslationMemory
+      class List < Base
+        def initialize(api, options = {})
+          super
+        end
+
+        def request
+          build_translation_memory_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_translation_memory_list(request, response)
+          data = JSON.parse(response.body)
+          data['translation_memories'].map do |tm|
+            Resources::TranslationMemory.new(tm, 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)
+          URI.encode_www_form(params)
+        end
+
+        def path
+          'translation_memories'
+        end
+      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