deepl-rb 3.0.2 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ed15fdabc7d3b893b4590bda599106140c9c06c7d4d67cc6ff2a679a05ba301
-  data.tar.gz: fee679c9456728c0679ebdf66ea501d7924eb49e9e1e480520a50a6c7cfed3d9
+  metadata.gz: 47bf797967929a4b7775e21ce7021cdc1871283b3358cbb36d13a8f6f6b5ac6b
+  data.tar.gz: df4399cc6c552fb5c03b79b0566d2370101b58246bfd5e0b05d27c83e994ae6c
 SHA512:
-  metadata.gz: eefd241705fc379dd6de1574a63f83380cb445a6d883c7d2db6da3827691b79845b06f37227c0ea0285738066ba1850782e0462ec9fab9a02816205ab416ba35
-  data.tar.gz: c6f0789c07f2f23c27a9ee979812b0d76bde2edb308cd2e6c422f826a089f561cdb6c80317dfecb27ed94d9f2ee6c6340135548ea3866bb21084896da28ceb3d
+  metadata.gz: 4639c87e107dfa0a13b1bace938e9a3580fb15bb1e2f280267527e3d5d0c9b8913752b841bd095039f1e4f7d15b13813075131c0767216855bf5e7d28a4b81a1
+  data.tar.gz: 19743f57e84c550e5fe35b1d6c39f853df1d0d1d357eb8c0f061a0202831af8a557651f34f50dcad10928b45638a3a09b9ab64652fdadab6d6ad62ec3f2a1242

data/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0]
+### Added
+* Added `rephrase` functionality to get a new version of submitted text with various possible styles or tones applied
+* Added `DeepL::Constants` namespace and associated constant values for options possibilities
+
+## [3.1.0]
+### Added
+* Added `model_type` option to `translate()` to use models with higher
+  translation quality (available for some language pairs), or better latency.
+  Options are `'quality_optimized'`, `'latency_optimized'`, and  `'prefer_quality_optimized'`
+* Added the `model_type_used` field to the `translate()` response, that
+  indicates the translation model used when the `model_type` option is
+  specified.
+
 
 ## [3.0.2] - 2024-10-02
 ### Added
@@ -40,7 +54,8 @@ The change in major version is only due to the change in maintainership, there i
 ### Fixed
 * Make RequestEntityTooLarge error message more clear
 
-
+[3.2.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.1.0...3.2.0
+[3.1.0]: https://github.com/DeepLcom/deepl-rb/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/DeepLcom/deepl-rb/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/DeepLcom/deepl-rb/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/DeepLcom/deepl-rb/compare/v2.5.3...v3.0.0

data/README.md

@@ -137,6 +137,23 @@ puts translation.text
 # => "¡Eso es picante!"
 ```
 
+To specify a type of translation model to use, you can use the `model_type` option:
+
+```rb
+translation = DeepL.translate 'That is hot!', 'EN', 'DE',
+                              model_type: 'quality_optimized'
+```
+
+This would use next-gen translation models for the translation. The available values are
+
+- `'quality_optimized'`: use a translation model that maximizes translation quality, at the
+  cost of response time. This option may be unavailable for some language pairs.
+- `'prefer_quality_optimized'`: use the highest-quality translation model for the given
+  language pair.
+- `'latency_optimized'`: use a translation model that minimizes response time, at the cost
+  of translation quality.
+
+
 The following parameters will be automatically converted:
 
 | Parameter             | Conversion
@@ -151,6 +168,37 @@ The following parameters will be automatically converted:
 | `glossary_id`         | No conversion applied
 | `context`             | No conversion applied
 
+### Rephrase Text
+
+To rephrase or improve text, including changing the writing style or tone of the text, use the `rephrase` method:
+
+```rb
+rephrased_text = DeepL.rephrase 'you will acquire new rephrased text', 'EN'
+
+puts rephrased_text.class
+# => DeepL::Resources::Text
+puts rephrased_text.text
+# => 'You get new rephrased text.'
+```
+
+As with translate, the text input can be a single string or an array of strings.
+
+You can use the additional arguments to specify the writing style or tone you want for the rephrased text:
+
+```rb
+rephrased_text = DeepL.rephrase 'you will acquire new rephrased text', 'EN', 'casual'
+
+puts rephrased_text.text
+# => 'You'll get new, rephrased text.'
+```
+
+```rb
+rephrased_text = DeepL.rephrase 'you will acquire new rephrased text', 'EN', nil, 'friendly'
+
+puts rephrased_text.text
+# => 'You'll get to enjoy new, rephrased text!'
+```
+
 ### 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.
@@ -372,6 +420,30 @@ end
 
 This information is passed along when the library makes calls to the DeepL API. Both name and version are required. Please note that setting the `User-Agent` header via `deepl.configure` will override this setting, if you need to use this, please manually identify your Application in the `User-Agent` header.
 
+## Options Constants
+
+The available values for various possible options are provided under the `DeepL::Constants` namespace. The currently available options are
+
+`TagHandling`
+`SplitSentences`
+`ModelType`
+`Formality`
+`WritingStyle`
+`Tone`
+
+To view all the possible options for a given constant, call `options`:
+
+```rb
+all_available_tones = DeepL::Constants::Tones.options
+```
+
+To check if a given string is a possible option for a given constant, call `valid?`:
+
+```rb
+DeepL::Constants::Tones.valid?('friendly') # true
+DeepL::Constants::Tones.valid?('rude') # false
+```
+
 ## Integrations
 
 ### Ruby on Rails

data/VERSION

@@ -1 +1 @@
-3.0.2
+3.2.0

data/deepl-rb.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: deepl-rb 3.0.2 ruby lib
+# stub: deepl-rb 3.2.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "deepl-rb".freeze
-  s.version = "3.0.2"
+  s.version = "3.2.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.metadata = { "bug_tracker_uri" => "https://github.com/DeepLcom/deepl-rb/issues", "changelog_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/CHANGELOG.md", "documentation_uri" => "https://github.com/DeepLcom/deepl-rb/blob/main/README.md", "homepage_uri" => "https://github.com/DeepLcom/deepl-rb" } if s.respond_to? :metadata=
   s.require_paths = ["lib".freeze]
   s.authors = ["DeepL SE".freeze]
-  s.date = "2024-10-02"
+  s.date = "2025-01-15"
   s.description = "Official Ruby library for the DeepL language translation API (v2). For more information, check this: https://www.deepl.com/docs/api-reference.html".freeze
   s.email = "open-source@deepl.com".freeze
   s.extra_rdoc_files = [
@@ -39,6 +39,13 @@ Gem::Specification.new do |s|
     "lib/deepl.rb",
     "lib/deepl/api.rb",
     "lib/deepl/configuration.rb",
+    "lib/deepl/constants/base_constant.rb",
+    "lib/deepl/constants/formality.rb",
+    "lib/deepl/constants/model_type.rb",
+    "lib/deepl/constants/split_sentences.rb",
+    "lib/deepl/constants/tag_handling.rb",
+    "lib/deepl/constants/tone.rb",
+    "lib/deepl/constants/writing_style.rb",
     "lib/deepl/document_api.rb",
     "lib/deepl/exceptions/authorization_failed.rb",
     "lib/deepl/exceptions/bad_request.rb",
@@ -63,6 +70,7 @@ Gem::Specification.new do |s|
     "lib/deepl/requests/glossary/language_pairs.rb",
     "lib/deepl/requests/glossary/list.rb",
     "lib/deepl/requests/languages.rb",
+    "lib/deepl/requests/rephrase.rb",
     "lib/deepl/requests/translate.rb",
     "lib/deepl/requests/usage.rb",
     "lib/deepl/resources/base.rb",
@@ -80,6 +88,7 @@ Gem::Specification.new do |s|
     "spec/api/api_spec.rb",
     "spec/api/configuration_spec.rb",
     "spec/api/deepl_spec.rb",
+    "spec/constants/constants_spec.rb",
     "spec/fixtures/vcr_cassettes/deepl_document.yml",
     "spec/fixtures/vcr_cassettes/deepl_document_download.yml",
     "spec/fixtures/vcr_cassettes/deepl_glossaries.yml",
@@ -88,6 +97,7 @@ Gem::Specification.new do |s|
     "spec/fixtures/vcr_cassettes/deepl_usage.yml",
     "spec/fixtures/vcr_cassettes/glossaries.yml",
     "spec/fixtures/vcr_cassettes/languages.yml",
+    "spec/fixtures/vcr_cassettes/rephrase_texts.yml",
     "spec/fixtures/vcr_cassettes/translate_texts.yml",
     "spec/fixtures/vcr_cassettes/usage.yml",
     "spec/integration_tests/document_api_spec.rb",
@@ -99,6 +109,7 @@ Gem::Specification.new do |s|
     "spec/requests/glossary/language_pairs_spec.rb",
     "spec/requests/glossary/list_spec.rb",
     "spec/requests/languages_spec.rb",
+    "spec/requests/rephrase_spec.rb",
     "spec/requests/translate_spec.rb",
     "spec/requests/usage_spec.rb",
     "spec/resources/glossary_spec.rb",
@@ -110,12 +121,12 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "https://github.com/DeepLcom/deepl-rb".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.4.6".freeze
+  s.rubygems_version = "3.5.3".freeze
   s.summary = "Official Ruby library for the DeepL language translation API.".freeze
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<juwelier>.freeze, [">= 0"])
-  s.add_development_dependency(%q<byebug>.freeze, [">= 0"])
+  s.add_development_dependency(%q<juwelier>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<byebug>.freeze, [">= 0".freeze])
 end
 

data/lib/deepl/constants/base_constant.rb

@@ -0,0 +1,18 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class BaseConstant
+      def self.options
+        constants.map { |const| const_get(const) }
+      end
+
+      def self.valid?(value)
+        options.include?(value)
+      end
+    end
+  end
+end

data/lib/deepl/constants/formality.rb

@@ -0,0 +1,16 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class Formality < BaseConstant
+      DEFAULT = 'default'
+      MORE = 'more'
+      LESS = 'less'
+      PREFER_MORE = 'prefer_more'
+      PREFER_LESS = 'prefer_less'
+    end
+  end
+end

data/lib/deepl/constants/model_type.rb

@@ -0,0 +1,14 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class ModelType < BaseConstant
+      QUALITY_OPTIMIZED = 'quality_optimized'
+      PREFER_QUALITY_OPTIMIZED = 'prefer_quality_optimized'
+      LATENCY_OPTIMIZED = 'latency_optimized'
+    end
+  end
+end

data/lib/deepl/constants/split_sentences.rb

@@ -0,0 +1,14 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class SplitSentences < BaseConstant
+      NO_SPLITTING = '0'
+      SPLIT_ON_PUNCTUATION_AND_NEWLINES = '1'
+      SPLIT_ON_PUNCTUATION_ONLY = 'nonewlines'
+    end
+  end
+end

data/lib/deepl/constants/tag_handling.rb

@@ -0,0 +1,13 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class TagHandling < BaseConstant
+      XML = 'xml'
+      HTML = 'html'
+    end
+  end
+end

data/lib/deepl/constants/tone.rb

@@ -0,0 +1,20 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class Tone < BaseConstant
+      DEFAULT = 'default'
+      ENTHUSIASTIC = 'enthusiastic'
+      FRIENDLY = 'friendly'
+      CONFIDENT = 'confident'
+      DIPLOMATIC = 'diplomatic'
+      PREFER_ENTHUSIASTIC = 'prefer_enthusiastic'
+      PREFER_FRIENDLY = 'prefer_friendly'
+      PREFER_CONFIDENT = 'prefer_confident'
+      PREFER_DIPLOMATIC = 'prefer_diplomatic'
+    end
+  end
+end

data/lib/deepl/constants/writing_style.rb

@@ -0,0 +1,20 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Constants
+    class WritingStyle < BaseConstant
+      DEFAULT = 'default'
+      SIMPLE = 'simple'
+      BUSINESS = 'business'
+      ACADEMIC = 'academic'
+      CASUAL = 'casual'
+      PREFER_SIMPLE = 'prefer_simple'
+      PREFER_BUSINESS = 'prefer_business'
+      PREFER_ACADEMIC = 'prefer_academic'
+      PREFER_CASUAL = 'prefer_casual'
+    end
+  end
+end

data/lib/deepl/requests/rephrase.rb

@@ -0,0 +1,54 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+module DeepL
+  module Requests
+    class Rephrase < Base
+      attr_reader :text, :target_lang, :writing_style, :tone
+
+      def initialize(api, text, target_lang, writing_style = nil, tone = nil, options = {})
+        super(api, options)
+        @text = text
+        @target_lang = target_lang
+        @writing_style = writing_style
+        @tone = tone
+      end
+
+      def request
+        text_arrayified = text.is_a?(Array) ? text : [text]
+        payload = { text: text_arrayified, target_lang: target_lang }
+        payload[:writing_style] = writing_style unless writing_style.nil?
+        payload[:tone] = tone unless tone.nil?
+        build_texts(*execute_request_with_retries(post_request(payload)))
+      end
+
+      def details
+        "HTTP Headers: #{headers}\nPayload #{{ text: text, target_lang: target_lang,
+                                               writing_style: writing_style, tone: tone }}"
+      end
+
+      def to_s
+        "POST #{uri.request_uri}"
+      end
+
+      private
+
+      def build_texts(request, response)
+        data = JSON.parse(response.body)
+
+        texts = data['improvements'].map do |improvement|
+          Resources::Text.new(improvement['text'], improvement['detected_source_language'], nil,
+                              request, response)
+        end
+
+        texts.size == 1 ? texts.first : texts
+      end
+
+      def path
+        'write/rephrase'
+      end
+    end
+  end
+end

data/lib/deepl/requests/translate.rb

@@ -27,7 +27,7 @@ module DeepL
       }.freeze
 
       attr_reader :text, :source_lang, :target_lang, :ignore_tags, :splitting_tags,
-                  :non_splitting_tags
+                  :non_splitting_tags, :model_type
 
       def initialize(api, text, source_lang, target_lang, options = {})
         super(api, options)
@@ -68,7 +68,7 @@ module DeepL
 
         texts = data['translations'].map do |translation|
           Resources::Text.new(translation['text'], translation['detected_source_language'],
-                              request, response)
+                              translation['model_type_used'], request, response)
         end
 
         texts.size == 1 ? texts.first : texts

data/lib/deepl/resources/text.rb

@@ -6,13 +6,14 @@
 module DeepL
   module Resources
     class Text < Base
-      attr_reader :text, :detected_source_language
+      attr_reader :text, :detected_source_language, :model_type_used
 
-      def initialize(text, detected_source_language, *args)
+      def initialize(text, detected_source_language, model_type_used, *args)
         super(*args)
 
         @text = text
         @detected_source_language = detected_source_language
+        @model_type_used = model_type_used
       end
 
       def to_s

data/lib/deepl.rb

@@ -34,6 +34,7 @@ require 'deepl/requests/glossary/list'
 require 'deepl/requests/languages'
 require 'deepl/requests/translate'
 require 'deepl/requests/usage'
+require 'deepl/requests/rephrase'
 
 # -- Responses and resources
 require 'deepl/resources/base'
@@ -49,6 +50,15 @@ require 'deepl/resources/usage'
 require 'deepl/utils/exception_builder'
 require 'deepl/utils/backoff_timer'
 
+# -- Constants
+require 'deepl/constants/base_constant'
+require 'deepl/constants/formality'
+require 'deepl/constants/model_type'
+require 'deepl/constants/split_sentences'
+require 'deepl/constants/tag_handling'
+require 'deepl/constants/tone'
+require 'deepl/constants/writing_style'
+
 # -- HTTP Utils
 require 'http_client_options'
 

data/spec/constants/constants_spec.rb

@@ -0,0 +1,158 @@
+# Copyright 2025 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE.md file.
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'DeepL::Constants' do
+  describe DeepL::Constants::Tone do
+    subject(:tone) { described_class }
+
+    it 'includes all expected tone values' do # rubocop:disable RSpec/ExampleLength
+      expect(tone.options).to contain_exactly(
+        'confident',
+        'default',
+        'diplomatic',
+        'enthusiastic',
+        'friendly',
+        'prefer_confident',
+        'prefer_diplomatic',
+        'prefer_enthusiastic',
+        'prefer_friendly'
+      )
+    end
+
+    it 'validates correct tone values' do
+      expect(tone.valid?('enthusiastic')).to be true
+      expect(tone.valid?('friendly')).to be true
+      expect(tone.valid?('confident')).to be true
+      expect(tone.valid?('diplomatic')).to be true
+      expect(tone.valid?('default')).to be true
+    end
+
+    it 'invalidates incorrect tone values' do
+      expect(tone.valid?('angry')).to be false
+      expect(tone.valid?('')).to be false
+      expect(tone.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::WritingStyle do
+    subject(:writing_style) { described_class }
+
+    it 'includes all expected writing style values' do # rubocop:disable RSpec/ExampleLength
+      expect(writing_style.options).to contain_exactly(
+        'default',
+        'simple',
+        'business',
+        'academic',
+        'casual',
+        'prefer_academic',
+        'prefer_business',
+        'prefer_casual',
+        'prefer_simple'
+      )
+    end
+
+    it 'validates correct writing style values' do
+      expect(writing_style.valid?('simple')).to be true
+      expect(writing_style.valid?('business')).to be true
+      expect(writing_style.valid?('academic')).to be true
+      expect(writing_style.valid?('casual')).to be true
+      expect(writing_style.valid?('default')).to be true
+    end
+
+    it 'invalidates incorrect writing style values' do
+      expect(writing_style.valid?('wordy')).to be false
+      expect(writing_style.valid?('')).to be false
+      expect(writing_style.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::TagHandling do
+    subject(:tag_handling) { described_class }
+
+    it 'includes all expected tag handling values' do
+      expect(tag_handling.options).to contain_exactly('xml', 'html')
+    end
+
+    it 'validates correct tag handling values' do
+      expect(tag_handling.valid?('xml')).to be true
+      expect(tag_handling.valid?('html')).to be true
+    end
+
+    it 'invalidates incorrect tag handling values' do
+      expect(tag_handling.valid?('json')).to be false
+      expect(tag_handling.valid?('')).to be false
+      expect(tag_handling.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::SplitSentences do
+    subject(:split_sentences) { described_class }
+
+    it 'includes all expected split sentences values' do
+      expect(split_sentences.options).to contain_exactly('0', '1', 'nonewlines')
+    end
+
+    it 'validates correct split sentences values' do
+      expect(split_sentences.valid?('0')).to be true
+      expect(split_sentences.valid?('1')).to be true
+      expect(split_sentences.valid?('nonewlines')).to be true
+    end
+
+    it 'invalidates incorrect split sentences values' do
+      expect(split_sentences.valid?('2')).to be false
+      expect(split_sentences.valid?('')).to be false
+      expect(split_sentences.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::ModelType do
+    subject(:model_type) { described_class }
+
+    it 'includes all expected model type values' do
+      expect(model_type.options).to contain_exactly(
+        'quality_optimized',
+        'prefer_quality_optimized',
+        'latency_optimized'
+      )
+    end
+
+    it 'validates correct model type values' do
+      expect(model_type.valid?('quality_optimized')).to be true
+      expect(model_type.valid?('prefer_quality_optimized')).to be true
+      expect(model_type.valid?('latency_optimized')).to be true
+    end
+
+    it 'invalidates incorrect model type values' do
+      expect(model_type.valid?('speed_optimized')).to be false
+      expect(model_type.valid?('')).to be false
+      expect(model_type.valid?(nil)).to be false
+    end
+  end
+
+  describe DeepL::Constants::Formality do
+    subject(:formality) { described_class }
+
+    it 'includes all expected formality values' do
+      expect(formality.options).to contain_exactly('default', 'more', 'less', 'prefer_more',
+                                                   'prefer_less')
+    end
+
+    it 'validates correct formality values' do
+      expect(formality.valid?('default')).to be true
+      expect(formality.valid?('more')).to be true
+      expect(formality.valid?('less')).to be true
+      expect(formality.valid?('prefer_more')).to be true
+      expect(formality.valid?('prefer_less')).to be true
+    end
+
+    it 'invalidates incorrect formality values' do
+      expect(formality.valid?('neutral')).to be false
+      expect(formality.valid?('')).to be false
+      expect(formality.valid?(nil)).to be false
+    end
+  end
+end