[](https://badge.fury.io/rb/deepl-rb) [](https://circleci.com/gh/wikiti/deepl-rb) [](https://codecov.io/gh/wikiti/deepl-rb)
# DeepL for ruby
A simple ruby wrapper for the [DeepL translation API (v2)](https://www.deepl.com/api.html).
## Installation
Install this gem with
```sh
gem install deepl-rb
# Load it in your ruby file using `require 'deepl'`
```
Or add it to your Gemfile:
```rb
gem 'deepl-rb', require: 'deepl'
```
## Usage
Setup an environment variable named `DEEPL_AUTH_KEY` with your authentication key:
```sh
export DEEPL_AUTH_KEY="your-api-token"
```
Alternatively, you can configure the API client within a ruby block:
```rb
DeepL.configure do |config|
config.auth_key = 'your-api-token'
end
```
You can also configure the API host and the API version:
```rb
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:
```rb
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`:
```rb
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:
```rb
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`:
```rb
translation = DeepL.translate 'A sample
', 'EN', 'ES',
tag_handling: 'xml', split_sentences: false,
non_splitting_tags: 'h1', ignore_tags: %w[code pre]
puts translation.text
# => "Una muestra
"
```
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:
```rb
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:
```rb
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:
```sh
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](mailto:info@danielherzog.es)