deepl-rb 2.3.1 → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12e4767413ff5fc13b5b91e23cdc80c99b7252045753f7c2ef197bc4b0c0a0d2
-  data.tar.gz: 05ac02229186bc7cf8f234767f8a258b2c472e4045fa4f5c006f77bbc14314b3
+  metadata.gz: 9b243885998d697691ea44defaba15632cbe10a2738962c5befa1191b20edb53
+  data.tar.gz: 9e64eff8b57820a5f59cfc1afdde88dd16bac72f8f9de89979c1288bdc72132b
 SHA512:
-  metadata.gz: 218d0486a3ae68ab23849762976810940d8e2efb6fadc094e0b63d62e59a5c2ef06129a8a6681d8a985875a0bcf92ba4767d769826ab1a545c0a26391529808c
-  data.tar.gz: d991c7bb24a02f5c0f415bcd27c728f936a8365c20a1b91847f1cef4ba1b8031a01e23b17fe4ba7ad13aec58f6df5c2df112af2457f08a6e61cda54879cc12c9
+  metadata.gz: 8058534d4022fe77f16c5cda86e4479a7081e7d446a53282a4742f5b4ece7e66f57f1bde6e83c30a0d6dc054477bd53e7b961147e61cd7abc815af7c4c65cc72
+  data.tar.gz: d07ddd8f131b597756fd00bb5e1a43bb4d4310ab3cd4650fdd2bcd4658066063280a58c8bd9c3e0cbb5399adb1013654a89aebf7cbe5fa3fe515b7b714309194

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
 
@@ -125,11 +128,106 @@ 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:
+
+```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:
@@ -154,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:
 

data/VERSION

@@ -1 +1 @@
-2.3.1
+2.5.1

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.1 ruby lib
+# stub: deepl-rb 2.5.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "deepl-rb".freeze
-  s.version = "2.3.1"
+  s.version = "2.5.1"
 
   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-09-28"
+  s.date = "2022-06-22"
   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

@@ -8,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
@@ -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

@@ -4,16 +4,18 @@ module DeepL
   module Requests
     class Translate < Base
       BOOLEAN_CONVERSION = { true => '1', false => '0' }.freeze
-      ARRAY_CONVERSION = ->(value) { value.is_a?(Array) ? value.join(', ') : value }.freeze
+      ARRAY_CONVERSION = ->(value) { value.is_a?(Array) ? value.join(',') : value }.freeze
       OPTIONS_CONVERSIONS = {
         split_sentences: BOOLEAN_CONVERSION,
         preserve_formatting: BOOLEAN_CONVERSION,
         outline_detection: BOOLEAN_CONVERSION,
+        splitting_tags: ARRAY_CONVERSION,
         non_splitting_tags: ARRAY_CONVERSION,
         ignore_tags: ARRAY_CONVERSION
       }.freeze
 
-      attr_reader :text, :source_lang, :target_lang, :ignore_tags, :non_splitting_tags
+      attr_reader :text, :source_lang, :target_lang, :ignore_tags, :splitting_tags,
+                  :non_splitting_tags
 
       def initialize(api, text, source_lang, target_lang, options = {})
         super(api, options)

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