deepl-rb 3.8.0 → 3.9.0

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,6 +115,22 @@ module DeepL
     Requests::Languages.new(api, options).request
   end
 
+  ##
+  # 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,

data/lib/version.rb

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

data/spec/integration_tests/document_api_spec.rb

@@ -140,6 +140,53 @@ describe DeepL::DocumentApi do
     expect(doc_status.status).to eq('done')
   end
 
+  it 'Translates a document with a style_id set', :mock_server_only do # rubocop:disable RSpec/ExampleLength
+    File.unlink(output_document_path)
+    # Mock's default style rule (dca2e053...) has language `en`, so the target
+    # language must be English.
+    source_lang = 'DE'
+    target_lang = 'EN-US'
+    example_doc_path = example_document_path(source_lang)
+    style_id = 'dca2e053-8ae5-45e6-a0d2-881156e7f4e4'
+    doc_status = nil
+    DeepL.with_session(DeepL::HTTPClientOptions.new({}, nil,
+                                                    enable_ssl_verification: false)) do |_session|
+      handle = DeepL.document.upload(example_doc_path, source_lang, target_lang,
+                                     File.basename(example_doc_path),
+                                     { style_rule: style_id })
+      doc_status = handle.wait_until_document_translation_finished
+      DeepL.document.download(handle, output_document_path) if doc_status.status != 'error'
+    end
+    output_file_contents = File.read(output_document_path)
+
+    expect(example_document_translation(target_lang)).to eq(output_file_contents)
+    expect(doc_status.status).to eq('done')
+  end
+
+  it 'Translates a document with a translation_memory_id set', :mock_server_only do # rubocop:disable RSpec/ExampleLength
+    File.unlink(output_document_path)
+    # Mock's default translation memory (a74d88fb...) has source `de` and
+    # targets `en`/`es`/`fr`, so translate DE -> EN-US.
+    source_lang = 'DE'
+    target_lang = 'EN-US'
+    example_doc_path = example_document_path(source_lang)
+    translation_memory_id = 'a74d88fb-ed2a-4943-a664-a4512398b994'
+    doc_status = nil
+    DeepL.with_session(DeepL::HTTPClientOptions.new({}, nil,
+                                                    enable_ssl_verification: false)) do |_session|
+      handle = DeepL.document.upload(example_doc_path, source_lang, target_lang,
+                                     File.basename(example_doc_path),
+                                     { translation_memory: translation_memory_id,
+                                       translation_memory_threshold: 80 })
+      doc_status = handle.wait_until_document_translation_finished
+      DeepL.document.download(handle, output_document_path) if doc_status.status != 'error'
+    end
+    output_file_contents = File.read(output_document_path)
+
+    expect(example_document_translation(target_lang)).to eq(output_file_contents)
+    expect(doc_status.status).to eq('done')
+  end
+
   it 'Translates a document with extra_body_parameters' do # rubocop:disable RSpec/ExampleLength
     File.unlink(output_document_path)
     source_lang = default_lang_args[:source_lang]

data/spec/integration_tests/integration_test_utils.rb

@@ -148,6 +148,14 @@ module IntegrationTestUtils # rubocop:disable Metrics/ModuleLength
       'mock-server-session' => SecureRandom.uuid }
   end
 
+  # Makes a translation memory import or export job report its non-terminal status, such as
+  # `awaiting_input` for an uploaded import, for the given number of status queries before it
+  # completes. Without it a job completes on the first query.
+  def tm_job_processing_polls_header(poll_count)
+    { 'mock-server-session-tm-job-processing-polls' => poll_count.to_s,
+      'mock-server-session' => SecureRandom.uuid }
+  end
+
   def expect_proxy_header(response_count)
     { 'mock-server-session-expect-proxy' => response_count.to_s,
       'mock-server-session' => SecureRandom.uuid }

data/spec/integration_tests/translate_api_spec.rb

@@ -76,6 +76,25 @@ describe 'DeepL.translate' do # rubocop:disable RSpec/DescribeClass
       end
     end
 
+    it 'translates using multiple glossaries via glossary_ids' do # rubocop:disable RSpec/ExampleLength
+      with_managed_glossary(name: 'Translate Glossary IDs 1', source_lang: 'en', target_lang: 'de',
+                            entries: [%w[Hello Hallo]]) do |glossary1|
+        with_managed_glossary(name: 'Translate Glossary IDs 2', source_lang: 'en',
+                              target_lang: 'de', entries: [%w[World Welt]]) do |glossary2|
+          # Newly created glossaries can lag behind (eventual consistency), so
+          # ensure they are resolvable before translating and tolerate a
+          # transient "not found" on the translate call itself.
+          wait_until_glossaries_ready(glossary1, glossary2)
+          result = translate_retrying_missing_glossary(
+            'Hello', 'EN', 'DE', { glossary_ids: [glossary1.id, glossary2.id] }
+          )
+
+          expect(result).to be_a(DeepL::Resources::Text)
+          expect(result.text).not_to be_empty
+        end
+      end
+    end
+
     %w[quality_optimized latency_optimized prefer_quality_optimized].each do |model_type|
       it "returns model_type_used for #{model_type}" do
         result = DeepL.translate(text, 'EN', 'DE', { model_type: model_type })