deepl-rb 3.8.0 → 3.9.0

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

data/lib/deepl/resources/translation_memory_job.rb

@@ -0,0 +1,142 @@
+# 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
+    ##
+    # The outcome of a translation memory import or export job.
+
+    class TranslationMemoryJobResult
+      STATUS_AWAITING_INPUT = 'awaiting_input'
+      STATUS_PROCESSING = 'processing'
+      STATUS_COMPLETED = 'completed'
+      STATUS_DOWNLOADED = 'downloaded'
+      STATUS_FAILED = 'failed'
+      STATUS_EXPIRED = 'expired'
+
+      attr_reader :status, :required_action, :download_url, :expires_at, :error_message,
+                  :translation_memory_id, :skipped_segment_count
+
+      def initialize(result)
+        status_metadata = result['status_metadata'] || {}
+        error = result['error'] || {}
+
+        @status = result['status']
+        @required_action = status_metadata['required_action']
+        @download_url = result['download_url']
+        @expires_at = Utils::TimeParser.parse_optional_time(result['expires_at'])
+        @error_message = error['message']
+        @translation_memory_id = result['translation_memory_id']
+        @skipped_segment_count = result['skipped_segment_count']
+      end
+
+      ##
+      # Checks if the job 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?
+        [STATUS_COMPLETED, STATUS_DOWNLOADED, STATUS_FAILED, STATUS_EXPIRED].include?(status)
+      end
+
+      ##
+      # Checks if the job is still waiting for the TMX file to be uploaded. Note that the API
+      # detects an upload asynchronously, so a job keeps reporting this status for a while after
+      # its file has been uploaded.
+      #
+      # @return [true] if so
+
+      def awaiting_input?
+        status == STATUS_AWAITING_INPUT
+      end
+
+      ##
+      # Checks if there was an error during the job, including it having expired.
+      #
+      # @return [true] if so
+
+      def error?
+        [STATUS_FAILED, STATUS_EXPIRED].include?(status)
+      end
+
+      def to_s
+        "TranslationMemoryJobResult: Status: #{status} - Error message: #{error_message}"
+      end
+    end
+
+    ##
+    # Status of a translation memory import or export job. The API returns exactly one result.
+
+    class TranslationMemoryJob < Base
+      OPERATION_IMPORT = 'import'
+      OPERATION_EXPORT = 'export'
+
+      attr_reader :job_id, :product, :operation, :creation_time, :updated_time, :results,
+                  :translation_memory_id, :display_name, :source_content_type,
+                  :source_content_length
+
+      def initialize(job, *args)
+        super(*args)
+        extract_basic_fields(job)
+        extract_parameters(job)
+        @results = (job['results'] || []).map { |result| TranslationMemoryJobResult.new(result) }
+      end
+
+      ##
+      # The single result of the job, or nil if the API returned none.
+      #
+      # @return [DeepL::Resources::TranslationMemoryJobResult, nil]
+
+      def result
+        results.first
+      end
+
+      def status
+        result&.status
+      end
+
+      def finished?
+        result ? result.finished? : false
+      end
+
+      def awaiting_input?
+        result ? result.awaiting_input? : false
+      end
+
+      def error?
+        result ? result.error? : false
+      end
+
+      def error_message
+        result&.error_message
+      end
+
+      def to_s
+        "TranslationMemoryJob: #{operation} - ID: #{job_id} - Status: #{status}"
+      end
+
+      private
+
+      def extract_basic_fields(job)
+        @job_id = job['job_id']
+        @product = job['product']
+        @operation = job['operation']
+        @creation_time = Utils::TimeParser.parse_optional_time(job['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_time(job['updated_time'])
+      end
+
+      def extract_parameters(job)
+        parameters = job['parameters'] || {}
+        source_file = job['source_file'] || {}
+
+        @translation_memory_id = parameters['translation_memory_id']
+        @display_name = parameters['display_name']
+        @source_content_type = source_file['content_type']
+        @source_content_length = source_file['content_length']
+      end
+    end
+  end
+end