deepl-rb 3.6.0 → 3.7.0

data/lib/deepl/constants/tone.rb

@@ -0,0 +1,20 @@
+# 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 Constants
+    class Tone < BaseConstant
+      DEFAULT = 'default'
+      ENTHUSIASTIC = 'enthusiastic'
+      FRIENDLY = 'friendly'
+      CONFIDENT = 'confident'
+      DIPLOMATIC = 'diplomatic'
+      PREFER_ENTHUSIASTIC = 'prefer_enthusiastic'
+      PREFER_FRIENDLY = 'prefer_friendly'
+      PREFER_CONFIDENT = 'prefer_confident'
+      PREFER_DIPLOMATIC = 'prefer_diplomatic'
+    end
+  end
+end

data/lib/deepl/constants/writing_style.rb

@@ -0,0 +1,20 @@
+# 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 Constants
+    class WritingStyle < BaseConstant
+      DEFAULT = 'default'
+      SIMPLE = 'simple'
+      BUSINESS = 'business'
+      ACADEMIC = 'academic'
+      CASUAL = 'casual'
+      PREFER_SIMPLE = 'prefer_simple'
+      PREFER_BUSINESS = 'prefer_business'
+      PREFER_ACADEMIC = 'prefer_academic'
+      PREFER_CASUAL = 'prefer_casual'
+    end
+  end
+end

data/lib/deepl/document_api.rb

@@ -0,0 +1,121 @@
+# 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 DocumentApi
+    def initialize(api, options = {})
+      @api = api
+      @options = options
+    end
+
+    ##
+    # Uploads the file at the given +input_file_path+ to be translated from +source_lang+ into
+    # +target_lang+. The API interface is async, so you need to poll using the returned
+    # `DeepL::Resources::DocumentHandle` until the translation is finished, then you can download it
+    #
+    # @param [String] input_file_path File path to the file to be translated
+    # @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.
+    # @param [String] target_lang Target language to use for the translation. Must be formatted as
+    #                             ISO 639-1, 2-letter language codes, plus a hyphen "-" with the
+    #                             variant identifier for languages with variants/dialects/... .
+    # @param [String, nil] filename The filename of the file, including its extension. Used to open
+    #                               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.
+    # @param [Hash] additional_headers Additional HTTP headers for the upload.
+    # @return [DeepL::Resources::DocumentHandle] Document handle for the uploaded document.
+
+    def upload(input_file_path, source_lang, target_lang, filename = nil, options = {},
+               additional_headers = {})
+      DeepL::Requests::Document::Upload.new(@api, input_file_path, source_lang, target_lang,
+                                            filename, options, additional_headers)
+                                       .request
+    end
+
+    ##
+    # Queries the status of the translation of the document with the given +document_handle+.
+    #
+    # @param [DeepL::Resources::DocumentHandle] document_handle Handle returned by the `upload`
+    # method.
+    # @param [Hash] options Additional options for the upload.
+    # @param [Hash] additional_headers Additional HTTP headers for the status check.
+    # @return [DeepL::Resources::DocumentTranslationStatus] Status of the document translation.
+
+    def get_status(document_handle, options = {}, additional_headers = {})
+      DeepL::Requests::Document::GetStatus.new(@api, document_handle.document_id,
+                                               document_handle.document_key, options,
+                                               additional_headers).request
+    end
+
+    ##
+    # Downloads the document identified by the +document_handle+ to +output_file+
+    #
+    # @param [DeepL::Resources::DocumentHandle] document_handle Handle returned by the `upload`
+    # method.
+    # @param [String] output_file Path to the file to write to. Will be overwritten if the file
+    #                             already exists.
+    # @return [DeepL::Resources::DocumentTranslationStatus] Status of the document translation.
+
+    def download(document_handle, output_file)
+      DeepL::Requests::Document::Download.new(@api, document_handle.document_id,
+                                              document_handle.document_key, output_file).request
+    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.
+    #
+    # @raise [DocumentTranslationError] If any error occurs during the process.
+    #
+    # @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, 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.
+    # @param [String] target_lang Target language to use for the translation. Must be formatted as
+    #                             ISO 639-1, 2-letter language codes, plus a hyphen "-" with the
+    #                             variant identifier for languages with variants/dialects/... .
+    # @param [String, nil] filename The filename of the file, including its extension. Used to open
+    #                               the different kinds of documents (PDFs, etc). If nil, will use
+    #                               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.
+
+    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)
+
+      begin
+        handle = upload(input_file, source_lang, target_lang, filename, options,
+                        additional_headers)
+        translate_document_wait_and_download(handle, output_file)
+      rescue StandardError => e
+        FileUtils.rm_f(output_file)
+        raise Exceptions::DocumentTranslationError.new(
+          "Error occurred during document translation: #{e.message}", handle
+        )
+      end
+    end
+
+    private
+
+    def translate_document_wait_and_download(document_handle, output_file)
+      doc_status = document_handle.wait_until_document_translation_finished
+      if doc_status.error?
+        raise Exceptions::DocumentTranslationError.new(
+          "Exception when querying document status #{doc_status.error_message}", document_handle
+        )
+      else
+        download(document_handle, output_file)
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/authorization_failed.rb

@@ -0,0 +1,14 @@
+# 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 Exceptions
+    class AuthorizationFailed < RequestError
+      def to_s
+        'Authorization failed. Please supply a valid auth_key parameter.'
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/bad_request.rb

@@ -0,0 +1,16 @@
+# 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 Exceptions
+    class BadRequest < RequestError
+      def to_s
+        JSON.parse(response.body)['message']
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/document_translation_error.rb

@@ -0,0 +1,15 @@
+# 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 Exceptions
+    class DocumentTranslationError < Error
+      def initialize(message, handle)
+        super(message)
+        @handle = handle
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/error.rb

@@ -0,0 +1,14 @@
+# 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 Exceptions
+    class Error < StandardError
+      def should_retry?
+        false
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/limit_exceeded.rb

@@ -0,0 +1,18 @@
+# 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 Exceptions
+    class LimitExceeded < RequestError
+      def to_s
+        'Limit exceeded. Please wait and send your request once again.'
+      end
+
+      def should_retry?
+        true
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/not_found.rb

@@ -0,0 +1,16 @@
+# 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 Exceptions
+    class NotFound < RequestError
+      def to_s
+        JSON.parse(response.body)['message']
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/not_supported.rb

@@ -0,0 +1,14 @@
+# 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 Exceptions
+    class NotSupported < Error
+      def initialize(msg = 'The feature is not supported')
+        super
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/quota_exceeded.rb

@@ -0,0 +1,14 @@
+# 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 Exceptions
+    class QuotaExceeded < RequestError
+      def to_s
+        'Quota exceeded. The character limit has been reached.'
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/request_entity_too_large.rb

@@ -0,0 +1,15 @@
+# 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 Exceptions
+    class RequestEntityTooLarge < RequestError
+      def to_s
+        'The request size has reached the supported limit. ' \
+          "Make sure that you're not sending more than 50 text parts."
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/request_error.rb

@@ -0,0 +1,21 @@
+# 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 Exceptions
+    class RequestError < Error
+      attr_reader :request, :response
+
+      def initialize(response)
+        super()
+        @response = response
+      end
+
+      def to_s
+        'Unknown error.'
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/server_error.rb

@@ -0,0 +1,18 @@
+# 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 Exceptions
+    class ServerError < RequestError
+      def to_s
+        'An internal server error occured. Try again after waiting a short period.'
+      end
+
+      def should_retry?
+        true
+      end
+    end
+  end
+end

data/lib/deepl/glossary_api.rb

@@ -0,0 +1,38 @@
+# 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
+  class GlossaryApi
+    def initialize(api, options = {})
+      @api = api
+      @options = options
+    end
+
+    def create(name, source_lang, target_lang, entries, options = {})
+      DeepL::Requests::Glossary::Create.new(@api, name, source_lang, target_lang, entries, options)
+                                       .request
+    end
+
+    def destroy(glossary_id, options = {})
+      DeepL::Requests::Glossary::Destroy.new(@api, glossary_id, options).request
+    end
+
+    def entries(glossary_id, options = {})
+      DeepL::Requests::Glossary::Entries.new(@api, glossary_id, options).request
+    end
+
+    def find(glossary_id, options = {})
+      DeepL::Requests::Glossary::Find.new(@api, glossary_id, options).request
+    end
+
+    def language_pairs(options = {})
+      DeepL::Requests::Glossary::LanguagePairs.new(@api, options).request
+    end
+
+    def list(options = {})
+      DeepL::Requests::Glossary::List.new(@api, options).request
+    end
+  end
+end

data/lib/deepl/requests/base.rb

@@ -0,0 +1,212 @@
+# 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 Base # rubocop:disable Metrics/ClassLength
+      attr_reader :api, :response, :options
+
+      def initialize(api, options = {}, additional_headers = {})
+        @api = api
+        @options = options
+        @additional_headers = additional_headers
+        @num_retries = 0
+        @backoff_timer = Utils::BackoffTimer.new
+      end
+
+      def request
+        raise NotImplementedError
+      end
+
+      def details
+        "HTTP Headers #{headers}"
+      end
+
+      private
+
+      def option?(name)
+        options.key?(name.to_s) || options.key?(name.to_sym)
+      end
+
+      def option(name)
+        options[name.to_s] || options[name.to_sym]
+      end
+
+      def delete_option(name)
+        options.delete(name.to_s) || options.delete(name.to_sym)
+      end
+
+      def set_option(name, value)
+        if options.key?(name.to_sym)
+          options[name.to_sym] = value
+        else
+          options[name.to_s] = value
+        end
+      end
+
+      # Returns options excluding extra_body_parameters
+      # extra_body_parameters are applied separately via apply_extra_body_parameters_* methods
+      def options_without_extra_params
+        options.reject do |k, _|
+          k.to_s == 'extra_body_parameters' || k.to_sym == :extra_body_parameters
+        end
+      end
+
+      # Apply extra body parameters to a hash payload (for JSON/form-encoded requests)
+      # Extra parameters will override existing keys
+      def apply_extra_body_parameters_to_json(payload)
+        return unless option?(:extra_body_parameters)
+
+        extra_params = option(:extra_body_parameters)
+        extra_params.each do |key, value|
+          payload[key] = value
+        end
+      end
+
+      # Apply extra body parameters to multipart form data array
+      # Extra parameters will override existing keys
+      def apply_extra_body_parameters_to_form(form_data)
+        return unless option?(:extra_body_parameters)
+
+        extra_params = option(:extra_body_parameters)
+        extra_params.each do |key, value|
+          key_str = key.to_s
+          # Remove existing key if present to allow override.
+          # Required for form data as it would be duplicated otherwise
+          form_data.reject! { |field| field[0].to_s == key_str }
+          form_data.push([key_str, value.to_s])
+        end
+      end
+
+      # Files to reset: list of file objects to rewind when retrying the request
+      def execute_request_with_retries(req, files_to_reset = []) # rubocop:disable all
+        api.configuration.logger&.info("Request to the DeepL API: #{self}")
+        api.configuration.logger&.debug("Request details: #{details}")
+        loop do
+          resp = api.http_client.request(req)
+          validate_response!(resp)
+          return [req, resp]
+        rescue DeepL::Exceptions::Error => e
+          raise e unless should_retry?(resp, e, @backoff_timer.num_retries)
+
+          unless e.nil?
+            api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
+          end
+          api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
+                                         "request #{request} after sleeping for " \
+                                         "#{format('%.2f', @backoff_timer.time_until_deadline)}")
+          files_to_reset.each(&:rewind)
+          @backoff_timer.sleep_until_deadline
+          next
+        rescue Net::HTTPBadResponse, Net::HTTPServerError, Net::HTTPFatalError, Timeout::Error,
+               SocketError => e
+          unless e.nil?
+            api.configuration.logger&.info("Encountered a retryable exception: #{e.message}")
+          end
+          api.configuration.logger&.info("Starting retry #{@backoff_timer.num_retries + 1} for " \
+                                         "request #{request} after sleeping for " \
+                                         "#{format('%.2f', @backoff_timer.time_until_deadline)}")
+          files_to_reset.each(&:rewind)
+          @backoff_timer.sleep_until_deadline
+          next
+        end
+      end
+
+      def should_retry?(response, exception, num_retries)
+        return false if num_retries >= api.configuration.max_network_retries
+        return exception.should_retry? if response.nil?
+
+        response.is_a?(Net::HTTPTooManyRequests) || response.is_a?(Net::HTTPInternalServerError)
+      end
+
+      def post_request(payload)
+        apply_extra_body_parameters_to_json(payload)
+        http_headers = add_json_content_type(headers)
+        post_req = Net::HTTP::Post.new(uri.path, http_headers)
+        post_req.body = payload.merge(options_without_extra_params).to_json
+        post_req
+      end
+
+      def post_request_with_file(form_data)
+        http_headers = add_multipart_form_content_type(headers)
+        post_req = Net::HTTP::Post.new(uri.request_uri, http_headers)
+        post_req.set_form(form_data, 'multipart/form-data')
+        post_req
+      end
+
+      def get_request # rubocop:disable Naming/AccessorMethodName
+        http_headers = add_json_content_type(headers)
+        get_req = Net::HTTP::Get.new(uri.path, http_headers)
+        get_req.body = options_without_extra_params.to_json
+        get_req
+      end
+
+      def patch_request(payload)
+        apply_extra_body_parameters_to_json(payload)
+        http_headers = add_json_content_type(headers)
+        req = Net::HTTP::Patch.new(uri.path, http_headers)
+        req.body = payload.merge(options_without_extra_params).to_json
+        req
+      end
+
+      def put_request(payload)
+        apply_extra_body_parameters_to_json(payload)
+        http_headers = add_json_content_type(headers)
+        req = Net::HTTP::Put.new(uri.path, http_headers)
+        req.body = payload.merge(options_without_extra_params).to_json
+        req
+      end
+
+      def delete_request
+        http_headers = add_json_content_type(headers)
+        del_req = Net::HTTP::Delete.new(uri.path, http_headers)
+        del_req.body = options_without_extra_params.to_json
+        del_req
+      end
+
+      def validate_response!(response)
+        return if response.is_a?(Net::HTTPSuccess)
+
+        raise Utils::ExceptionBuilder.new(response).build
+      end
+
+      def path
+        raise NotImplementedError
+      end
+
+      def url
+        "#{host}/#{api.configuration.version}/#{path}"
+      end
+
+      def uri
+        @uri ||= URI(url)
+        @uri
+      end
+
+      def host
+        api.configuration.host
+      end
+
+      def query_params
+        options
+      end
+
+      def headers
+        { 'Authorization' => "DeepL-Auth-Key #{api.configuration.auth_key}",
+          'User-Agent' => api.configuration.user_agent }.merge(@additional_headers)
+      end
+
+      def add_json_content_type(headers_to_add_to)
+        headers_to_add_to['Content-Type'] = 'application/json'
+        headers_to_add_to
+      end
+
+      def add_multipart_form_content_type(headers_to_add_to)
+        headers_to_add_to['Content-Type'] = 'multipart/form-data'
+        headers_to_add_to
+      end
+    end
+  end
+end

data/lib/deepl/requests/document/download.rb

@@ -0,0 +1,44 @@
+# 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 Requests
+    module Document
+      class Download < Base
+        attr_reader :document_id, :document_key
+
+        def initialize(api, document_id, document_key, output_file)
+          super(api, {})
+          @document_id = document_id
+          @document_key = document_key
+          @output_file = output_file
+        end
+
+        def request
+          payload = { document_key: document_key }
+          extract_file(*execute_request_with_retries(post_request(payload)))
+        end
+
+        def details
+          "HTTP Headers: #{headers}\nPayload #{{ document_key: document_key }}"
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
+        end
+
+        private
+
+        def extract_file(_request, response)
+          File.write(@output_file, response.body)
+        end
+
+        def path
+          "document/#{document_id}/result"
+        end
+      end
+    end
+  end
+end