Class: DeepL::DocumentApi

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

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of DocumentApi.



8
9
10
11
 
# File 'lib/deepl/document_api.rb', line 8

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

Instance Method Details

#download(document_handle, output_file) ⇒ DeepL::Resources::DocumentTranslationStatus

Downloads the document identified by the document_handle to output_file

method.

Parameters:

  • document_handle (DeepL::Resources::DocumentHandle) —

    Handle returned by the ‘upload`

  • output_file (String) —

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

Returns:



63
64
65
66
 
# File 'lib/deepl/document_api.rb', line 63

def download(document_handle, output_file)
  DeepL::Requests::Document::Download.new(@api, document_handle.document_id,
                                          document_handle.document_key, output_file).request
end

#get_status(document_handle, options = {}, additional_headers = {}) ⇒ DeepL::Resources::DocumentTranslationStatus

Queries the status of the translation of the document with the given document_handle.

method.

Parameters:

  • document_handle (DeepL::Resources::DocumentHandle) —

    Handle returned by the ‘upload`

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

    Additional options for the upload.

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

    Additional HTTP headers for the status check.

Returns:



48
49
50
51
52
 
# File 'lib/deepl/document_api.rb', line 48

def get_status(document_handle, options = {}, additional_headers = {})
  DeepL::Requests::Document::GetStatus.new(@api, document_handle.document_id,
                                           document_handle.document_key, options,
                                           additional_headers).request
end

#translate_document(input_file, output_file, source_lang, target_lang, filename = nil, options = {}, additional_headers = {}) ⇒ DeepL::Resources::DocumentTranslationStatus

Translates a document with the DeepL API, ‘sleep`ing during waiting periods. Returns the status that was queried last. This can be either because the document translation terminated (successfully or with an error) or because the maximum number of status requests have been made. See the parameter `max_doc_status_queries` for details.

Parameters:

  • input_file (String) —

    Path to the file to be translated

  • output_file (String) —

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

  • source_lang (String, nil) —

    Source language to use for the translation. ‘nil` will cause automatic source langauge detection to be used. Must be formatted as ISO 639-1, 2-letter language codes.

  • target_lang (String) —

    Target language to use for the translation. Must be formatted as ISO 639-1, 2-letter language codes, plus a hyphen “-” with the variant identifier for languages with variants/dialects/… .

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

    The filename of the file, including its extension. Used to open the different kinds of documents (PDFs, etc). If nil, will use the filename of input_file_path.

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

    Additional options for the upload.

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

    Additional headers for the upload.

Returns:

Raises:

  • (DocumentTranslationError) —

    If any error occurs during the process.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/deepl/document_api.rb', line 92

def translate_document(input_file, output_file, source_lang, target_lang, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists
                       filename = nil, options = {}, additional_headers = {})
  raise IOError 'File already exists at output path' if File.exist?(output_file)

  begin
    handle = upload(input_file, source_lang, target_lang, filename, options,
                    additional_headers)
    translate_document_wait_and_download(handle, output_file)
  rescue StandardError => e
    FileUtils.rm_f(output_file)
    raise Exceptions::DocumentTranslationError.new(
      "Error occurred during document translation: #{e.message}", handle
    )
  end
end

#upload(input_file_path, source_lang, target_lang, filename = nil, options = {}, additional_headers = {}) ⇒ DeepL::Resources::DocumentHandle

Uploads the file at the given input_file_path to be translated from source_lang into target_lang. The API interface is async, so you need to poll using the returned ‘DeepL::Resources::DocumentHandle` until the translation is finished, then you can download it

Parameters:

  • input_file_path (String) —

    File path to the file to be translated

  • source_lang (String, nil) —

    Source language to use for the translation. ‘nil` will cause automatic source langauge detection to be used. Must be formatted as ISO 639-1, 2-letter language codes.

  • target_lang (String) —

    Target language to use for the translation. Must be formatted as ISO 639-1, 2-letter language codes, plus a hyphen “-” with the variant identifier for languages with variants/dialects/… .

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

    The filename of the file, including its extension. Used to open the different kinds of documents (PDFs, etc). If nil, will use the filename of input_file_path.

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

    Additional (body) options for the upload.

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

    Additional HTTP headers for the upload.

Returns:



32
33
34
35
36
37
 
# File 'lib/deepl/document_api.rb', line 32

def upload(input_file_path, source_lang, target_lang, filename = nil, options = {},
           additional_headers = {})
  DeepL::Requests::Document::Upload.new(@api, input_file_path, source_lang, target_lang,
                                        filename, options, additional_headers)
                                   .request
end