deepl-rb 2.2.1 → 2.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fedf9315cf7b163148b9eebbbded4f80c93c4ae3
-  data.tar.gz: aa81c5a04442a74fc5099acb060bbbbd71e9bf00
+SHA256:
+  metadata.gz: d0f4d3d2ddeeb7156fd35df3906d1a176d9e66b64c8d936ff2fb7fc3681cb437
+  data.tar.gz: 2d15451265aed72177fdf9692e44a5ca5f19750db4c620a009e482a708232ddf
 SHA512:
-  metadata.gz: 8ef069fb972692ec56ac2688c85385de934beba10ce3f180fd354e42a14c91568d37dfa9549dc19a3c55824575885ead52d7fbea69fc58322851c2149dd01f0d
-  data.tar.gz: f92c7383dc6511902f825ba373aaf5c6bf7470a369d9a042dd28bf918409d7b9e80b4c044d50e09522e3c6410e3bae77a7d732b9e590db71022ac7227b4af18a
+  metadata.gz: c949370aa698d2c891c8961e17c94b914e7a7f9942584ca2ef8664cad22dcf03169d5512d5caa2d43d3c2ee65a9d19a9eb2231d1b7766eab444430a18d84c75b
+  data.tar.gz: aa188f9969cfdbd0b0355d2f58afb828358be8078487e52f2c2ac3bdc518e9a6d5c718c8652461c612a9cf39dba15ff4b157b5335fd3282a570f425bd245ade4

data/.circleci/config.yml

@@ -3,26 +3,14 @@ jobs:
   build:
     working_directory: ~/deepl-rb
     docker:
-    - image: circleci/ruby:2.1
+    - image: circleci/ruby:2.7
     steps:
     - checkout
 
-    # Restore bundle cache
-    - type: cache-restore
-      name: Restore bundle cache
-      key: deepl-rb-bundle-{{ checksum "Gemfile.lock" }}
-
     - run:
         name: Bundle Install
         command: bundle install --path vendor/bundle
 
-    # Store bundle cache
-    - type: cache-save
-      name: Store bundle cache
-      key: deepl-rb-bundle-{{ checksum "Gemfile.lock" }}
-      paths:
-      - vendor/bundle
-
     # Run rspec
     - type: shell
       command: |

data/.rubocop.yml

@@ -2,15 +2,19 @@
 
 AllCops:
   DisplayCopNames: true
+  NewCops: enable
   Exclude:
-  - deepl-rb.gemspec
-  - vendor/**/*
+    - deepl-rb.gemspec
+    - vendor/**/*
 
 Metrics/BlockLength:
   Exclude:
-  - "**/*_spec.rb"
+    - "**/*_spec.rb"
 
-Metrics/LineLength:
+Metrics/ParameterLists:
+  Max: 6
+
+Layout/LineLength:
   Max: 100
 
 Style/Documentation:

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 group :development do
@@ -5,6 +7,10 @@ group :development do
   gem 'juwelier'
 end
 
+group :test, :development do
+  gem 'byebug', require: 'byebug'
+end
+
 group :test do
   # Test
   gem 'codecov', require: false

data/README.md

@@ -40,11 +40,42 @@ 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.host = 'https://api-free.deepl.com' # Default value is 'https://api.deepl.com'
   config.version = 'v1' # Default value is 'v2'
 end
 ```
 
+### Available languages
+
+Available languages can be retrieved via API:
+
+```rb
+languages = DeepL.languages
+
+puts languages.class
+# => Array
+puts languages.first.class
+# => DeepL::Resources::Language
+puts "#{languages.first.code} -> #{languages.first.name}"
+# => "ES -> Spanish"
+```
+
+Note that source and target languages may be different, which can be retrieved by using the `type`
+option:
+
+```rb
+puts DeepL.languages(type: :source).count
+# => 24
+puts DeepL.languages(type: :target).count
+# => 26
+```
+
+All languages are also defined on the
+[official API documentation](https://www.deepl.com/docs-api/translating-text/).
+
+Note that target languages may include the `supports_formality` flag, which may be checked
+using the `DeepL::Resources::Language#supports_formality?`.
+
 ### Translate
 
 To translate a simple text, use the `translate` method:
@@ -79,20 +110,6 @@ 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`:
 
 ```rb
@@ -110,10 +127,108 @@ The following parameters will be automatically converted:
 | --------------------- | ---------------
 | `preserve_formatting` | Converts `false` to `'0'` and `true` to `'1'`
 | `split_sentences`     | Converts `false` to `'0'` and `true` to `'1'`
+| `outline_detection`   | Converts `false` to `'0'` and `true` to `'1'`
+| `splitting_tags`      | Converts arrays to strings joining by commas
 | `non_splitting_tags`  | Converts arrays to strings joining by commas
 | `ignore_tags`         | Converts arrays to strings joining by commas
+| `formality`           | No conversion applied
+| `glossary_id`         | No conversion applied
+
+### Glossaries
+
+To create a glossary, use the `glossaries.create` method. The glossary `entries` argument should be an array of text pairs. Each pair includes the source and the target translations.
+
+```rb
+entries = [
+  ['Hello World', 'Hola Tierra'],
+  ['car', 'auto']
+]
+glossary = DeepL.glossaries.create 'Mi Glosario', 'EN', 'ES', entries
+
+puts glossary.class
+# => DeepL::Resources::Glossary
+puts glossary.id
+# => 'aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e'
+puts glossary.entry_count
+# => 2
+```
+
+Created glossaries can be used in the `translate` method by specifying the `glossary_id` option:
+
+```rb
+translation = DeepL.translate 'Hello World', 'EN', 'ES', glossary_id: 'aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e'
+
+puts translation.class
+# => DeepL::Resources::Text
+puts translation.text
+# => 'Hola Tierra'
+
+translation = DeepL.translate "I wish we had a car.", 'EN', 'ES', glossary_id: 'aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e'
+
+puts translation.class
+# => DeepL::Resources::Text
+puts translation.text
+# => Ojalá tuviéramos un auto.
+```
+
+To list all the glossaries available, use the `glossaries.list` method:
+
+```rb
+glossaries = DeepL.glossaries.list
+
+puts glossaries.class
+# => Array
+puts glossaries.first.class
+# => DeepL::Resources::Glossary
+```
+
+To find an existing glossary, use the `glossaries.find` method:
+
+```rb
+glossary = DeepL.glossaries.find 'aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e'
+
+puts glossary.class
+# => DeepL::Resources::Glossary
+```
+
+The glossary resource does not include the glossary entries. To list the glossary entries, use the `glossaries.entries` method:
+
+```rb
+entries = DeepL.glossaries.entries 'aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e'
+
+puts entries.class
+# => Array
+puts entries.size
+# => 2
+pp entries.first
+# => ["Hello World", "Hola Tierra"]
+```
+
+To delete an existing glossary, use the `glossaries.destroy` method:
+
+```rb
+glossary_id = DeepL.glossaries.destroy 'aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e'
+
+puts glossary_id
+# => aa48c7f0-0d02-413e-8a06-d5bbf0ca7a6e
+```
+
+You can list all the language pairs supported by glossaries using the `glossaries.language_pairs` method:
 
-### Usage
+```rb
+language_pairs = DeepL.glossaries.language_pairs
+
+puts language_pairs.class
+# => Array
+puts language_pairs.first.class
+# => DeepL::Resources::LanguagePair
+puts language_pairs.first.source_lang
+# => en
+puts language_pairs.first.target_lang
+# => de
+```
+
+### Monitor usage
 
 To check current API usage, use:
 
@@ -137,6 +252,7 @@ You can capture and process exceptions that may be raised during API calls. Thes
 | `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. |
+| `DeepL::Exceptions::NotSupported` | The requested method or API endpoint is not supported. |
 
 An exampling of handling a generic exception:
 
@@ -171,7 +287,7 @@ Since the DeepL service is defined globally, you can use service anywhere in you
 ### i18n-tasks
 
 You may also take a look at [`i18n-tasks`](https://github.com/glebm/i18n-tasks), which is a gem
-that helps you find and manage missing and unused translations. `deepl-rb` is used as one the
+that helps you find and manage missing and unused translations. `deepl-rb` is used as one of the
 backend services to translate content.
 
 ## Development
@@ -189,11 +305,3 @@ To run tests (rspec and rubocop), use
 ```
 bundle exec rake test
 ```
-
-## Contributors
-
-This project has been developed by:
-
-| Avatar | Name | Nickname | Email |
-| ------ | ---- | -------- | ----- |
-| ![](http://www.gravatar.com/avatar/2ae6d81e0605177ba9e17b19f54e6b6c.jpg?s=64)  | Daniel Herzog | Wikiti | [info@danielherzog.es](mailto:info@danielherzog.es)

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rubygems'
 require 'bundler'
 

data/VERSION

@@ -1 +1 @@
-2.2.1
+2.5.3

data/deepl-rb.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: deepl-rb 2.2.1 ruby lib
+# stub: deepl-rb 2.5.3 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "deepl-rb".freeze
-  s.version = "2.2.1"
+  s.version = "2.5.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Daniel Herzog".freeze]
-  s.date = "2020-03-08"
+  s.date = "2022-09-26"
   s.description = "A simple ruby wrapper for the DeepL translation API (v1). For more information, check this: https://www.deepl.com/docs/api-reference.html".freeze
   s.email = "info@danielherzog.es".freeze
   s.extra_rdoc_files = [
@@ -22,7 +22,6 @@ Gem::Specification.new do |s|
     ".circleci/config.yml",
     ".rubocop.yml",
     "Gemfile",
-    "Gemfile.lock",
     "LICENSE.md",
     "README.md",
     "Rakefile",
@@ -35,42 +34,71 @@ Gem::Specification.new do |s|
     "lib/deepl/exceptions/bad_request.rb",
     "lib/deepl/exceptions/error.rb",
     "lib/deepl/exceptions/limit_exceeded.rb",
+    "lib/deepl/exceptions/not_found.rb",
+    "lib/deepl/exceptions/not_supported.rb",
     "lib/deepl/exceptions/quota_exceeded.rb",
+    "lib/deepl/exceptions/request_entity_too_large.rb",
     "lib/deepl/exceptions/request_error.rb",
+    "lib/deepl/glossary_api.rb",
     "lib/deepl/requests/base.rb",
+    "lib/deepl/requests/glossary/create.rb",
+    "lib/deepl/requests/glossary/destroy.rb",
+    "lib/deepl/requests/glossary/entries.rb",
+    "lib/deepl/requests/glossary/find.rb",
+    "lib/deepl/requests/glossary/language_pairs.rb",
+    "lib/deepl/requests/glossary/list.rb",
+    "lib/deepl/requests/languages.rb",
     "lib/deepl/requests/translate.rb",
     "lib/deepl/requests/usage.rb",
     "lib/deepl/resources/base.rb",
+    "lib/deepl/resources/glossary.rb",
+    "lib/deepl/resources/language.rb",
+    "lib/deepl/resources/language_pair.rb",
     "lib/deepl/resources/text.rb",
     "lib/deepl/resources/usage.rb",
+    "lib/deepl/utils/exception_builder.rb",
     "spec/api/api_spec.rb",
     "spec/api/configuration_spec.rb",
     "spec/api/deepl_spec.rb",
+    "spec/fixtures/vcr_cassettes/deepl_glossaries.yml",
+    "spec/fixtures/vcr_cassettes/deepl_languages.yml",
     "spec/fixtures/vcr_cassettes/deepl_translate.yml",
     "spec/fixtures/vcr_cassettes/deepl_usage.yml",
+    "spec/fixtures/vcr_cassettes/glossaries.yml",
+    "spec/fixtures/vcr_cassettes/languages.yml",
     "spec/fixtures/vcr_cassettes/translate_texts.yml",
     "spec/fixtures/vcr_cassettes/usage.yml",
+    "spec/requests/glossary/create_spec.rb",
+    "spec/requests/glossary/destroy_spec.rb",
+    "spec/requests/glossary/entries_spec.rb",
+    "spec/requests/glossary/find_spec.rb",
+    "spec/requests/glossary/language_pairs_spec.rb",
+    "spec/requests/glossary/list_spec.rb",
+    "spec/requests/languages_spec.rb",
     "spec/requests/translate_spec.rb",
     "spec/requests/usage_spec.rb",
+    "spec/resources/glossary_spec.rb",
+    "spec/resources/language_pair_spec.rb",
+    "spec/resources/language_spec.rb",
     "spec/resources/text_spec.rb",
     "spec/resources/usage_spec.rb",
     "spec/spec_helper.rb"
   ]
   s.homepage = "http://github.com/wikiti/deepl-rb".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "2.6.14".freeze
+  s.rubygems_version = "3.3.7".freeze
   s.summary = "A simple ruby wrapper for the DeepL API".freeze
 
   if s.respond_to? :specification_version then
     s.specification_version = 4
+  end
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<juwelier>.freeze, [">= 0"])
-    else
-      s.add_dependency(%q<juwelier>.freeze, [">= 0"])
-    end
+  if s.respond_to? :add_runtime_dependency then
+    s.add_development_dependency(%q<juwelier>.freeze, [">= 0"])
+    s.add_development_dependency(%q<byebug>.freeze, [">= 0"])
   else
     s.add_dependency(%q<juwelier>.freeze, [">= 0"])
+    s.add_dependency(%q<byebug>.freeze, [">= 0"])
   end
 end
 

data/lib/deepl/api.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DeepL
   class API
     attr_reader :configuration

data/lib/deepl/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DeepL
   class Configuration
     ATTRIBUTES = %i[auth_key host version].freeze
@@ -6,7 +8,7 @@ module DeepL
 
     def initialize(data = {})
       data.each { |key, value| send("#{key}=", value) }
-      @auth_key ||= ENV['DEEPL_AUTH_KEY']
+      @auth_key ||= ENV.fetch('DEEPL_AUTH_KEY', nil)
       @host ||= 'https://api.deepl.com'
       @version ||= 'v2'
     end
@@ -16,7 +18,7 @@ module DeepL
     end
 
     def attributes
-      ATTRIBUTES.map { |attr| [attr, send(attr)] }.to_h
+      ATTRIBUTES.to_h { |attr| [attr, send(attr)] }
     end
 
     def ==(other)

data/lib/deepl/exceptions/authorization_failed.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DeepL
   module Exceptions
     class AuthorizationFailed < RequestError

data/lib/deepl/exceptions/bad_request.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 module DeepL
   module Exceptions
     class BadRequest < RequestError
       def message
         JSON.parse(response.body)['message']
+      rescue JSON::ParserError
+        response.body
       end
     end
   end

data/lib/deepl/exceptions/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DeepL
   module Exceptions
     class Error < StandardError

data/lib/deepl/exceptions/limit_exceeded.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DeepL
   module Exceptions
     class LimitExceeded < RequestError

data/lib/deepl/exceptions/not_found.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Exceptions
+    class NotFound < RequestError
+      def message
+        JSON.parse(response.body)['message']
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/not_supported.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Exceptions
+    class NotSupported < Error
+      def initialize(msg = 'The feature is not supported')
+        super
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/quota_exceeded.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DeepL
   module Exceptions
     class QuotaExceeded < RequestError

data/lib/deepl/exceptions/request_entity_too_large.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Exceptions
+    class RequestEntityTooLarge < RequestError
+      def message
+        'The request size has reached the supported limit. ' \
+          "Make sure that you're not sending more than 50 text parts."
+      end
+    end
+  end
+end

data/lib/deepl/exceptions/request_error.rb

@@ -1,15 +1,18 @@
+# frozen_string_literal: true
+
 module DeepL
   module Exceptions
     class RequestError < Error
       attr_reader :request, :response
 
       def initialize(request, response)
+        super()
         @request = request
         @response = response
       end
 
       def message
-        'Unkown error.'
+        'Unknown error.'
       end
     end
   end

data/lib/deepl/glossary_api.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DeepL
+  class GlossaryApi
+    def initialize(api, options = {})
+      @api = api
+      @options = options
+    end
+
+    def create(name, source_lang, target_lang, entries, options = {})
+      DeepL::Requests::Glossary::Create.new(@api, name, source_lang, target_lang, entries, options)
+                                       .request
+    end
+
+    def destroy(glossary_id, options = {})
+      DeepL::Requests::Glossary::Destroy.new(@api, glossary_id, options).request
+    end
+
+    def entries(glossary_id, options = {})
+      DeepL::Requests::Glossary::Entries.new(@api, glossary_id, options).request
+    end
+
+    def find(glossary_id, options = {})
+      DeepL::Requests::Glossary::Find.new(@api, glossary_id, options).request
+    end
+
+    def language_pairs(options = {})
+      DeepL::Requests::Glossary::LanguagePairs.new(@api, options).request
+    end
+
+    def list(options = {})
+      DeepL::Requests::Glossary::List.new(@api, options).request
+    end
+  end
+end

data/lib/deepl/requests/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DeepL
   module Requests
     class Base
@@ -22,6 +24,10 @@ module DeepL
         options[name.to_s] || options[name.to_sym]
       end
 
+      def delete_option(name)
+        options.delete(name.to_s) || options.delete(name.to_sym)
+      end
+
       def set_option(name, value)
         if options.key?(name.to_sym)
           options[name.to_sym] = value
@@ -31,8 +37,8 @@ module DeepL
       end
 
       def post(payload)
-        request = Net::HTTP::Post.new(uri.request_uri)
-        request.set_form_data(payload.reject { |_, v| v.nil? })
+        request = Net::HTTP::Post.new(uri.request_uri, headers)
+        request.set_form_data(payload.compact)
         response = http.request(request)
 
         validate_response!(request, response)
@@ -40,7 +46,15 @@ module DeepL
       end
 
       def get
-        request = Net::HTTP::Get.new(uri.request_uri)
+        request = Net::HTTP::Get.new(uri.request_uri, headers)
+        response = http.request(request)
+
+        validate_response!(request, response)
+        [request, response]
+      end
+
+      def delete
+        request = Net::HTTP::Delete.new(uri.request_uri, headers)
         response = http.request(request)
 
         validate_response!(request, response)
@@ -58,13 +72,7 @@ module DeepL
       def validate_response!(request, response)
         return if response.is_a?(Net::HTTPSuccess)
 
-        case response.code
-        when '400' then raise Exceptions::BadRequest.new(request, response)
-        when '403' then raise Exceptions::AuthorizationFailed.new(request, response)
-        when '429' then raise Exceptions::LimitExceeded.new(request, response)
-        when '456' then raise Exceptions::QuotaExceeded.new(request, response)
-        else raise Exceptions::RequestError.new(request, response)
-        end
+        raise Utils::ExceptionBuilder.new(request, response).build
       end
 
       def path
@@ -89,7 +97,11 @@ module DeepL
       end
 
       def query_params
-        { auth_key: api.configuration.auth_key }.merge(options)
+        options
+      end
+
+      def headers
+        { 'Authorization' => "DeepL-Auth-Key #{api.configuration.auth_key}" }
       end
     end
   end