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:



73
74
75
76
 
# File 'lib/deepl/document_api.rb', line 73

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:



58
59
60
61
62
 
# File 'lib/deepl/document_api.rb', line 58

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, sleeping 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.



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/deepl/document_api.rb', line 102

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. Notable glossary options: :glossary_id (a single glossary ID) or :glossary_ids (an array of up to 5 glossary IDs, as strings or DeepL::Resources::Glossary objects). :glossary_ids requires source_lang to be set, cannot be combined with :glossary_id, and raises ArgumentError if these rules are violated or more than 5 IDs are provided. Notable style/translation memory options (mirroring text translation): :style_rule (a style rule ID string or a DeepL::Resources::StyleRule object), :translation_memory (a translation memory ID string or a DeepL::Resources::TranslationMemory object), and :translation_memory_threshold (integer 0-100, recommended minimum 75).

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

    Additional HTTP headers for the upload.

Returns:



42
43
44
45
46
47
 
# File 'lib/deepl/document_api.rb', line 42

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