better_translate 0.5.0 → 1.0.0

data/lib/better_translate/providers/base_http_provider.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module BetterTranslate
+  # Translation provider implementations
+  #
+  # Contains all AI provider integrations (ChatGPT, Gemini, Anthropic)
+  # and the base HTTP provider class.
+  module Providers
+    # Base class for HTTP-based translation providers
+    #
+    # Implements common functionality:
+    # - Faraday HTTP client with retry logic
+    # - Exponential backoff with jitter
+    # - Rate limiting
+    # - Caching
+    # - Error handling
+    #
+    # @abstract Subclasses must implement {#translate_text} and {#translate_batch}
+    #
+    # @example Creating a custom provider
+    #   class MyProvider < BaseHttpProvider
+    #     def translate_text(text, target_lang_code, target_lang_name)
+    #       # Implementation
+    #     end
+    #
+    #     def translate_batch(texts, target_lang_code, target_lang_name)
+    #       # Implementation
+    #     end
+    #   end
+    #
+    class BaseHttpProvider
+      # @return [Configuration] The configuration object
+      attr_reader :config
+
+      # @return [Cache] The cache instance
+      attr_reader :cache
+
+      # @return [RateLimiter] The rate limiter instance
+      attr_reader :rate_limiter
+
+      # Initialize the provider
+      #
+      # @param config [Configuration] Configuration object
+      #
+      # @example
+      #   config = Configuration.new
+      #   provider = BaseHttpProvider.new(config)
+      #
+      def initialize(config)
+        @config = config
+        @cache = Cache.new(capacity: config.cache_size, ttl: config.cache_ttl)
+        @rate_limiter = RateLimiter.new(delay: 0.5)
+      end
+
+      # Translate a single text string
+      #
+      # @param text [String] Text to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [String] Translated text
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      #
+      # @example
+      #   provider.translate_text("Hello", "it", "Italian")
+      #   #=> "Ciao"
+      #
+      def translate_text(text, target_lang_code, target_lang_name)
+        raise NotImplementedError, "#{self.class} must implement #translate_text"
+      end
+
+      # Translate multiple texts in a batch
+      #
+      # @param texts [Array<String>] Texts to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [Array<String>] Translated texts
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      #
+      # @example
+      #   provider.translate_batch(["Hello", "World"], "it", "Italian")
+      #   #=> ["Ciao", "Mondo"]
+      #
+      def translate_batch(texts, target_lang_code, target_lang_name)
+        raise NotImplementedError, "#{self.class} must implement #translate_batch"
+      end
+
+      protected
+
+      # Make an HTTP request with retry logic
+      #
+      # Implements exponential backoff with jitter and rate limiting.
+      # Automatically retries on rate limit and API errors.
+      #
+      # @param method [Symbol] HTTP method (:get, :post, etc.)
+      # @param url [String] Request URL
+      # @param body [Hash, nil] Request body
+      # @param headers [Hash] Request headers
+      # @return [Faraday::Response] HTTP response
+      # @raise [ApiError] if request fails after retries
+      # @api private
+      #
+      def make_request(method, url, body: nil, headers: {})
+        attempt = 0
+
+        loop do
+          attempt += 1
+
+          begin
+            rate_limiter.wait
+            response = http_client.send(method, url) do |req|
+              req.headers.merge!(headers)
+              req.body = body.to_json if body
+            end
+            rate_limiter.record_request
+
+            handle_response(response)
+            return response
+          rescue RateLimitError, ApiError => e
+            raise if attempt >= config.max_retries
+
+            delay = calculate_backoff(attempt)
+            log_retry(attempt, delay, e)
+            sleep(delay)
+          end
+        end
+      end
+
+      # Handle HTTP response
+      #
+      # @param response [Faraday::Response] HTTP response
+      # @raise [RateLimitError] if rate limited (429)
+      # @raise [ApiError] if response indicates error
+      # @return [void]
+      # @api private
+      #
+      def handle_response(response)
+        case response.status
+        when 200..299
+          # Success
+        when 429
+          raise RateLimitError.new(
+            "Rate limit exceeded",
+            context: { status: response.status, body: response.body }
+          )
+        when 400..499
+          raise ApiError.new(
+            "Client error: #{response.status}",
+            context: { status: response.status, body: response.body }
+          )
+        when 500..599
+          raise ApiError.new(
+            "Server error: #{response.status}",
+            context: { status: response.status, body: response.body }
+          )
+        else
+          raise ApiError.new(
+            "Unexpected status: #{response.status}",
+            context: { status: response.status, body: response.body }
+          )
+        end
+      end
+
+      # Calculate exponential backoff with jitter
+      #
+      # @param attempt [Integer] Current attempt number
+      # @return [Float] Delay in seconds
+      # @api private
+      #
+      def calculate_backoff(attempt)
+        base_delay = config.retry_delay
+        max_delay = 60.0
+        jitter = rand * 0.3 # 0-30% jitter
+
+        delay = base_delay * (2**(attempt - 1)) * (1 + jitter)
+        [delay, max_delay].min
+      end
+
+      # Log retry attempt
+      #
+      # @param attempt [Integer] Current attempt number
+      # @param delay [Float] Delay before retry
+      # @param error [StandardError] The error that triggered retry
+      # @return [void]
+      # @api private
+      #
+      def log_retry(attempt, delay, error)
+        return unless config.verbose
+
+        puts "[BetterTranslate] Retry #{attempt}/#{config.max_retries} " \
+             "after #{delay.round(2)}s (#{error.class}: #{error.message})"
+      end
+
+      # Get or create HTTP client
+      #
+      # @return [Faraday::Connection] HTTP client
+      # @api private
+      #
+      def http_client
+        @http_client ||= Faraday.new do |f|
+          f.options.timeout = config.request_timeout
+          f.options.open_timeout = 10
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Get from cache or execute block
+      #
+      # @param cache_key [String] Cache key
+      # @yieldreturn [String] Value to cache if not found
+      # @return [String] Cached or newly computed value
+      # @api private
+      #
+      def with_cache(cache_key)
+        return yield unless config.cache_enabled
+
+        cached = cache.get(cache_key)
+        return cached if cached
+
+        result = yield
+        cache.set(cache_key, result)
+        result
+      end
+
+      # Build cache key
+      #
+      # @param text [String] Text being translated
+      # @param target_lang_code [String] Target language code
+      # @return [String] Cache key
+      # @api private
+      #
+      def build_cache_key(text, target_lang_code)
+        "#{text}:#{target_lang_code}"
+      end
+    end
+  end
+end

data/lib/better_translate/providers/chatgpt_provider.rb

@@ -1,55 +1,149 @@
+# frozen_string_literal: true
+
 module BetterTranslate
   module Providers
-    # Translation provider that uses OpenAI's ChatGPT API to perform translations.
-    # Implements the BaseProvider interface with ChatGPT-specific translation logic.
-    # Uses the gpt-3.5-turbo model with a specialized prompt for accurate translations.
+    # OpenAI ChatGPT translation provider
+    #
+    # Uses GPT-5-nano model with temperature=1.0 for natural translations.
+    #
+    # @example Basic usage
+    #   config = Configuration.new
+    #   config.openai_key = ENV['OPENAI_API_KEY']
+    #   provider = ChatGPTProvider.new(config)
+    #   result = provider.translate_text("Hello", "it", "Italian")
+    #   #=> "Ciao"
     #
-    # @example
-    #   provider = BetterTranslate::Providers::ChatgptProvider.new(ENV['OPENAI_API_KEY'])
-    #   translated_text = provider.translate("Hello world", "fr", "French")
-    class ChatgptProvider < BaseProvider
-      # Translates text using the OpenAI ChatGPT API.
-      # Implements the provider-specific translation logic using OpenAI's ChatGPT API.
-      # Sends a carefully crafted prompt to the API to ensure high-quality translations
-      # without explanations or additional text.
-      #
-      # @param text [String] The text to translate
-      # @param target_lang_code [String] The target language code (e.g., "fr")
-      # @param target_lang_name [String] The target language name (e.g., "French")
-      # @return [String] The translated text
-      # @raise [StandardError] If the API request fails or returns an error
+    class ChatGPTProvider < BaseHttpProvider
+      # OpenAI API endpoint
+      API_URL = "https://api.openai.com/v1/chat/completions"
+
+      # Model to use for translations
+      MODEL = "gpt-5-nano"
+
+      # Temperature setting for creativity
+      TEMPERATURE = 1.0
+
+      # Translate a single text
+      #
+      # @param text [String] Text to translate
+      # @param target_lang_code [String] Target language code (e.g., "it")
+      # @param target_lang_name [String] Target language name (e.g., "Italian")
+      # @return [String] Translated text
+      # @raise [ValidationError] if input is invalid
+      # @raise [TranslationError] if translation fails
+      #
+      # @example
+      #   provider.translate_text("Hello world", "it", "Italian")
+      #   #=> "Ciao mondo"
+      #
       def translate_text(text, target_lang_code, target_lang_name)
-        uri = URI("https://api.openai.com/v1/chat/completions")
-        headers = {
-          "Content-Type"  => "application/json",
-          "Authorization" => "Bearer #{@api_key}"
-        }
+        Validator.validate_text!(text)
+        Validator.validate_language_code!(target_lang_code)
+
+        cache_key = build_cache_key(text, target_lang_code)
 
-        # Build the prompt to translate the text.
+        with_cache(cache_key) do
+          messages = build_messages(text, target_lang_name)
+          response = make_chat_completion_request(messages)
+          extract_translation(response)
+        end
+      rescue ApiError => e
+        raise TranslationError.new(
+          "Failed to translate text with ChatGPT: #{e.message}",
+          context: { text: text, target_lang: target_lang_code, original_error: e }
+        )
+      end
+
+      # Translate multiple texts in a batch
+      #
+      # @param texts [Array<String>] Texts to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [Array<String>] Translated texts
+      #
+      # @example
+      #   provider.translate_batch(["Hello", "World"], "it", "Italian")
+      #   #=> ["Ciao", "Mondo"]
+      #
+      def translate_batch(texts, target_lang_code, target_lang_name)
+        texts.map { |text| translate_text(text, target_lang_code, target_lang_name) }
+      end
+
+      private
+
+      # Build messages array for ChatGPT API
+      #
+      # @param text [String] Text to translate
+      # @param target_lang_name [String] Target language name
+      # @return [Array<Hash>] Messages array
+      # @api private
+      #
+      def build_messages(text, target_lang_name)
+        system_message = build_system_message(target_lang_name)
+
+        [
+          { role: "system", content: system_message },
+          { role: "user", content: text }
+        ]
+      end
+
+      # Build system message with optional context
+      #
+      # @param target_lang_name [String] Target language name
+      # @return [String] System message
+      # @api private
+      #
+      def build_system_message(target_lang_name)
+        base_message = "You are a professional translator. Translate the following text to #{target_lang_name}. " \
+                       "Return ONLY the translated text, without any explanations or additional text."
+
+        if config.translation_context && !config.translation_context.empty?
+          base_message += "\n\nContext: #{config.translation_context}"
+        end
+
+        base_message
+      end
+
+      # Make chat completion request to OpenAI API
+      #
+      # @param messages [Array<Hash>] Messages array
+      # @return [Faraday::Response] HTTP response
+      # @api private
+      #
+      def make_chat_completion_request(messages)
         body = {
-          model: "gpt-3.5-turbo",
-          messages: [
-            { role: "system", content: "You are a professional translator. Translate the following text exactly from #{BetterTranslate.configuration.source_language} to #{target_lang_name}. Provide ONLY the direct translation without any explanations, alternatives, or additional text. Do not include the original text. Do not use markdown formatting. Do not add any prefixes or notes. Just return the plain translated text." },
-            { role: "user", content: "#{text}" }
-          ],
-          temperature: 0.3
+          model: MODEL,
+          messages: messages,
+          temperature: TEMPERATURE
         }
 
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = true
-        request = Net::HTTP::Post.new(uri.path, headers)
-        request.body = body.to_json
-
-        response = http.request(request)
-        if response.is_a?(Net::HTTPSuccess)
-          json = JSON.parse(response.body)
-          translated_text = json.dig("choices", 0, "message", "content")
-          translated_text ? translated_text.strip : text
-        else
-          raise "Errore HTTP #{response.code}: #{response.body}"
-        end
-      rescue StandardError => e
-        raise "Errore durante la traduzione con ChatGPT: #{e.message}"
+        headers = {
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{config.openai_key}"
+        }
+
+        make_request(:post, API_URL, body: body, headers: headers)
+      end
+
+      # Extract translation from API response
+      #
+      # @param response [Faraday::Response] HTTP response
+      # @return [String] Translated text
+      # @raise [TranslationError] if parsing fails or no translation found
+      # @api private
+      #
+      def extract_translation(response)
+        parsed = JSON.parse(response.body)
+        translation = parsed.dig("choices", 0, "message", "content")
+
+        raise TranslationError, "No translation in response" if translation.nil? || translation.empty?
+
+        translation.strip
+      rescue JSON::ParserError => e
+        raise TranslationError.new(
+          "Failed to parse ChatGPT response",
+          context: { error: e.message, body: response.body }
+        )
       end
     end
   end

data/lib/better_translate/providers/gemini_provider.rb

@@ -1,75 +1,137 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "json"
-require "uri"
-
 module BetterTranslate
   module Providers
-    # Translation provider that uses Google's Gemini API to perform translations.
-    # Implements the BaseProvider interface with Gemini-specific translation logic.
-    # Uses the gemini-2.0-flash model with a specialized prompt for accurate translations.
+    # Google Gemini translation provider
+    #
+    # Uses gemini-2.0-flash-exp model for fast, high-quality translations.
+    #
+    # @example Basic usage
+    #   config = Configuration.new
+    #   config.google_gemini_key = ENV['GOOGLE_GEMINI_KEY']
+    #   provider = GeminiProvider.new(config)
+    #   result = provider.translate_text("Hello", "it", "Italian")
+    #   #=> "Ciao"
     #
-    # @example
-    #   provider = BetterTranslate::Providers::GeminiProvider.new(ENV['GOOGLE_GEMINI_KEY'])
-    #   translated_text = provider.translate("Hello world", "fr", "French")
-    class GeminiProvider < BaseProvider
-      # The base URL for the Gemini API
-      # @return [String] The API endpoint URL
-      GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent"
-
-      # Implements the provider-specific translation logic using Google's Gemini API.
-      # Sends a carefully crafted prompt to the API to ensure high-quality translations
-      # without explanations or additional text. Includes minimal text cleaning to handle
-      # any formatting issues in the response.
+    class GeminiProvider < BaseHttpProvider
+      # Google Gemini API endpoint
+      API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent"
+
+      # Model to use for translations
+      MODEL = "gemini-2.0-flash-exp"
+
+      # Translate a single text
+      #
+      # @param text [String] Text to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [String] Translated text
+      # @raise [ValidationError] if input is invalid
+      # @raise [TranslationError] if translation fails
+      #
+      # @example
+      #   provider.translate_text("Hello world", "it", "Italian")
+      #   #=> "Ciao mondo"
       #
-      # @param text [String] The text to translate
-      # @param target_lang_code [String] The target language code (e.g., "fr")
-      # @param target_lang_name [String] The target language name (e.g., "French")
-      # @return [String] The translated text
-      # @raise [StandardError] If the API request fails or returns an error
       def translate_text(text, target_lang_code, target_lang_name)
-        url = "#{GEMINI_API_URL}?key=#{@api_key}"
-        uri = URI(url)
+        Validator.validate_text!(text)
+        Validator.validate_language_code!(target_lang_code)
+
+        cache_key = build_cache_key(text, target_lang_code)
+
+        with_cache(cache_key) do
+          prompt = build_prompt(text, target_lang_name)
+          response = make_generation_request(prompt)
+          extract_translation(response)
+        end
+      rescue ApiError => e
+        raise TranslationError.new(
+          "Failed to translate text with Gemini: #{e.message}",
+          context: { text: text, target_lang: target_lang_code, original_error: e }
+        )
+      end
+
+      # Translate multiple texts in a batch
+      #
+      # @param texts [Array<String>] Texts to translate
+      # @param target_lang_code [String] Target language code
+      # @param target_lang_name [String] Target language name
+      # @return [Array<String>] Translated texts
+      #
+      # @example
+      #   provider.translate_batch(["Hello", "World"], "it", "Italian")
+      #   #=> ["Ciao", "Mondo"]
+      #
+      def translate_batch(texts, target_lang_code, target_lang_name)
+        texts.map { |text| translate_text(text, target_lang_code, target_lang_name) }
+      end
+
+      private
+
+      # Build prompt for Gemini API
+      #
+      # @param text [String] Text to translate
+      # @param target_lang_name [String] Target language name
+      # @return [String] Prompt
+      # @api private
+      #
+      def build_prompt(text, target_lang_name)
+        base_prompt = "Translate the following text to #{target_lang_name}. " \
+                      "Return ONLY the translated text, without any explanations.\n\n" \
+                      "Text: #{text}"
+
+        if config.translation_context && !config.translation_context.empty?
+          base_prompt = "Context: #{config.translation_context}\n\n#{base_prompt}"
+        end
+
+        base_prompt
+      end
+
+      # Make generation request to Gemini API
+      #
+      # @param prompt [String] Prompt text
+      # @return [Faraday::Response] HTTP response
+      # @api private
+      #
+      def make_generation_request(prompt)
+        url = "#{API_URL}?key=#{config.google_gemini_key}"
 
-        headers = { "Content-Type" => "application/json" }
         body = {
-          contents: [{
-            parts: [{
-              text: "Translate the following text to #{target_lang_name}. Provide ONLY the direct translation without any explanations, alternatives, or additional text. Do not include the original text. Do not use markdown formatting. Do not add any prefixes or notes. Just return the plain translated text:\n\n#{text}"
-            }]
-          }]
+          contents: [
+            {
+              parts: [
+                { text: prompt }
+              ]
+            }
+          ]
         }
 
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = true
-        request = Net::HTTP::Post.new(uri.path + "?" + uri.query, headers)
-        request.body = body.to_json
-
-        begin
-          response = http.request(request)
-          
-          if response.is_a?(Net::HTTPSuccess)
-            json = JSON.parse(response.body)
-            
-            if json["candidates"]&.any? && json["candidates"][0]["content"]["parts"]&.any?
-              translated_text = json["candidates"][0]["content"]["parts"][0]["text"]
-              
-              # Pulizia minima del testo, dato che il prompt è già specifico
-              cleaned_text = translated_text.strip
-                .gsub(/[\*\`\n"]/, '') # Rimuovi markdown, newline e virgolette
-                .gsub(/\s+/, ' ') # Riduci spazi multipli a uno singolo
-              
-              cleaned_text.empty? ? text : cleaned_text
-            else
-              raise "Risposta Gemini non valida: #{json}"
-            end
-          else
-            raise "Errore HTTP #{response.code}: #{response.body}"
-          end
-        rescue => e
-          raise "Errore durante la traduzione con Gemini: #{e.message}"
-        end
+        headers = {
+          "Content-Type" => "application/json"
+        }
+
+        make_request(:post, url, body: body, headers: headers)
+      end
+
+      # Extract translation from API response
+      #
+      # @param response [Faraday::Response] HTTP response
+      # @return [String] Translated text
+      # @raise [TranslationError] if parsing fails or no translation found
+      # @api private
+      #
+      def extract_translation(response)
+        parsed = JSON.parse(response.body)
+        translation = parsed.dig("candidates", 0, "content", "parts", 0, "text")
+
+        raise TranslationError, "No translation in response" if translation.nil? || translation.empty?
+
+        translation.strip
+      rescue JSON::ParserError => e
+        raise TranslationError.new(
+          "Failed to parse Gemini response",
+          context: { error: e.message, body: response.body }
+        )
       end
     end
   end

data/lib/better_translate/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Rails integration
+  #
+  # Automatically loads Rake tasks when used in a Rails application.
+  #
+  # @example In a Rails app, tasks are available automatically:
+  #   rake better_translate:translate
+  #   rake better_translate:config:generate
+  #
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      rake_file = File.expand_path("../tasks/better_translate.rake", __dir__)
+      load rake_file if rake_file
+    end
+  end
+end