DeepL for ruby

A simple ruby wrapper for the DeepL translation API (v2).

Installation

Install this gem with

gem install deepl-rb
# Load it in your ruby file using `require 'deepl'`

Or add it to your Gemfile:

gem 'deepl-rb', require: 'deepl'

Usage

Setup an environment variable named DEEPL_AUTH_KEY with your authentication key:

export DEEPL_AUTH_KEY="your-api-token"

Alternatively, you can configure the API client within a ruby block:

DeepL.configure do |config|
  config.auth_key = 'your-api-token'
end

You can also configure the API host and the API version:

DeepL.configure do |config|
  config.auth_key = 'your-api-token'
  config.host = 'https://test-api.deepl.com' # Default value is 'https://api.deepl.com'
  config.version = 'v1' # Default value is 'v2'
end

Translate

To translate a simple text, use the translate method:

translation = DeepL.translate 'This is my text', 'EN', 'ES'

puts translation.class
# => DeepL::Resources::Text
puts translation.text
# => 'Este es mi texto'

Enable auto-detect source language by skipping the source language with nil:

translation = DeepL.translate 'This is my text', nil, 'ES'

puts translation.detected_source_language
# => 'EN'

Translate a list of texts by passing an array as an argument:

texts = ['Sample text', 'Another text']
translations = DeepL.translate texts, 'EN', 'ES'

puts translations.class
# => Array
puts translations.first.class
# => DeepL::Resources::Text

Here's a list of available language codes:

Language code	Language
EN	English
DE	German
FR	French
ES	Spanish
IT	Italian
NL	Dutch
PL	Polish

You can also use custom query parameters, like tag_handling, split_sentences, non_splitting_tags or ignore_tags:

translation = DeepL.translate '<p>A sample</p>', 'EN', 'ES',
                              tag_handling: 'xml', split_sentences: false,
                              non_splitting_tags: 'h1', ignore_tags: %w[code pre]

puts translation.text
# => "<p>Una muestra</p>"

The following parameters will be automatically converted:

Parameter	Conversion
preserve_formatting	Converts false to '0' and true to '1'
split_sentences	Converts false to '0' and true to '1'
non_splitting_tags	Converts arrays to strings joining by commas
ignore_tags	Converts arrays to strings joining by commas

Usage

To check current API usage, use:

usage = DeepL.usage

puts usage.character_count
# => 180118
puts usage.character_limit
# => 1250000

Handle exceptions

You can capture and process exceptions that may be raised during API calls. These are all the possible exceptions:

Exception class	Descripcion
DeepL::Exceptions::AuthorizationFailed	The authorization process has failed. Check your auth_key value.
DeepL::Exceptions::BadRequest	Something is wrong in your request. Check exception.message for more information.
DeepL::Exceptions::LimitExceeded	You've reached the API's call limit.
DeepL::Exceptions::RequestError	An unkown request error. Check exception.response and exception.request for more information.

An exampling of handling a generic exception:

def my_method
  item = DeepL.translate 'This is my text', nil, 'ES'
rescue DeepL::Exceptions::RequestError => e
  puts 'Oops!'
  puts "Code: #{e.response.code}"
  puts "Response body: #{e.response.body}"
  puts "Request body: #{e.request.body}"
end

Development

Clone the repository, and install its dependencies:

git clone https://github.com/wikiti/deepl-rb
cd deepl-rb
bundle install

To run tests (rspec and rubocop), use

bundle exec rake test

Contributors

This project has been developed by:

Avatar	Name	Nickname	Email
	Daniel Herzog	Wikiti	info@danielherzog.es