deepl-rb 3.7.0 → 3.9.0

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

data/lib/deepl/resources/translation_memory_segments.rb

@@ -0,0 +1,78 @@
+# 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
+    class TranslationMemoryTargetSegment
+      attr_reader :target_segment_id, :target_language, :target_text, :creation_time,
+                  :updated_time, :last_used_time
+
+      def initialize(target_segment)
+        @target_segment_id = target_segment['target_segment_id']
+        @target_language = target_segment['target_language']
+        @target_text = target_segment['target_text']
+        @creation_time = Utils::TimeParser.parse_optional_time(target_segment['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_time(target_segment['updated_time'])
+        @last_used_time = Utils::TimeParser.parse_optional_time(target_segment['last_used_time'])
+      end
+
+      def to_s
+        "#{target_language}: #{target_text}"
+      end
+    end
+
+    class TranslationMemorySegment
+      attr_reader :source_segment_id, :source_text, :targets, :creation_time, :updated_time,
+                  :last_used_time
+
+      def initialize(segment)
+        @source_segment_id = segment['source_segment_id']
+        @source_text = segment['source_text']
+        @targets = (segment['targets'] || []).map do |target|
+          TranslationMemoryTargetSegment.new(target)
+        end
+        @creation_time = Utils::TimeParser.parse_optional_time(segment['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_time(segment['updated_time'])
+        @last_used_time = Utils::TimeParser.parse_optional_time(segment['last_used_time'])
+      end
+
+      def to_s
+        "#{source_segment_id} - #{source_text}"
+      end
+    end
+
+    ##
+    # One page of the segments of a translation memory. Pagination is cursor-based: pass
+    # `next_page_cursor` as the `page_cursor` option of the next request until it is nil.
+
+    class TranslationMemorySegments < Base
+      attr_reader :segments, :segment_count, :next_page_cursor
+
+      def initialize(segments_response, *args)
+        super(*args)
+        @segments = (segments_response['segments'] || []).map do |segment|
+          TranslationMemorySegment.new(segment)
+        end
+        # Note that this is the number of segments stored in the translation memory, it is not
+        # reduced by a text filter.
+        @segment_count = segments_response['segment_count'] || 0
+        @next_page_cursor = segments_response['next_page_cursor']
+      end
+
+      ##
+      # Checks whether another page of segments can be requested.
+      #
+      # @return [true] if so
+
+      def next_page?
+        !next_page_cursor.nil?
+      end
+
+      def to_s
+        "#{segments.size} of #{segment_count} segment(s)"
+      end
+    end
+  end
+end

data/lib/deepl/translation_memory_api.rb

@@ -4,14 +4,306 @@
 # frozen_string_literal: true
 
 module DeepL
-  class TranslationMemoryApi
+  class TranslationMemoryApi # rubocop:disable Metrics/ClassLength
+    # Time to wait between two status queries of an import or export job.
+    JOB_POLLING_INTERVAL_SECONDS = 5
+
     def initialize(api, options = {})
       @api = api
       @options = options
     end
 
+    ##
+    # Lists the translation memories of the account.
+    #
+    # @param [Hash] options Additional options for the request. Supports `page` (page number for
+    #                       pagination, 0-indexed) and `page_size` (number of items per page).
+    # @return [Array<DeepL::Resources::TranslationMemory>] The translation memories of the page.
+
     def list(options = {})
       DeepL::Requests::TranslationMemory::List.new(@api, options).request
     end
+
+    ##
+    # Retrieves a single translation memory.
+    #
+    # @param [String, DeepL::Resources::TranslationMemory] translation_memory Translation memory
+    #                                                                         ID or object.
+    # @param [Hash] options Additional options for the request.
+    # @return [DeepL::Resources::TranslationMemory] The requested translation memory.
+
+    def find(translation_memory, options = {})
+      DeepL::Requests::TranslationMemory::Find.new(
+        @api, extract_translation_memory_id(translation_memory), options
+      ).request
+    end
+
+    ##
+    # Retrieves one page of the segments of a translation memory. Pagination is cursor-based:
+    # omit `page_cursor` on the first call, then pass the `next_page_cursor` of the previous
+    # response until it is nil.
+    #
+    # @param [String, DeepL::Resources::TranslationMemory] translation_memory Translation memory
+    #                                                                         ID or object.
+    # @param [Hash] options Additional options for the request. Supports `page_size` (maximum
+    #                       number of segments per page, 1-100, defaults to 50), `page_cursor`
+    #                       (cursor of a previous response), `filter_text` (substring filter
+    #                       across source and target text, at least 2 characters) and
+    #                       `filter_case_sensitive` (whether the filter is case-sensitive,
+    #                       defaults to false).
+    # @return [DeepL::Resources::TranslationMemorySegments] The requested page of segments.
+
+    def segments(translation_memory, options = {})
+      DeepL::Requests::TranslationMemory::Segments.new(
+        @api, extract_translation_memory_id(translation_memory), options
+      ).request
+    end
+
+    ##
+    # Deletes a translation memory.
+    #
+    # @param [String, DeepL::Resources::TranslationMemory] translation_memory Translation memory
+    #                                                                         ID or object.
+    # @param [Hash] options Additional options for the request.
+    # @return [String] The ID of the deleted translation memory.
+
+    def destroy(translation_memory, options = {})
+      DeepL::Requests::TranslationMemory::Destroy.new(
+        @api, extract_translation_memory_id(translation_memory), options
+      ).request
+    end
+
+    ##
+    # Creates an import job for a new translation memory. The job only declares the file, upload
+    # the TMX file itself to the returned upload URL with `upload_file`, then poll `find_job` for
+    # the outcome. Use `import_from_filepath` to do all three steps at once.
+    #
+    # @param [String] file_name Name of the TMX file to import, for example "legal.tmx".
+    # @param [Integer] content_length Size of the TMX file in bytes.
+    # @param [String, nil] content_type MIME type of the file, defaults to "application/xml".
+    # @param [String, nil] display_name Name of the resulting translation memory, defaults to the
+    #                                   file name.
+    # @param [Hash] additional_headers Additional HTTP headers for the request.
+    # @return [DeepL::Resources::TranslationMemoryImport] The job ID and the upload URL.
+
+    def create_import(file_name, content_length, content_type: nil, display_name: nil,
+                      additional_headers: {})
+      DeepL::Requests::TranslationMemory::CreateImport.new(
+        @api, file_name, content_length,
+        { content_type: content_type, display_name: display_name }.compact, additional_headers
+      ).request
+    end
+
+    ##
+    # Uploads a TMX file to the upload URL of an import job, which starts the processing. The
+    # upload URL is a pre-signed storage URL outside of the DeepL API, so no authorization header
+    # is sent with this request.
+    #
+    # @param [String, DeepL::Resources::TranslationMemoryImport] translation_memory_import Import
+    #        returned by `create_import`, or its upload URL.
+    # @param [String] file_content Content of the TMX file.
+    # @param [String] content_type MIME type of the file. Must match the `content_type` declared
+    #                              when the import job was created.
+    # @return [nil]
+
+    def upload_file(translation_memory_import, file_content,
+                    content_type: Requests::TranslationMemory::UploadFile::DEFAULT_CONTENT_TYPE)
+      DeepL::Requests::TranslationMemory::UploadFile.new(
+        @api, extract_upload_url(translation_memory_import), file_content, content_type
+      ).request
+    end
+
+    ##
+    # Creates an export job for a translation memory. Poll `find_job` for the download URL of the
+    # exported TMX file. Use `export_to_filepath` to do both steps and write the file at once.
+    #
+    # @param [String, DeepL::Resources::TranslationMemory] translation_memory Translation memory
+    #                                                                         ID or object.
+    # @param [Hash] options Additional options for the request.
+    # @return [DeepL::Resources::TranslationMemoryExport] The job ID, and whether the API reused a
+    #                                                     previously completed export.
+
+    def create_export(translation_memory, options = {})
+      DeepL::Requests::TranslationMemory::CreateExport.new(
+        @api, extract_translation_memory_id(translation_memory), options
+      ).request
+    end
+
+    ##
+    # Retrieves the status of a translation memory import or export job.
+    #
+    # @param [String, DeepL::Resources::TranslationMemoryJob] job Job ID or object.
+    # @param [Hash] options Additional options for the request.
+    # @return [DeepL::Resources::TranslationMemoryJob] The current status of the job.
+
+    def find_job(job, options = {})
+      DeepL::Requests::TranslationMemory::FindJob.new(@api, extract_job_id(job), options).request
+    end
+
+    ##
+    # Polls a translation memory import or export job until it is finished, `sleep`ing between
+    # the status queries, and returns the final status.
+    #
+    # Note that an import job keeps reporting `awaiting_input` for a while after its file has
+    # been uploaded, because the API detects the upload asynchronously. That status is therefore
+    # polled through like any other non-terminal one. A job whose file is never uploaded does not
+    # finish on its own, so pass `timeout_s` when that is a possibility.
+    #
+    # @raise [DeepL::Exceptions::Error] If the job failed or expired, or if `timeout_s` elapsed
+    #                                   before the job finished.
+    #
+    # @param [String, DeepL::Resources::TranslationMemoryJob] job Job ID or object.
+    # @param [Hash] options Additional options for the status queries.
+    # @param [Numeric, nil] timeout_s Maximum time in seconds to wait for the job to finish. Note
+    #                                 that this is not accurate to the second, the status is only
+    #                                 queried every five seconds.
+    # @return [DeepL::Resources::TranslationMemoryJob] The finished job.
+
+    def wait_until_job_done(job, options = {}, timeout_s: nil)
+      job_status = find_job(job, options)
+      started_at = monotonic_time
+      until job_status.finished?
+        raise_timeout_error(timeout_s) if timeout_exceeded?(started_at, timeout_s)
+
+        log_job_polling
+        sleep(JOB_POLLING_INTERVAL_SECONDS)
+        job_status = find_job(job, options)
+      end
+      raise_job_error(job_status) if job_status.error?
+
+      job_status
+    end
+
+    ##
+    # Downloads the TMX file of a completed export job. The download URL is a pre-signed storage
+    # URL outside of the DeepL API, so no authorization header is sent with this request.
+    #
+    # @raise [DeepL::Exceptions::Error] If the job carries no download URL, for example because
+    #                                   it has not completed yet.
+    #
+    # @param [DeepL::Resources::TranslationMemoryJob, String] job Completed export job carrying
+    #        the download URL, or the download URL itself.
+    # @param [String] output_path Path to the file to write to. Will be overwritten if the file
+    #                             already exists.
+
+    def download_export(job, output_path)
+      DeepL::Requests::TranslationMemory::DownloadExport.new(@api, extract_download_url(job),
+                                                             output_path).request
+    end
+
+    ##
+    # Imports a TMX file as a new translation memory: creates the import job, uploads the file
+    # and waits for the processing to finish.
+    #
+    # @raise [DeepL::Exceptions::Error] If the import fails.
+    #
+    # @param [String] input_file_path Path to the TMX file to import.
+    # @param [String, nil] display_name Name of the resulting translation memory, defaults to the
+    #                                   file name.
+    # @param [Numeric, nil] timeout_s Maximum time in seconds to wait for the import to finish.
+    #                                 Note that the API keeps reporting `awaiting_input` for a
+    #                                 while after the upload, so allow for a generous timeout.
+    # @return [DeepL::Resources::TranslationMemoryJob] The finished import job, its result carries
+    #                                                  the ID of the new translation memory.
+
+    def import_from_filepath(input_file_path, display_name: nil, timeout_s: nil)
+      unless File.exist?(input_file_path)
+        raise Exceptions::Error, "No file found at #{input_file_path}"
+      end
+
+      file_content = File.binread(input_file_path)
+      created = create_import(File.basename(input_file_path), file_content.bytesize,
+                              display_name: display_name)
+      upload_file(created, file_content)
+      wait_until_job_done(created.job_id, timeout_s: timeout_s)
+    end
+
+    ##
+    # Exports a translation memory to a TMX file: creates the export job, waits for it to finish
+    # and writes the result to +output_path+.
+    #
+    # @raise [DeepL::Exceptions::Error] If the export fails.
+    #
+    # @param [String, DeepL::Resources::TranslationMemory] translation_memory Translation memory
+    #                                                                         ID or object.
+    # @param [String] output_path Path to the file to write to. Will be overwritten if the file
+    #                             already exists.
+    # @param [Numeric, nil] timeout_s Maximum time in seconds to wait for the export to finish.
+    # @return [DeepL::Resources::TranslationMemoryJob] The finished export job.
+
+    def export_to_filepath(translation_memory, output_path, timeout_s: nil)
+      created = create_export(translation_memory)
+      job = wait_until_job_done(created.job_id, timeout_s: timeout_s)
+      download_export(job, output_path)
+      job
+    end
+
+    private
+
+    def extract_translation_memory_id(translation_memory)
+      id = if translation_memory.is_a?(Resources::TranslationMemory)
+             translation_memory.translation_memory_id
+           else
+             translation_memory
+           end
+      raise Exceptions::Error, 'Translation memory ID must not be empty' if blank?(id)
+
+      id
+    end
+
+    def extract_job_id(job)
+      id = job.is_a?(Resources::TranslationMemoryJob) ? job.job_id : job
+      raise Exceptions::Error, 'Job ID must not be empty' if blank?(id)
+
+      id
+    end
+
+    def extract_upload_url(translation_memory_import)
+      if translation_memory_import.is_a?(Resources::TranslationMemoryImport)
+        translation_memory_import.upload_url
+      else
+        translation_memory_import
+      end
+    end
+
+    def extract_download_url(job)
+      return job unless job.is_a?(Resources::TranslationMemoryJob)
+
+      download_url = job.result&.download_url
+      if blank?(download_url)
+        raise Exceptions::Error, 'Translation memory export job has no download URL, ' \
+                                 'it may not have completed yet'
+      end
+
+      download_url
+    end
+
+    def blank?(value)
+      value.nil? || value.empty?
+    end
+
+    def log_job_polling
+      @api.configuration.logger&.info('Rechecking translation memory job status after sleeping ' \
+                                      "for #{JOB_POLLING_INTERVAL_SECONDS} seconds.")
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def timeout_exceeded?(started_at, timeout_s)
+      !timeout_s.nil? && (monotonic_time - started_at) > timeout_s
+    end
+
+    def raise_timeout_error(timeout_s)
+      raise Exceptions::Error,
+            "Manual timeout of #{timeout_s}s exceeded for the translation memory job"
+    end
+
+    def raise_job_error(job_status)
+      raise Exceptions::Error,
+            "Error occurred during the translation memory #{job_status.operation}: " \
+            "#{job_status.error_message || job_status.status}"
+    end
   end
 end

data/lib/deepl/utils/time_parser.rb

@@ -0,0 +1,26 @@
+# 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
+
+require 'time'
+
+module DeepL
+  module Utils
+    module TimeParser
+      extend self
+
+      ##
+      # Parses an optional timestamp returned by the API.
+      #
+      # @param [String, nil] time_string Timestamp in ISO 8601 format, or nil.
+      # @return [Time, nil] The parsed time, or nil if no timestamp was given.
+
+      def parse_optional_time(time_string)
+        return nil if time_string.nil? || time_string.empty?
+
+        Time.parse(time_string)
+      end
+    end
+  end
+end

data/lib/deepl.rb

@@ -41,7 +41,17 @@ require_relative 'deepl/requests/style_rule/create_custom_instruction'
 require_relative 'deepl/requests/style_rule/find_custom_instruction'
 require_relative 'deepl/requests/style_rule/update_custom_instruction'
 require_relative 'deepl/requests/style_rule/destroy_custom_instruction'
+require_relative 'deepl/requests/translation_memory/base'
+require_relative 'deepl/requests/translation_memory/storage_base'
 require_relative 'deepl/requests/translation_memory/list'
+require_relative 'deepl/requests/translation_memory/find'
+require_relative 'deepl/requests/translation_memory/segments'
+require_relative 'deepl/requests/translation_memory/destroy'
+require_relative 'deepl/requests/translation_memory/create_import'
+require_relative 'deepl/requests/translation_memory/upload_file'
+require_relative 'deepl/requests/translation_memory/create_export'
+require_relative 'deepl/requests/translation_memory/find_job'
+require_relative 'deepl/requests/translation_memory/download_export'
 require_relative 'deepl/requests/languages'
 require_relative 'deepl/requests/translate'
 require_relative 'deepl/requests/usage'
@@ -54,6 +64,10 @@ require_relative 'deepl/resources/document_translation_status'
 require_relative 'deepl/resources/glossary'
 require_relative 'deepl/resources/style_rule'
 require_relative 'deepl/resources/translation_memory'
+require_relative 'deepl/resources/translation_memory_segments'
+require_relative 'deepl/resources/translation_memory_import'
+require_relative 'deepl/resources/translation_memory_export'
+require_relative 'deepl/resources/translation_memory_job'
 require_relative 'deepl/resources/language'
 require_relative 'deepl/resources/language_pair'
 require_relative 'deepl/resources/text'
@@ -62,6 +76,7 @@ require_relative 'deepl/resources/usage'
 # -- Utils
 require_relative 'deepl/utils/exception_builder'
 require_relative 'deepl/utils/backoff_timer'
+require_relative 'deepl/utils/time_parser'
 
 # -- Constants
 require_relative 'deepl/constants/base_constant'
@@ -100,9 +115,26 @@ module DeepL
     Requests::Languages.new(api, options).request
   end
 
-  def translate(text, source_lang, target_lang, options = {})
+  ##
+  # Translates +text+ from +source_lang+ into +target_lang+.
+  #
+  # @param [String, Array<String>] text Text(s) to translate.
+  # @param [String, nil] source_lang Source language. `nil` enables automatic detection.
+  # @param [String] target_lang Target language.
+  # @param [Hash] options Additional (body) options for the translation. Notable options:
+  #   * +:glossary_id+ - A single glossary ID (string) to use for the translation. Requires
+  #     +source_lang+ to be set. Cannot be combined with +:glossary_ids+.
+  #   * +:glossary_ids+ - An array of up to 5 glossary IDs (strings or
+  #     `DeepL::Resources::Glossary` objects) to use for the translation. Glossaries are applied
+  #     in order (first match wins). Requires +source_lang+ to be set. Cannot be combined with
+  #     +:glossary_id+. Raises `ArgumentError` if these rules are violated or more than 5 IDs are
+  #     provided.
+  # @param [Hash] additional_headers Additional HTTP headers for the translation.
+  # @return [DeepL::Resources::Text, Array<DeepL::Resources::Text>] Translated text resource(s).
+  def translate(text, source_lang, target_lang, options = {}, additional_headers = {})
     configure if @configuration.nil?
-    Requests::Translate.new(api, text, source_lang, target_lang, options).request
+    Requests::Translate.new(api, text, source_lang, target_lang, options,
+                            additional_headers).request
   end
 
   def document(options = {})
@@ -125,9 +157,11 @@ module DeepL
     TranslationMemoryApi.new(api, options)
   end
 
-  def rephrase(text, target_lang = nil, writing_style = nil, tone = nil, options = {}) # rubocop:disable Metrics/ParameterLists
+  def rephrase(text, target_lang = nil, writing_style = nil, tone = nil, options = {}, # rubocop:disable Metrics/ParameterLists
+               additional_headers = {})
     configure if @configuration.nil?
-    Requests::Rephrase.new(api, text, target_lang, writing_style, tone, options).request
+    Requests::Rephrase.new(api, text, target_lang, writing_style, tone, options,
+                           additional_headers).request
   end
 
   def usage(options = {})

data/lib/version.rb

@@ -4,5 +4,5 @@
 # frozen_string_literal: true
 
 module DeepL
-  VERSION = '3.7.0'
+  VERSION = '3.9.0'
 end