deepl-rb 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f531ff13d2ba139bab65f6027f2e673f6480b097847d898531ecc7a9b247faea
-  data.tar.gz: e12727852eff8153dbb3a95d853d0fbd5ef5c703f02eaf7dedd089320e6873a2
+  metadata.gz: 50a94f4bc3e0633bf578ae6fd53d794632e2b7a03b8d2a78b9678ed44289043c
+  data.tar.gz: 74e5911707588b9fd75684bbdce7092b492deafc5c3cef4e47c2732006a3bfb9
 SHA512:
-  metadata.gz: 1d783cba5c207fb772589bc3f328a942919eff214778ea739a6924022bb7589a1898ab62a1cad2b9f6b177f857beb1bd0c5fbe290eba1467c31b26ab9cad461e
-  data.tar.gz: f14387ba9bc6e7ca3b97176fe1d51f4fa001ca9caba1dc6377d13e4c573896f953575f6efa682bbf55d6704657a53eb73686f9ec51711298549b49a2e5a07701
+  metadata.gz: 9700c6128ab06b432596131da46cbdb240c433baeecb2ece7b74860040818fd3a9e32cf9c4a9384a6a8875200c4aa69f0fa74f533ffc6a4aeb9b9736e76b577f
+  data.tar.gz: 5a60db0a73691310159cfc92036c36e317f247f7bd0ece2b1002723068ffa531f43d4c96741e25e0fde4aff0fa1dc6c54596d6a91183c8ad4a75eaa62848153a

data/.rubocop.yml

@@ -4,14 +4,17 @@ 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/README.md

@@ -71,7 +71,10 @@ puts DeepL.languages(type: :target).count
 ```
 
 All languages are also defined on the
-[official API documentation](https://www.deepl.com/docs-api/translating-text/)
+[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
 
@@ -124,8 +127,105 @@ 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'`
 | `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:
+
+```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
 
@@ -151,6 +251,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:
 

data/VERSION

@@ -1 +1 @@
-2.3.0
+2.5.0

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.3.0 ruby lib
+# stub: deepl-rb 2.5.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "deepl-rb".freeze
-  s.version = "2.3.0"
+  s.version = "2.5.0"
 
   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 = "2021-05-17"
+  s.date = "2022-06-06"
   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 = [
@@ -34,28 +34,49 @@ 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_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",
     "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",
@@ -63,7 +84,7 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "http://github.com/wikiti/deepl-rb".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.1.2".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

data/lib/deepl/configuration.rb

@@ -18,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/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/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

@@ -24,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
@@ -33,7 +37,7 @@ module DeepL
       end
 
       def post(payload)
-        request = Net::HTTP::Post.new(uri.request_uri)
+        request = Net::HTTP::Post.new(uri.request_uri, headers)
         request.set_form_data(payload.compact)
         response = http.request(request)
 
@@ -42,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)
@@ -62,7 +74,8 @@ module DeepL
 
         case response.code
         when '400' then raise Exceptions::BadRequest.new(request, response)
-        when '403' then raise Exceptions::AuthorizationFailed.new(request, response)
+        when '401', '403' then raise Exceptions::AuthorizationFailed.new(request, response)
+        when '404' then raise Exceptions::NotFound.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)
@@ -91,7 +104,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

data/lib/deepl/requests/glossary/create.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Glossary
+      class Create < Base
+        attr_reader :name, :source_lang, :target_lang, :entries, :entries_format
+
+        def initialize(api, name, source_lang, target_lang, entries, options = {})
+          super(api, options)
+          @name = name
+          @source_lang = source_lang
+          @target_lang = target_lang
+          @entries = entries
+          @entries_format = delete_option(:entries_format) || 'tsv'
+        end
+
+        def request
+          payload = {
+            name: name, source_lang: source_lang, target_lang: target_lang, entries: entries_to_tsv,
+            entries_format: entries_format
+          }
+          build_glossary(*post(payload))
+        end
+
+        private
+
+        def entries_to_tsv
+          return entries if entries.is_a?(String)
+
+          entries.reduce('') { |tsv, entry| "#{tsv}#{entry.first}\t#{entry.last}\n" }
+        end
+
+        def build_glossary(request, response)
+          glossary = JSON.parse(response.body)
+          Resources::Glossary.new(glossary, request, response)
+        end
+
+        def path
+          'glossaries'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/glossary/destroy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Glossary
+      class Destroy < Base
+        attr_reader :id
+
+        def initialize(api, id, options = {})
+          super(api, options)
+          @id = id
+        end
+
+        def request
+          build_response(*delete)
+        end
+
+        private
+
+        def build_response(_, _)
+          id
+        end
+
+        def path
+          "glossaries/#{id}"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/glossary/entries.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Glossary
+      class Entries < Base
+        attr_reader :id
+
+        def initialize(api, id, options = {})
+          super(api, options)
+          @id = id
+        end
+
+        def request
+          build_entries(*get)
+        end
+
+        private
+
+        def build_entries(_, response)
+          response.body.split("\n").map { |entry| entry.split("\t") }
+        end
+
+        def path
+          "glossaries/#{id}/entries"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/glossary/find.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Glossary
+      class Find < Base
+        attr_reader :id
+
+        def initialize(api, id, options = {})
+          super(api, options)
+          @id = id
+        end
+
+        def request
+          build_glossary(*get)
+        end
+
+        private
+
+        def build_glossary(request, response)
+          glossary = JSON.parse(response.body)
+          Resources::Glossary.new(glossary, request, response)
+        end
+
+        def path
+          "glossaries/#{id}"
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/glossary/language_pairs.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Glossary
+      class LanguagePairs < Base
+        def initialize(api, options = {})
+          super(api, options)
+        end
+
+        def request
+          build_language_pair_list(*get)
+        end
+
+        private
+
+        def build_language_pair_list(request, response)
+          data = JSON.parse(response.body)
+          data['supported_languages'].map do |language_pair|
+            Resources::LanguagePair.new(language_pair['source_lang'], language_pair['target_lang'],
+                                        request, response)
+          end
+        end
+
+        def path
+          'glossary-language-pairs'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/glossary/list.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    module Glossary
+      class List < Base
+        def initialize(api, options = {})
+          super(api, options)
+        end
+
+        def request
+          build_glossary_list(*get)
+        end
+
+        private
+
+        def build_glossary_list(request, response)
+          data = JSON.parse(response.body)
+          data['glossaries'].map do |glossary|
+            Resources::Glossary.new(glossary, request, response)
+          end
+        end
+
+        def path
+          'glossaries'
+        end
+      end
+    end
+  end
+end

data/lib/deepl/requests/languages.rb

@@ -16,7 +16,9 @@ module DeepL
       def build_languages(request, response)
         data = JSON.parse(response.body)
         data.map do |language|
-          Resources::Language.new(language['language'], language['name'], request, response)
+          Resources::Language.new(language['language'], language['name'],
+                                  language['supports_formality'],
+                                  request, response)
         end
       end
 

data/lib/deepl/requests/translate.rb

@@ -8,6 +8,7 @@ module DeepL
       OPTIONS_CONVERSIONS = {
         split_sentences: BOOLEAN_CONVERSION,
         preserve_formatting: BOOLEAN_CONVERSION,
+        outline_detection: BOOLEAN_CONVERSION,
         non_splitting_tags: ARRAY_CONVERSION,
         ignore_tags: ARRAY_CONVERSION
       }.freeze

data/lib/deepl/resources/glossary.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    class Glossary < Base
+      attr_reader :id, :name, :ready, :source_lang, :target_lang, :creation_time, :entry_count
+
+      def initialize(glossary, *args)
+        super(*args)
+
+        @id = glossary['glossary_id']
+        @name = glossary['name']
+        @ready = glossary['ready']
+        @source_lang = glossary['source_lang']
+        @target_lang = glossary['target_lang']
+        @creation_time = glossary['creation_time']
+        @entry_count = glossary['entry_count']
+      end
+
+      def to_s
+        "#{id} - #{name}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/language.rb

@@ -5,16 +5,23 @@ module DeepL
     class Language < Base
       attr_reader :code, :name
 
-      def initialize(code, name, *args)
+      def initialize(code, name, supports_formality, *args)
         super(*args)
 
         @code = code
         @name = name
+        @supports_formality = supports_formality
       end
 
       def to_s
         "#{code} - #{name}"
       end
+
+      def supports_formality?
+        return @supports_formality unless @supports_formality.nil?
+
+        raise Exceptions::NotSupported, 'Support formality is only available on target languages'
+      end
     end
   end
 end

data/lib/deepl/resources/language_pair.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DeepL
+  module Resources
+    class LanguagePair < Base
+      attr_reader :source_lang, :target_lang
+
+      def initialize(source_lang, target_lang, *args)
+        super(*args)
+
+        @source_lang = source_lang
+        @target_lang = target_lang
+      end
+
+      def to_s
+        "#{source_lang} - #{target_lang}"
+      end
+    end
+  end
+end