deepl-rb 3.7.0 → 3.9.0

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

@@ -49,10 +49,59 @@ module DeepL
           ]
           filename_param = filename || File.basename(input_file_path)
           form_data.push(['filename', filename_param]) unless filename_param.nil?
-          add_supported_options_to_form(form_data)
+          add_extra_options_to_form(form_data)
           form_data
         end
 
+        def add_extra_options_to_form(form_data)
+          add_supported_options_to_form(form_data)
+          add_glossary_ids_to_form(form_data)
+          add_style_rule_to_form(form_data)
+          add_translation_memory_to_form(form_data)
+          add_translation_memory_threshold_to_form(form_data)
+        end
+
+        # Validates and serializes the `glossary_ids` option (see
+        # `DeepL::Requests::Base#build_glossary_ids_param`) and appends it to the form data as a
+        # comma-separated `glossary_ids` field. Requires `source_lang`, cannot be combined with
+        # the singular `glossary_id` option, and allows at most 5 IDs.
+        def add_glossary_ids_to_form(form_data)
+          glossary_ids = build_glossary_ids_param(source_lang)
+          form_data.push(['glossary_ids', glossary_ids.join(',')]) unless glossary_ids.nil?
+        end
+
+        # Serializes the `style_rule` option and appends it to the form data as a `style_id`
+        # field. Mirrors text translation: accepts either a style rule ID string or a
+        # `DeepL::Resources::StyleRule` object.
+        def add_style_rule_to_form(form_data)
+          return unless option?(:style_rule)
+
+          rule = delete_option(:style_rule)
+          style_id = rule.is_a?(DeepL::Resources::StyleRule) ? rule.style_id : rule
+          form_data.push(['style_id', style_id.to_s])
+        end
+
+        # Serializes the `translation_memory` option and appends it to the form data as a
+        # `translation_memory_id` field. Mirrors text translation: the `translation_memory`
+        # option accepts either a translation memory ID string or a
+        # `DeepL::Resources::TranslationMemory` object.
+        def add_translation_memory_to_form(form_data)
+          return unless option?(:translation_memory)
+
+          tm = delete_option(:translation_memory)
+          tm_id = tm.is_a?(DeepL::Resources::TranslationMemory) ? tm.translation_memory_id : tm
+          form_data.push(['translation_memory_id', tm_id.to_s])
+        end
+
+        # Serializes the `translation_memory_threshold` option (integer 0-100) and appends it to
+        # the form data as a `translation_memory_threshold` field, mirroring text translation.
+        def add_translation_memory_threshold_to_form(form_data)
+          return unless option?(:translation_memory_threshold)
+
+          threshold = delete_option(:translation_memory_threshold)
+          form_data.push(['translation_memory_threshold', threshold.to_s])
+        end
+
         def add_supported_options_to_form(form_data)
           SUPPORTED_OPTIONS.each do |option_name|
             option_value = option(option_name)

data/lib/deepl/requests/rephrase.rb

@@ -8,8 +8,9 @@ module DeepL
     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)
+      def initialize(api, text, target_lang = nil, writing_style = nil, tone = nil, options = {}, # rubocop:disable Metrics/ParameterLists
+                     additional_headers = {})
+        super(api, options, additional_headers)
         @text = text
         @target_lang = target_lang
         @writing_style = writing_style

data/lib/deepl/requests/translate.rb

@@ -30,8 +30,8 @@ module DeepL
       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)
+      def initialize(api, text, source_lang, target_lang, options = {}, additional_headers = {})
+        super(api, options, additional_headers)
         @text = text
         @source_lang = source_lang
         @target_lang = target_lang
@@ -39,7 +39,7 @@ module DeepL
         tweak_parameters!
       end
 
-      def request # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def request # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
         text_arrayified = text.is_a?(Array) ? text : [text]
         payload = { text: text_arrayified, source_lang: source_lang, target_lang: target_lang }
 
@@ -65,6 +65,9 @@ module DeepL
           payload[:translation_memory_threshold] = delete_option(:translation_memory_threshold)
         end
 
+        glossary_ids = build_glossary_ids_param(source_lang)
+        payload[:glossary_ids] = glossary_ids unless glossary_ids.nil?
+
         build_texts(*execute_request_with_retries(post_request(payload)))
       end
 

data/lib/deepl/requests/translation_memory/base.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 TranslationMemory
+      ##
+      # Common behaviour of the translation memory endpoints: they are served under the `v3`
+      # prefix instead of the configured API version, and take their parameters in the query
+      # string rather than in the request body.
+
+      class Base < DeepL::Requests::Base
+        private
+
+        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
+          # encode_www_form encodes a space as `+`, which is correct for a form body but not for
+          # a URI query string. A literal `+` is already escaped as %2B, so every remaining `+`
+          # is a space.
+          URI.encode_www_form(query_params).gsub('+', '%20')
+        end
+
+        def query_params
+          {}
+        end
+
+        def get_request # rubocop:disable Naming/AccessorMethodName
+          Net::HTTP::Get.new(uri.request_uri, add_json_content_type(headers))
+        end
+
+        def delete_request
+          Net::HTTP::Delete.new(uri.request_uri, add_json_content_type(headers))
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/create_export.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 TranslationMemory
+      class CreateExport < Base
+        attr_reader :translation_memory_id
+
+        def initialize(api, translation_memory_id, options = {})
+          super(api, options)
+          @translation_memory_id = translation_memory_id
+        end
+
+        def request
+          build_translation_memory_export(*execute_request_with_retries(post_request({})))
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
+        end
+
+        private
+
+        def build_translation_memory_export(request, response)
+          data = JSON.parse(response.body)
+          # The API answers 200 when it reused a previously completed export, and 202 when it
+          # started a new one.
+          reused_existing = response.code.to_i == 200
+          Resources::TranslationMemoryExport.new(data, reused_existing, request, response)
+        end
+
+        def path
+          "translation_memories/#{translation_memory_id}/export"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/create_import.rb

@@ -0,0 +1,53 @@
+# 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 CreateImport < Base
+        attr_reader :file_name, :content_length
+
+        def initialize(api, file_name, content_length, options = {}, additional_headers = {})
+          super(api, options, additional_headers)
+          @file_name = file_name
+          @content_length = content_length
+          @content_type = delete_option(:content_type)
+          @display_name = delete_option(:display_name)
+        end
+
+        def request
+          build_translation_memory_import(*execute_request_with_retries(post_request(payload)))
+        end
+
+        def details
+          "HTTP Headers: #{headers}\nPayload #{payload}"
+        end
+
+        def to_s
+          "POST #{uri.request_uri}"
+        end
+
+        private
+
+        def payload
+          source_file = { file_name: file_name, content_length: content_length }
+          source_file[:content_type] = @content_type if @content_type
+          payload = { source_file: source_file }
+          payload[:parameters] = { display_name: @display_name } if @display_name
+          payload
+        end
+
+        def build_translation_memory_import(request, response)
+          data = JSON.parse(response.body)
+          Resources::TranslationMemoryImport.new(data, request, response)
+        end
+
+        def path
+          'translation_memories/import'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/destroy.rb

@@ -0,0 +1,37 @@
+# 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 Destroy < Base
+        attr_reader :translation_memory_id
+
+        def initialize(api, translation_memory_id, options = {})
+          super(api, options)
+          @translation_memory_id = translation_memory_id
+        end
+
+        def request
+          build_response(*execute_request_with_retries(delete_request))
+        end
+
+        def to_s
+          "DELETE #{uri.request_uri}"
+        end
+
+        private
+
+        def build_response(_, _)
+          translation_memory_id
+        end
+
+        def path
+          "translation_memories/#{translation_memory_id}"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/download_export.rb

@@ -0,0 +1,35 @@
+# 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 DownloadExport < StorageBase
+        def initialize(api, download_url, output_file)
+          super(api, download_url)
+          @output_file = output_file
+        end
+
+        def request
+          extract_file(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
+        end
+
+        private
+
+        def get_request # rubocop:disable Naming/AccessorMethodName
+          Net::HTTP::Get.new(uri.request_uri, headers)
+        end
+
+        def extract_file(_request, response)
+          File.binwrite(@output_file, response.body)
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/find.rb

@@ -0,0 +1,38 @@
+# 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 Find < Base
+        attr_reader :translation_memory_id
+
+        def initialize(api, translation_memory_id, options = {})
+          super(api, options)
+          @translation_memory_id = translation_memory_id
+        end
+
+        def request
+          build_translation_memory(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
+        end
+
+        private
+
+        def build_translation_memory(request, response)
+          data = JSON.parse(response.body)
+          Resources::TranslationMemory.new(data, request, response)
+        end
+
+        def path
+          "translation_memories/#{translation_memory_id}"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/find_job.rb

@@ -0,0 +1,38 @@
+# 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 FindJob < Base
+        attr_reader :job_id
+
+        def initialize(api, job_id, options = {})
+          super(api, options)
+          @job_id = job_id
+        end
+
+        def request
+          build_job(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
+        end
+
+        private
+
+        def build_job(request, response)
+          data = JSON.parse(response.body)
+          Resources::TranslationMemoryJob.new(data, request, response)
+        end
+
+        def path
+          "translation_memories/jobs/#{job_id}"
+        end
+      end
+    end
+  end
+end

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

@@ -7,6 +7,8 @@ module DeepL
   module Requests
     module TranslationMemory
       class List < Base
+        SUPPORTED_OPTIONS = %w[page page_size].freeze
+
         def initialize(api, options = {})
           super
         end
@@ -21,11 +23,6 @@ module DeepL
 
         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|
@@ -33,22 +30,12 @@ module DeepL
           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
+        def query_params
+          SUPPORTED_OPTIONS.each_with_object({}) do |option_name, params|
+            params[option_name] = option(option_name).to_s if option?(option_name)
           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

data/lib/deepl/requests/translation_memory/segments.rb

@@ -0,0 +1,46 @@
+# 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 Segments < Base
+        SUPPORTED_OPTIONS = %w[page_size page_cursor filter_text filter_case_sensitive].freeze
+
+        attr_reader :translation_memory_id
+
+        def initialize(api, translation_memory_id, options = {})
+          super(api, options)
+          @translation_memory_id = translation_memory_id
+        end
+
+        def request
+          build_segments(*execute_request_with_retries(get_request))
+        end
+
+        def to_s
+          "GET #{uri.request_uri}"
+        end
+
+        private
+
+        def build_segments(request, response)
+          data = JSON.parse(response.body)
+          Resources::TranslationMemorySegments.new(data, request, response)
+        end
+
+        def query_params
+          SUPPORTED_OPTIONS.each_with_object({}) do |option_name, params|
+            params[option_name] = option(option_name).to_s if option?(option_name)
+          end
+        end
+
+        def path
+          "translation_memories/#{translation_memory_id}/segments"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/storage_base.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 TranslationMemory
+      ##
+      # Common behaviour of the requests to a pre-signed storage URL handed out by the API, such
+      # as a translation memory upload or download URL. Those URLs point outside of the DeepL
+      # API, so they are requested over their own connection and the DeepL `Authorization` header
+      # is deliberately not sent.
+
+      class StorageBase < DeepL::Requests::Base
+        attr_reader :storage_url
+
+        def initialize(api, storage_url, options = {}, additional_headers = {})
+          super(api, options, additional_headers)
+          if storage_url.nil? || storage_url.empty?
+            raise Exceptions::Error, 'Storage URL must not be empty'
+          end
+
+          @storage_url = storage_url
+        end
+
+        private
+
+        def http_client
+          @http_client ||= begin
+            client = Net::HTTP.new(uri.host, uri.port)
+            client.use_ssl = uri.scheme == 'https'
+            client
+          end
+        end
+
+        def uri
+          @uri ||= URI(storage_url)
+        end
+
+        def headers
+          { 'User-Agent' => api.configuration.user_agent }.merge(@additional_headers)
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/translation_memory/upload_file.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 TranslationMemory
+      class UploadFile < StorageBase
+        DEFAULT_CONTENT_TYPE = 'application/xml'
+
+        attr_reader :file_content, :content_type
+
+        def initialize(api, upload_url, file_content, content_type = DEFAULT_CONTENT_TYPE)
+          super(api, upload_url)
+          @file_content = file_content
+          @content_type = content_type || DEFAULT_CONTENT_TYPE
+        end
+
+        def request
+          build_response(*execute_request_with_retries(put_request))
+        end
+
+        def details
+          "HTTP Headers: #{headers}\nPayload #{file_content.bytesize} byte(s)"
+        end
+
+        def to_s
+          "PUT #{uri.request_uri}"
+        end
+
+        private
+
+        def put_request
+          put_req = Net::HTTP::Put.new(uri.request_uri,
+                                       headers.merge('Content-Type' => content_type))
+          put_req.body = file_content
+          put_req
+        end
+
+        def build_response(_, _)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/deepl/resources/translation_memory.rb

@@ -6,7 +6,8 @@
 module DeepL
   module Resources
     class TranslationMemory < Base
-      attr_reader :translation_memory_id, :name, :source_language, :target_languages, :segment_count
+      attr_reader :translation_memory_id, :name, :source_language, :target_languages,
+                  :segment_count, :creation_time, :updated_time
 
       def initialize(translation_memory, *args)
         super(*args)
@@ -15,6 +16,8 @@ module DeepL
         @source_language = translation_memory['source_language']
         @target_languages = translation_memory['target_languages'] || []
         @segment_count = translation_memory['segment_count'] || 0
+        @creation_time = Utils::TimeParser.parse_optional_time(translation_memory['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_time(translation_memory['updated_time'])
       end
 
       def to_s

data/lib/deepl/resources/translation_memory_export.rb

@@ -0,0 +1,37 @@
+# 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
+    ##
+    # A translation memory export job. Poll the job until it is finished to obtain the download
+    # URL of the exported TMX file.
+
+    class TranslationMemoryExport < Base
+      attr_reader :job_id, :translation_memory_id
+
+      def initialize(translation_memory_export, reused_existing, *args)
+        super(*args)
+        parameters = translation_memory_export['parameters'] || {}
+        @job_id = translation_memory_export['job_id']
+        @translation_memory_id = parameters['translation_memory_id']
+        @reused_existing = reused_existing
+      end
+
+      ##
+      # Checks if the API reused a previously completed export instead of starting a new one.
+      #
+      # @return [true] if so
+
+      def reused_existing?
+        @reused_existing
+      end
+
+      def to_s
+        "TranslationMemoryExport: ID: #{job_id}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/translation_memory_import.rb

@@ -0,0 +1,29 @@
+# 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
+    ##
+    # A newly created translation memory import job. The TMX file must be uploaded to
+    # `upload_url` before `expires_at`, processing starts once the upload is detected.
+
+    class TranslationMemoryImport < Base
+      attr_reader :job_id, :upload_url, :expires_at
+
+      def initialize(translation_memory_import, *args)
+        super(*args)
+        @job_id = translation_memory_import['job_id']
+        @upload_url = translation_memory_import['upload_url']
+        @expires_at = Utils::TimeParser.parse_optional_time(
+          translation_memory_import['expires_at']
+        )
+      end
+
+      def to_s
+        "TranslationMemoryImport: ID: #{job_id}"
+      end
+    end
+  end
+end