Class: DeepL::TranslationMemoryApi

Inherits:
Object
  • Object
show all
Defined in:
lib/deepl/translation_memory_api.rb

Overview

rubocop:disable Metrics/ClassLength

Constant Summary collapse

JOB_POLLING_INTERVAL_SECONDS =

Time to wait between two status queries of an import or export job.

5

Instance Method Summary collapse

Constructor Details

#initialize(api, options = {}) ⇒ TranslationMemoryApi

Returns a new instance of TranslationMemoryApi.



11
12
13
14
 
# File 'lib/deepl/translation_memory_api.rb', line 11

def initialize(api, options = {})
  @api = api
  @options = options
end

Instance Method Details

#create_export(translation_memory, options = {}) ⇒ DeepL::Resources::TranslationMemoryExport

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.

Parameters:

  • translation_memory (String, DeepL::Resources::TranslationMemory) —

    Translation memory ID or object.

  • options (Hash) (defaults to: {}) —

    Additional options for the request.

Returns:



126
127
128
129
130
 
# File 'lib/deepl/translation_memory_api.rb', line 126

def create_export(translation_memory, options = {})
  DeepL::Requests::TranslationMemory::CreateExport.new(
    @api, extract_translation_memory_id(translation_memory), options
  ).request
end

#create_import(file_name, content_length, content_type: nil, display_name: nil, additional_headers: {}) ⇒ DeepL::Resources::TranslationMemoryImport

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.

Parameters:

  • file_name (String) —

    Name of the TMX file to import, for example "legal.tmx".

  • content_length (Integer) —

    Size of the TMX file in bytes.

  • content_type (String, nil) (defaults to: nil) —

    MIME type of the file, defaults to "application/xml".

  • display_name (String, nil) (defaults to: nil) —

    Name of the resulting translation memory, defaults to the file name.

  • additional_headers (Hash) (defaults to: {}) —

    Additional HTTP headers for the request.

Returns:



89
90
91
92
93
94
95
 
# File 'lib/deepl/translation_memory_api.rb', line 89

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

#destroy(translation_memory, options = {}) ⇒ String

Deletes a translation memory.

Parameters:

  • translation_memory (String, DeepL::Resources::TranslationMemory) —

    Translation memory ID or object.

  • options (Hash) (defaults to: {}) —

    Additional options for the request.

Returns:

  • (String) —

    The ID of the deleted translation memory.



70
71
72
73
74
 
# File 'lib/deepl/translation_memory_api.rb', line 70

def destroy(translation_memory, options = {})
  DeepL::Requests::TranslationMemory::Destroy.new(
    @api, extract_translation_memory_id(translation_memory), options
  ).request
end

#download_export(job, output_path) ⇒ Object

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.

Parameters:

  • job (DeepL::Resources::TranslationMemoryJob, String) —

    Completed export job carrying the download URL, or the download URL itself.

  • output_path (String) —

    Path to the file to write to. Will be overwritten if the file already exists.

Raises:



189
190
191
192
 
# File 'lib/deepl/translation_memory_api.rb', line 189

def download_export(job, output_path)
  DeepL::Requests::TranslationMemory::DownloadExport.new(@api, extract_download_url(job),
                                                         output_path).request
end

#export_to_filepath(translation_memory, output_path, timeout_s: nil) ⇒ DeepL::Resources::TranslationMemoryJob

Exports a translation memory to a TMX file: creates the export job, waits for it to finish and writes the result to output_path.

Parameters:

  • translation_memory (String, DeepL::Resources::TranslationMemory) —

    Translation memory ID or object.

  • output_path (String) —

    Path to the file to write to. Will be overwritten if the file already exists.

  • timeout_s (Numeric, nil) (defaults to: nil) —

    Maximum time in seconds to wait for the export to finish.

Returns:

Raises:



234
235
236
237
238
239
 
# File 'lib/deepl/translation_memory_api.rb', line 234

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

#find(translation_memory, options = {}) ⇒ DeepL::Resources::TranslationMemory

Retrieves a single translation memory.

Parameters:

  • translation_memory (String, DeepL::Resources::TranslationMemory) —

    Translation memory ID or object.

  • options (Hash) (defaults to: {}) —

    Additional options for the request.

Returns:



35
36
37
38
39
 
# File 'lib/deepl/translation_memory_api.rb', line 35

def find(translation_memory, options = {})
  DeepL::Requests::TranslationMemory::Find.new(
    @api, extract_translation_memory_id(translation_memory), options
  ).request
end

#find_job(job, options = {}) ⇒ DeepL::Resources::TranslationMemoryJob

Retrieves the status of a translation memory import or export job.

Parameters:

Returns:



139
140
141
 
# File 'lib/deepl/translation_memory_api.rb', line 139

def find_job(job, options = {})
  DeepL::Requests::TranslationMemory::FindJob.new(@api, extract_job_id(job), options).request
end

#import_from_filepath(input_file_path, display_name: nil, timeout_s: nil) ⇒ DeepL::Resources::TranslationMemoryJob

Imports a TMX file as a new translation memory: creates the import job, uploads the file and waits for the processing to finish.

Parameters:

  • input_file_path (String) —

    Path to the TMX file to import.

  • display_name (String, nil) (defaults to: nil) —

    Name of the resulting translation memory, defaults to the file name.

  • timeout_s (Numeric, nil) (defaults to: nil) —

    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.

Returns:

Raises:



209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/deepl/translation_memory_api.rb', line 209

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

#list(options = {}) ⇒ Array<DeepL::Resources::TranslationMemory>

Lists the translation memories of the account.

Parameters:

  • options (Hash) (defaults to: {}) —

    Additional options for the request. Supports page (page number for pagination, 0-indexed) and page_size (number of items per page).

Returns:



23
24
25
 
# File 'lib/deepl/translation_memory_api.rb', line 23

def list(options = {})
  DeepL::Requests::TranslationMemory::List.new(@api, options).request
end

#segments(translation_memory, options = {}) ⇒ DeepL::Resources::TranslationMemorySegments

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.

Parameters:

  • translation_memory (String, DeepL::Resources::TranslationMemory) —

    Translation memory ID or object.

  • options (Hash) (defaults to: {}) —

    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).

Returns:



56
57
58
59
60
 
# File 'lib/deepl/translation_memory_api.rb', line 56

def segments(translation_memory, options = {})
  DeepL::Requests::TranslationMemory::Segments.new(
    @api, extract_translation_memory_id(translation_memory), options
  ).request
end

#upload_file(translation_memory_import, file_content, content_type: Requests::TranslationMemory::UploadFile::DEFAULT_CONTENT_TYPE) ⇒ nil

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.

Parameters:

  • translation_memory_import (String, DeepL::Resources::TranslationMemoryImport) —

    Import returned by create_import, or its upload URL.

  • file_content (String) —

    Content of the TMX file.

  • content_type (String) (defaults to: Requests::TranslationMemory::UploadFile::DEFAULT_CONTENT_TYPE) —

    MIME type of the file. Must match the content_type declared when the import job was created.

Returns:

  • (nil) 


109
110
111
112
113
114
 
# File 'lib/deepl/translation_memory_api.rb', line 109

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

#wait_until_job_done(job, options = {}, timeout_s: nil) ⇒ DeepL::Resources::TranslationMemoryJob

Polls a translation memory import or export job until it is finished, sleeping 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.

Parameters:

  • job (String, DeepL::Resources::TranslationMemoryJob) —

    Job ID or object.

  • options (Hash) (defaults to: {}) —

    Additional options for the status queries.

  • timeout_s (Numeric, nil) (defaults to: nil) —

    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.

Returns:

Raises:



162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/deepl/translation_memory_api.rb', line 162

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