Project

deepl-rb

0.07
The project is in a healthy, maintained state
A simple ruby wrapper for the DeepL translation API (v1). For more information, check this: https://www.deepl.com/docs/api-reference.html
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Project Readme

Gem Version CircleCI CodeCov

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
PT Portuguese
IT Italian
NL Dutch
PL Polish
RU Russian

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 Description
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::QuotaExceeded You've reached the API's character 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

Integrations

Ruby on Rails

You may use this gem as a standalone service by creating an initializer on your config/initializers folder with your DeepL configuration. For example:

# config/initializers/deepl.rb
DeepL.configure do |config|
  # Your configuration goes here
end

Since the DeepL service is defined globally, you can use service anywhere in your code (controllers, models, views, jobs, plain ruby objects… you name it).

i18n-tasks

You may also take a look at i18n-tasks, which is a gem that helps you find and manage missing and unused translations. deepl-rb is used as one of the backend services to translate content.

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