deepl-rb 3.9.0 → 3.10.0

data/lib/deepl/resources/multilingual_glossary.rb

@@ -0,0 +1,112 @@
+# Copyright 2026 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 Resources
+    class MultilingualGlossaryDictionary < Base
+      attr_reader :source_lang, :target_lang, :entry_count
+
+      def initialize(dictionary, *args)
+        super(*args)
+
+        @source_lang = dictionary['source_lang']
+        @target_lang = dictionary['target_lang']
+        @entry_count = dictionary['entry_count']
+      end
+
+      def to_s
+        "#{source_lang} -> #{target_lang} (#{entry_count})"
+      end
+    end
+
+    # The entries of one dictionary. Used as input for +create_multilingual_glossary+,
+    # +update_multilingual_glossary+, +update_multilingual_glossary_dictionary+ and
+    # +replace_multilingual_glossary_dictionary+, and returned by
+    # +get_multilingual_glossary_dictionary_entries+.
+    class MultilingualGlossaryDictionaryEntries < Base
+      # @return [Hash{String => String}] The target term of each source term.
+      attr_reader :entries
+      attr_reader :source_lang, :target_lang
+
+      ##
+      # @param [String] source_lang Source language code, for example +'en'+.
+      # @param [String] target_lang Target language code, for example +'de'+.
+      # @param [Hash{String => String}, Array<Array(String, String)>, String] entries The target
+      #   term of each source term, as a hash, source/target pairs or a TSV string; terms are
+      #   stripped and checked when sent.
+      # @raise [DeepL::Exceptions::ValidationError] If a pair or TSV line is not exactly two
+      #   terms, or a source term appears twice.
+      def initialize(source_lang, target_lang, entries, request = nil, response = nil)
+        super(request, response)
+
+        @source_lang = source_lang
+        @target_lang = target_lang
+        pairs = entries.is_a?(String) ? self.class.tsv_to_pairs(entries) : entries.to_a
+        @entries = self.class.check_pairs!(pairs).to_h
+      end
+
+      # @api private
+      # Builds the entries from a dictionary of the API, whose entries are a TSV string.
+      def self.from_response(dictionary, request, response)
+        entries = (dictionary['entries'] || '').split(/\r?\n/).reject(&:empty?).to_h do |line|
+          source, target = line.split("\t", 2)
+          [source, target]
+        end
+        new(dictionary['source_lang'], dictionary['target_lang'], entries, request, response)
+      end
+
+      # @api private
+      # Raises ValidationError unless each pair is two strings and no source term, stripped as
+      # the term check strips it, appears twice. Returns +pairs+.
+      def self.check_pairs!(pairs)
+        seen = {}
+        pairs.each do |pair|
+          unless pair.is_a?(Array) && pair.size == 2 && pair.all?(String)
+            raise Exceptions::ValidationError, "Entry #{pair.inspect} must be two terms"
+          end
+
+          source = pair.first.strip
+          next seen[source] = true unless seen[source]
+
+          raise Exceptions::ValidationError, "Duplicate source term #{source.inspect}"
+        end
+      end
+
+      # @api private
+      # One source/target pair per non-blank line, separated by a single tab.
+      def self.tsv_to_pairs(tsv)
+        tsv.split(/\r?\n/).reject { |line| line.strip.empty? }.map do |line|
+          pair = line.split("\t", -1)
+          unless pair.size == 2
+            raise Exceptions::ValidationError,
+                  "TSV entry #{line.inspect} must be a source and a target term separated by " \
+                  'one tab'
+          end
+
+          pair
+        end
+      end
+    end
+
+    class MultilingualGlossary < Base
+      attr_reader :id, :name, :creation_time, :dictionaries
+
+      def initialize(glossary, *args)
+        super(*args)
+
+        @id = glossary['glossary_id']
+        @name = glossary['name']
+        @creation_time = Utils::TimeParser.parse_optional_utc_time(glossary['creation_time'])
+        @dictionaries = (glossary['dictionaries'] || []).map do |dictionary|
+          MultilingualGlossaryDictionary.new(dictionary, *args)
+        end
+      end
+
+      def to_s
+        "#{id} - #{name}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/spoken_terms.rb

@@ -0,0 +1,61 @@
+# Copyright 2026 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 Resources
+    # The term count of one language in a spoken terms collection.
+    class SpokenTermsList < Base
+      attr_reader :lang, :entry_count
+
+      def initialize(term_list, *args)
+        super(*args)
+
+        @lang = term_list['lang']
+        @entry_count = term_list['entry_count']
+      end
+
+      def to_s
+        "#{lang} (#{entry_count})"
+      end
+    end
+
+    # The terms of one language. Used as input for +create_spoken_terms+,
+    # +update_spoken_terms+ and +replace_spoken_terms_list+, and returned by
+    # +get_spoken_terms_entries+.
+    class SpokenTermsEntries < Base
+      attr_reader :lang, :entries
+
+      ##
+      # @param [String] lang Language code, for example +'en'+.
+      # @param [Array<String>] entries The terms, one per element.
+      def initialize(lang, entries, request = nil, response = nil)
+        super(request, response)
+
+        @lang = lang
+        @entries = entries
+      end
+    end
+
+    # A spoken terms collection.
+    class SpokenTerms < Base
+      attr_reader :spoken_terms_id, :name, :creation_time, :term_lists
+
+      def initialize(spoken_terms, *args)
+        super(*args)
+
+        @spoken_terms_id = spoken_terms['spoken_terms_id']
+        @name = spoken_terms['name']
+        @creation_time = Utils::TimeParser.parse_optional_utc_time(spoken_terms['creation_time'])
+        @term_lists = (spoken_terms['term_lists'] || []).map do |term_list|
+          SpokenTermsList.new(term_list, *args)
+        end
+      end
+
+      def to_s
+        "#{spoken_terms_id} - #{name}"
+      end
+    end
+  end
+end

data/lib/deepl/resources/style_profile.rb

@@ -0,0 +1,44 @@
+# Copyright 2026 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 Resources
+    # A style profile: a named set of glossaries, style rule lists and translation memories.
+    class StyleProfile < Base
+      attr_reader :style_profile_id, :name, :description, :industry, :glossary_ids, :style_rule_ids,
+                  :translation_memory_ids, :glossary_priority_order_enabled, :creation_time,
+                  :updated_time
+
+      def initialize(profile, *args) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        super(*args)
+
+        @style_profile_id = profile['style_profile_id']
+        @name = profile['name']
+        @description = optional_string(profile['description'])
+        @industry = optional_string(profile['industry'])
+        @glossary_ids = id_list(profile['glossary_ids'])
+        @style_rule_ids = id_list(profile['style_rule_ids'])
+        @translation_memory_ids = id_list(profile['translation_memory_ids'])
+        @glossary_priority_order_enabled = profile['glossary_priority_order_enabled'] == true
+        @creation_time = Utils::TimeParser.parse_optional_utc_time(profile['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_utc_time(profile['updated_time'])
+      end
+
+      def to_s
+        "#{style_profile_id} - #{name}"
+      end
+
+      private
+
+      def optional_string(value)
+        value if value.is_a?(String)
+      end
+
+      def id_list(value)
+        value.is_a?(Array) ? value.grep(String) : []
+      end
+    end
+  end
+end

data/lib/deepl/resources/style_rule.rb

@@ -80,6 +80,9 @@ module DeepL
         return nil unless time_string
 
         Time.parse(time_string)
+      rescue ArgumentError, TypeError
+        raise Exceptions::Error,
+              "Unexpected response from the DeepL API: invalid time #{time_string.inspect}"
       end
     end
   end

data/lib/deepl/resources/text.rb

@@ -6,14 +6,30 @@
 module DeepL
   module Resources
     class Text < Base
+      # @return [Integer, nil] Number of characters billed for the text, +nil+ if the response
+      #   does not contain it.
+      attr_reader :billed_characters
+      # @return [String, nil] Tag handling algorithm version used (see
+      #   +DeepL::Constants::TagHandlingVersion+), +nil+ if the response does not contain it.
+      attr_reader :tag_handling_version
+      # @return [String, nil] Target language of a rephrase or correct result, +nil+ for text
+      #   translation results and if the response does not contain it.
+      attr_reader :target_language
       attr_reader :text, :detected_source_language, :model_type_used
 
-      def initialize(text, detected_source_language, model_type_used, *args)
-        super(*args)
+      # Positional, not keyword, parameters: Ruby 2.7 would read the response (it has +to_hash+)
+      # as keywords.
+      def initialize(text, detected_source_language, model_type_used, request = nil, # rubocop:disable Metrics/ParameterLists
+                     response = nil, billed_characters = nil, tag_handling_version = nil,
+                     target_language = nil)
+        super(request, response)
 
         @text = text
         @detected_source_language = detected_source_language
         @model_type_used = model_type_used
+        @billed_characters = billed_characters
+        @tag_handling_version = tag_handling_version
+        @target_language = target_language
       end
 
       def to_s

data/lib/deepl/resources/translation_memory.rb

@@ -16,13 +16,19 @@ module DeepL
         @source_language = translation_memory['source_language']
         @target_languages = translation_memory['target_languages'] || []
         @segment_count = translation_memory['segment_count'] || 0
-        @creation_time = Utils::TimeParser.parse_optional_time(translation_memory['creation_time'])
-        @updated_time = Utils::TimeParser.parse_optional_time(translation_memory['updated_time'])
+        @creation_time = parse_time(translation_memory['creation_time'])
+        @updated_time = parse_time(translation_memory['updated_time'])
       end
 
       def to_s
         "#{translation_memory_id} - #{name}"
       end
+
+      private
+
+      def parse_time(value)
+        Utils::TimeParser.parse_optional_utc_time(value)
+      end
     end
   end
 end

data/lib/deepl/resources/translation_memory_import.rb

@@ -16,7 +16,7 @@ module DeepL
         super(*args)
         @job_id = translation_memory_import['job_id']
         @upload_url = translation_memory_import['upload_url']
-        @expires_at = Utils::TimeParser.parse_optional_time(
+        @expires_at = Utils::TimeParser.parse_optional_utc_time(
           translation_memory_import['expires_at']
         )
       end

data/lib/deepl/resources/translation_memory_job.rb

@@ -26,7 +26,7 @@ module DeepL
         @status = result['status']
         @required_action = status_metadata['required_action']
         @download_url = result['download_url']
-        @expires_at = Utils::TimeParser.parse_optional_time(result['expires_at'])
+        @expires_at = Utils::TimeParser.parse_optional_utc_time(result['expires_at'])
         @error_message = error['message']
         @translation_memory_id = result['translation_memory_id']
         @skipped_segment_count = result['skipped_segment_count']
@@ -110,6 +110,26 @@ module DeepL
         result ? result.error? : false
       end
 
+      ##
+      # Checks if the job succeeded: its status is +completed+. Unlike +finished?+, this is
+      # false for a failed or expired job.
+      #
+      # @return [Boolean]
+
+      def done?
+        status == TranslationMemoryJobResult::STATUS_COMPLETED
+      end
+
+      ##
+      # Checks if the job has not failed: its status is not +failed+ or +expired+. Also true
+      # while the job is still running.
+      #
+      # @return [Boolean]
+
+      def ok?
+        !error?
+      end
+
       def error_message
         result&.error_message
       end
@@ -124,8 +144,8 @@ module DeepL
         @job_id = job['job_id']
         @product = job['product']
         @operation = job['operation']
-        @creation_time = Utils::TimeParser.parse_optional_time(job['creation_time'])
-        @updated_time = Utils::TimeParser.parse_optional_time(job['updated_time'])
+        @creation_time = Utils::TimeParser.parse_optional_utc_time(job['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_utc_time(job['updated_time'])
       end
 
       def extract_parameters(job)

data/lib/deepl/resources/translation_memory_segments.rb

@@ -13,9 +13,11 @@ module DeepL
         @target_segment_id = target_segment['target_segment_id']
         @target_language = target_segment['target_language']
         @target_text = target_segment['target_text']
-        @creation_time = Utils::TimeParser.parse_optional_time(target_segment['creation_time'])
-        @updated_time = Utils::TimeParser.parse_optional_time(target_segment['updated_time'])
-        @last_used_time = Utils::TimeParser.parse_optional_time(target_segment['last_used_time'])
+        @creation_time = Utils::TimeParser.parse_optional_utc_time(target_segment['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_utc_time(target_segment['updated_time'])
+        @last_used_time = Utils::TimeParser.parse_optional_utc_time(
+          target_segment['last_used_time']
+        )
       end
 
       def to_s
@@ -33,9 +35,9 @@ module DeepL
         @targets = (segment['targets'] || []).map do |target|
           TranslationMemoryTargetSegment.new(target)
         end
-        @creation_time = Utils::TimeParser.parse_optional_time(segment['creation_time'])
-        @updated_time = Utils::TimeParser.parse_optional_time(segment['updated_time'])
-        @last_used_time = Utils::TimeParser.parse_optional_time(segment['last_used_time'])
+        @creation_time = Utils::TimeParser.parse_optional_utc_time(segment['creation_time'])
+        @updated_time = Utils::TimeParser.parse_optional_utc_time(segment['updated_time'])
+        @last_used_time = Utils::TimeParser.parse_optional_utc_time(segment['last_used_time'])
       end
 
       def to_s

data/lib/deepl/resources/usage.rb

@@ -6,21 +6,110 @@
 module DeepL
   module Resources
     class Usage < Base
-      attr_reader :character_count, :character_limit
+      ##
+      # The amount used and the maximum amount allowed for one usage type.
+      class Detail
+        attr_reader :count, :limit
 
-      def initialize(character_count, character_limit, *args)
+        def initialize(count, limit)
+          @count = count
+          @limit = limit
+        end
+
+        def limit_reached?
+          count >= limit
+        end
+
+        def to_s
+          "#{count} of #{limit}"
+        end
+      end
+
+      DETAIL_TYPES = %i[document team_document api_key_character speech_to_text_minutes
+                        speech_to_speech_minutes].freeze
+      KEYWORD_FIELDS = (DETAIL_TYPES + %i[products start_time end_time]).freeze
+
+      attr_reader :character, *KEYWORD_FIELDS
+
+      ##
+      # Each keyword argument is nil when the response does not contain the field.
+      #
+      # @param [Detail, nil] document Document usage, for accounts with a document limit.
+      # @param [Detail, nil] team_document Document usage of the whole team.
+      # @param [Detail, nil] api_key_character Character usage of this API key (API Pro).
+      # @param [Detail, nil] speech_to_text_minutes Speech-to-text usage in minutes (API Pro).
+      # @param [Detail, nil] speech_to_speech_minutes Speech-to-speech usage in minutes (API Pro).
+      # @param [Array<UsageProduct>, nil] products Per-product usage (API Pro).
+      # @param [Time, nil] start_time Start of the current billing period (API Pro).
+      # @param [Time, nil] end_time End of the current billing period (API Pro).
+
+      def initialize(character_count, character_limit, *args, **fields)
         super(*args)
 
+        unknown = fields.keys - KEYWORD_FIELDS
+        raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
         @character_count = character_count
         @character_limit = character_limit
+        @character = Detail.new(character_count, character_limit) unless
+          character_count.nil? || character_limit.nil?
+        KEYWORD_FIELDS.each { |field| instance_variable_set("@#{field}", fields[field]) }
+      end
+
+      ##
+      # @deprecated Use +character.count+ instead.
+      def character_count
+        deprecated(:character_count, 'character.count')
+        @character_count
+      end
+
+      ##
+      # @deprecated Use +character.limit+ instead.
+      def character_limit
+        deprecated(:character_limit, 'character.limit')
+        @character_limit
       end
 
       def to_s
-        "#{character_count} / #{character_limit}"
+        "#{@character_count} / #{@character_limit}"
       end
 
+      ##
+      # @deprecated Use +character.limit_reached?+ or +any_limit_reached?+ instead.
       def quota_exceeded?
-        character_count >= character_limit
+        deprecated(:quota_exceeded?, 'character.limit_reached? or any_limit_reached?')
+        @character_count >= @character_limit
+      end
+
+      ##
+      # True if the character, document or team document limit has been reached. The API Pro
+      # usage types (api_key_character and the speech minutes) are not considered; call
+      # limit_reached? on them directly.
+      def any_limit_reached?
+        [character, document, team_document].compact.any?(&:limit_reached?)
+      end
+
+      private
+
+      def deprecated(name, replacement)
+        Deprecation.warn_once("DeepL::Resources::Usage##{name}",
+                              "[DEPRECATION] DeepL::Resources::Usage##{name} is deprecated, " \
+                              "use #{replacement} instead.", uplevel: 3)
+      end
+    end
+
+    class UsageProduct
+      attr_reader :product_type, :billing_unit, :api_key_unit_count, :account_unit_count
+
+      def initialize(product)
+        @product_type = product['product_type']
+        @billing_unit = product['billing_unit']
+        @api_key_unit_count = product['api_key_unit_count']
+        @account_unit_count = product['account_unit_count']
+      end
+
+      def to_s
+        "#{product_type}: #{api_key_unit_count} / #{account_unit_count} #{billing_unit}"
       end
     end
   end

data/lib/deepl/style_rule_api.rb

@@ -4,47 +4,57 @@
 # frozen_string_literal: true
 
 module DeepL
+  # @deprecated Use the style rule methods of DeepL::Client instead.
   class StyleRuleApi
     def initialize(api, options = {})
       @api = api
       @options = options
     end
 
+    # @deprecated Use DeepL::Client#get_all_style_rules instead.
     def list(options = {})
       DeepL::Requests::StyleRule::List.new(@api, options).request
     end
 
+    # @deprecated Use DeepL::Client#create_style_rule instead.
     def create(name, language, options = {})
       DeepL::Requests::StyleRule::Create.new(@api, name, language, options).request
     end
 
+    # @deprecated Use DeepL::Client#get_style_rule instead.
     def find(style_id, options = {})
       DeepL::Requests::StyleRule::Find.new(@api, style_id, options).request
     end
 
+    # @deprecated Use DeepL::Client#update_style_rule_name instead.
     def update_name(style_id, name, options = {})
       DeepL::Requests::StyleRule::Update.new(@api, style_id, name, options).request
     end
 
+    # @deprecated Use DeepL::Client#delete_style_rule instead.
     def destroy(style_id, options = {})
       DeepL::Requests::StyleRule::Destroy.new(@api, style_id, options).request
     end
 
+    # @deprecated Use DeepL::Client#update_style_rule_configured_rules instead.
     def update_configured_rules(style_id, configured_rules, options = {})
       DeepL::Requests::StyleRule::UpdateConfiguredRules.new(@api, style_id, configured_rules,
                                                             options).request
     end
 
+    # @deprecated Use DeepL::Client#create_style_rule_custom_instruction instead.
     def create_custom_instruction(style_id, label, prompt, source_language = nil, options = {})
       DeepL::Requests::StyleRule::CreateCustomInstruction.new(@api, style_id, label, prompt,
                                                               source_language, options).request
     end
 
+    # @deprecated Use DeepL::Client#get_style_rule_custom_instruction instead.
     def find_custom_instruction(style_id, instruction_id, options = {})
       DeepL::Requests::StyleRule::FindCustomInstruction.new(@api, style_id, instruction_id,
                                                             options).request
     end
 
+    # @deprecated Use DeepL::Client#update_style_rule_custom_instruction instead.
     def update_custom_instruction(style_id, instruction_id, label,
                                   prompt, source_language = nil,
                                   options = {})
@@ -53,6 +63,7 @@ module DeepL
                                                               options).request
     end
 
+    # @deprecated Use DeepL::Client#delete_style_rule_custom_instruction instead.
     def destroy_custom_instruction(style_id, instruction_id, options = {})
       DeepL::Requests::StyleRule::DestroyCustomInstruction.new(@api, style_id, instruction_id,
                                                                options).request