README.md in deepl-rb-0.0.1 vs README.md in deepl-rb-1.0.0
- old
+ new
@@ -1,6 +1,6 @@
-[](https://badge.fury.io/rb/deepl-rb) [](https://gemnasium.com/github.com/wikiti/deepl-rb) [](https://circleci.com/gh/wikiti/deepl-rb)
+[](https://badge.fury.io/rb/deepl-rb) [](https://gemnasium.com/github.com/wikiti/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 (v1)](https://www.deepl.com/docs/api-reference.html).
@@ -8,10 +8,11 @@
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
@@ -46,36 +47,83 @@
### Translate
To translate a simple text, use the `translate` method:
```rb
-item = DeepL.translate 'This is my text', 'EN', 'ES'
+translation = DeepL.translate 'This is my text', 'EN', 'ES'
-puts item.class
+puts translation.class
# => DeepL::Resources::Text
-puts item.text
+puts translation.text
# => 'Este es mi texto'
```
-You can also auto-detect source language by skipping it with `nil`:
+Enable auto-detect source language by skipping the source language with `nil`:
```rb
-item = DeepL.translate 'This is my text', nil, 'ES'
+translation = DeepL.translate 'This is my text', nil, 'ES'
-puts item.detected_source_language
+puts translation.detected_source_language
# => 'EN'
```
-You can also translate a list of texts by passing an array as an argument:
+Translate a list of texts by passing an array as an argument:
```rb
texts = ['Sample text', 'Another text']
-items = DeepL.translate texts, 'EN', 'ES'
+translations = DeepL.translate texts, 'EN', 'ES'
-puts items.class
+puts translations.class
# => Array
-puts items.first.class
+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`:
+
+```rb
+texts = ['Sample text',ยก]
+translation = DeepL.translate '<p>A sample</p>', 'EN', 'ES', tag_handling: true
+
+puts translation.text
+# => ""
+```
+
+### 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: