better_translate 0.5.0 → 1.0.0

data/lib/better_translate/rate_limiter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Thread-safe rate limiter
+  #
+  # Ensures requests are spaced out by a minimum delay.
+  #
+  # @example Basic usage
+  #   limiter = RateLimiter.new(delay: 0.5)
+  #   limiter.wait  # Waits if needed
+  #   # Make API request
+  #   limiter.record_request
+  #
+  # @example In a loop
+  #   limiter = RateLimiter.new(delay: 1.0)
+  #   translations.each do |text|
+  #     limiter.wait
+  #     result = translate_api_call(text)
+  #     limiter.record_request
+  #   end
+  #
+  class RateLimiter
+    # @return [Float] Delay between requests in seconds
+    attr_reader :delay
+
+    # Initialize a new rate limiter
+    #
+    # @param delay [Float] Delay in seconds between requests
+    #
+    # @example Create rate limiter with 1 second delay
+    #   limiter = RateLimiter.new(delay: 1.0)
+    #
+    def initialize(delay: 0.5)
+      @delay = delay
+      @last_request_time = nil
+      @mutex = Mutex.new
+    end
+
+    # Wait if necessary to respect rate limit
+    #
+    # Calculates time elapsed since last request and sleeps
+    # for the remaining time if needed.
+    #
+    # @return [void]
+    #
+    # @example Wait before making request
+    #   limiter.wait
+    #   response = api_client.post(data)
+    #   limiter.record_request
+    #
+    def wait
+      @mutex.synchronize do
+        return if @last_request_time.nil?
+
+        elapsed = Time.now - @last_request_time
+        sleep_time = @delay - elapsed.to_f
+
+        sleep(sleep_time) if sleep_time.positive?
+      end
+    end
+
+    # Record that a request was made
+    #
+    # Should be called immediately after making a request.
+    #
+    # @return [void]
+    #
+    # @example Record request timestamp
+    #   response = api_client.post(data)
+    #   limiter.record_request
+    #
+    def record_request
+      @mutex.synchronize { @last_request_time = Time.now }
+    end
+
+    # Reset the rate limiter
+    #
+    # Clears the last request time. Useful for testing or
+    # when switching contexts.
+    #
+    # @return [void]
+    #
+    # @example Reset limiter
+    #   limiter.reset
+    #
+    def reset
+      @mutex.synchronize { @last_request_time = nil }
+    end
+  end
+end

data/lib/better_translate/strategies/base_strategy.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Translation strategy implementations
+  module Strategies
+    # Base class for translation strategies
+    #
+    # @abstract Subclasses must implement {#translate}
+    #
+    # @example Creating a custom strategy
+    #   class MyStrategy < BaseStrategy
+    #     def translate(strings, target_lang_code, target_lang_name)
+    #       # Custom translation logic
+    #     end
+    #   end
+    #
+    class BaseStrategy
+      # @return [Configuration] Configuration object
+      attr_reader :config
+
+      # @return [Providers::BaseHttpProvider] Translation provider
+      attr_reader :provider
+
+      # @return [ProgressTracker] Progress tracker
+      attr_reader :progress_tracker
+
+      # Initialize the strategy
+      #
+      # @param config [Configuration] Configuration object
+      # @param provider [Providers::BaseHttpProvider] Translation provider
+      # @param progress_tracker [ProgressTracker] Progress tracker
+      #
+      # @example
+      #   strategy = BaseStrategy.new(config, provider, tracker)
+      #
+      def initialize(config, provider, progress_tracker)
+        @config = config
+        @provider = provider
+        @progress_tracker = progress_tracker
+      end
+
+      # Translate strings
+      #
+      # @param strings [Hash] Flattened hash of strings to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [Hash] Translated strings (flattened)
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      #
+      # @example
+      #   translated = strategy.translate(strings, "it", "Italian")
+      #
+      def translate(strings, target_lang_code, target_lang_name)
+        raise NotImplementedError, "#{self.class} must implement #translate"
+      end
+    end
+  end
+end

data/lib/better_translate/strategies/batch_strategy.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Strategies
+    # Batch translation strategy
+    #
+    # Translates strings in batches for improved performance.
+    # Used for larger files (>= 50 strings).
+    #
+    # @example
+    #   strategy = BatchStrategy.new(config, provider, tracker)
+    #   translated = strategy.translate(strings, "it", "Italian")
+    #
+    class BatchStrategy < BaseStrategy
+      # Batch size for translation
+      BATCH_SIZE = 10
+
+      # Translate strings in batches
+      #
+      # @param strings [Hash] Flattened hash of strings to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [Hash] Translated strings (flattened)
+      #
+      # @example
+      #   strings = { "key1" => "value1", "key2" => "value2", ... }
+      #   translated = strategy.translate(strings, "it", "Italian")
+      #
+      def translate(strings, target_lang_code, target_lang_name)
+        # @type var translated: Hash[String, String]
+        translated = {}
+        keys = strings.keys
+        values = strings.values
+        total_batches = (values.size.to_f / BATCH_SIZE).ceil
+
+        values.each_slice(BATCH_SIZE).with_index do |batch, batch_index|
+          progress_tracker.update(
+            language: target_lang_name,
+            current_key: "Batch #{batch_index + 1}/#{total_batches}",
+            progress: ((batch_index + 1).to_f / total_batches * 100.0).round(1)
+          )
+
+          translated_batch = provider.translate_batch(batch, target_lang_code, target_lang_name)
+
+          # Map back to keys
+          batch_keys = keys[batch_index * BATCH_SIZE, batch.size]
+          batch_keys&.each_with_index do |key, i|
+            translated[key] = translated_batch[i]
+          end
+        end
+
+        translated
+      end
+    end
+  end
+end

data/lib/better_translate/strategies/deep_strategy.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Strategies
+    # Deep translation strategy
+    #
+    # Translates each string individually with detailed progress tracking.
+    # Used for smaller files (< 50 strings) to provide more granular progress.
+    #
+    # @example
+    #   strategy = DeepStrategy.new(config, provider, tracker)
+    #   translated = strategy.translate(strings, "it", "Italian")
+    #
+    class DeepStrategy < BaseStrategy
+      # Translate strings individually
+      #
+      # @param strings [Hash] Flattened hash of strings to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [Hash] Translated strings (flattened)
+      #
+      # @example
+      #   translated = strategy.translate({ "greeting" => "Hello" }, "it", "Italian")
+      #   #=> { "greeting" => "Ciao" }
+      #
+      def translate(strings, target_lang_code, target_lang_name)
+        # @type var translated: Hash[String, String]
+        translated = {}
+        total = strings.size
+
+        strings.each_with_index do |(key, value), index|
+          progress_tracker.update(
+            language: target_lang_name,
+            current_key: key,
+            progress: ((index + 1).to_f / total * 100.0).round(1)
+          )
+
+          translated[key] = provider.translate_text(value, target_lang_code, target_lang_name)
+        end
+
+        translated
+      end
+    end
+  end
+end

data/lib/better_translate/strategies/strategy_selector.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Strategies
+    # Selects the appropriate translation strategy based on content size
+    #
+    # @example
+    #   strategy = StrategySelector.select(25, config, provider, tracker)
+    #   #=> #<DeepStrategy>
+    #
+    #   strategy = StrategySelector.select(100, config, provider, tracker)
+    #   #=> #<BatchStrategy>
+    #
+    class StrategySelector
+      # Threshold for switching from deep to batch strategy
+      DEEP_STRATEGY_THRESHOLD = 50
+
+      # Select the appropriate strategy
+      #
+      # @param strings_count [Integer] Number of strings to translate
+      # @param config [Configuration] Configuration object
+      # @param provider [Providers::BaseHttpProvider] Translation provider
+      # @param progress_tracker [ProgressTracker] Progress tracker
+      # @return [BaseStrategy] Selected strategy instance
+      #
+      # @example Small file (deep strategy)
+      #   strategy = StrategySelector.select(30, config, provider, tracker)
+      #   #=> #<DeepStrategy>
+      #
+      # @example Large file (batch strategy)
+      #   strategy = StrategySelector.select(200, config, provider, tracker)
+      #   #=> #<BatchStrategy>
+      #
+      def self.select(strings_count, config, provider, progress_tracker)
+        if strings_count < DEEP_STRATEGY_THRESHOLD
+          DeepStrategy.new(config, provider, progress_tracker)
+        else
+          BatchStrategy.new(config, provider, progress_tracker)
+        end
+      end
+    end
+  end
+end