better_translate 0.5.0 → 1.0.0

data/lib/better_translate/direct_translator.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Direct text translator for non-YAML workflows
+  #
+  # Provides convenience methods for translating individual strings or batches
+  # without requiring YAML files. Useful for runtime translation needs.
+  #
+  # @example Basic usage
+  #   config = Configuration.new
+  #   config.provider = :chatgpt
+  #   config.openai_key = ENV['OPENAI_API_KEY']
+  #   config.source_language = "en"
+  #
+  #   translator = DirectTranslator.new(config)
+  #   result = translator.translate("Hello", to: "it", language_name: "Italian")
+  #   #=> "Ciao"
+  #
+  # @example Batch translation
+  #   results = translator.translate_batch(
+  #     ["Hello", "Goodbye"],
+  #     to: "it",
+  #     language_name: "Italian"
+  #   )
+  #   #=> ["Ciao", "Arrivederci"]
+  #
+  class DirectTranslator
+    # @return [Configuration] Configuration object
+    attr_reader :config
+
+    # Initialize direct translator
+    #
+    # @param config [Configuration] Configuration object (must be valid)
+    # @raise [ConfigurationError] if configuration is invalid
+    #
+    # @example
+    #   translator = DirectTranslator.new(config)
+    #
+    def initialize(config)
+      @config = config
+      # Validate provider is configured (minimal validation for DirectTranslator)
+      raise ConfigurationError, "Provider must be configured" unless config.provider
+
+      @provider = ProviderFactory.create(config.provider, config)
+    end
+
+    # Translate a single text string
+    #
+    # @param text [String] Text to translate
+    # @param to [String, Symbol] Target language code (e.g., "it", :it)
+    # @param language_name [String] Full language name (e.g., "Italian")
+    #
+    # @return [String] Translated text
+    # @raise [ValidationError] if text or language_code is invalid
+    # @raise [TranslationError] if translation fails
+    #
+    # @example
+    #   translator.translate("Hello", to: "it", language_name: "Italian")
+    #   #=> "Ciao"
+    #
+    def translate(text, to:, language_name:)
+      Validator.validate_text!(text)
+      target_lang_code = to.to_s
+      Validator.validate_language_code!(target_lang_code)
+
+      @provider.translate_text(text, target_lang_code, language_name)
+    rescue ValidationError
+      raise # Re-raise validation errors without wrapping
+    rescue ApiError, StandardError => e
+      raise TranslationError.new(
+        "Failed to translate text: #{e.message}",
+        context: { text: text, target_lang: target_lang_code, original_error: e }
+      )
+    end
+
+    # Translate multiple text strings
+    #
+    # @param texts [Array<String>] Array of texts to translate
+    # @param to [String, Symbol] Target language code
+    # @param language_name [String] Full language name
+    # @param skip_errors [Boolean] Continue on error, returning nil for failed translations (default: false)
+    #
+    # @return [Array<String, nil>] Array of translated texts (nil for errors if skip_errors: true)
+    # @raise [ArgumentError] if texts is not an Array
+    # @raise [ValidationError] if any text is invalid
+    # @raise [TranslationError] if translation fails (unless skip_errors: true)
+    #
+    # @example
+    #   translator.translate_batch(
+    #     ["Hello", "Goodbye"],
+    #     to: "it",
+    #     language_name: "Italian"
+    #   )
+    #   #=> ["Ciao", "Arrivederci"]
+    #
+    # @example With error handling
+    #   translator.translate_batch(
+    #     ["Hello", "Goodbye"],
+    #     to: "it",
+    #     language_name: "Italian",
+    #     skip_errors: true
+    #   )
+    #   #=> ["Ciao", nil] # If second translation fails
+    #
+    def translate_batch(texts, to:, language_name:, skip_errors: false)
+      raise ArgumentError, "texts must be an Array" unless texts.is_a?(Array)
+
+      return [] if texts.empty?
+
+      # Validate all texts first
+      texts.each { |text| Validator.validate_text!(text) }
+
+      target_lang_code = to.to_s
+      Validator.validate_language_code!(target_lang_code)
+
+      # Translate each text
+      texts.map do |text|
+        @provider.translate_text(text, target_lang_code, language_name)
+      rescue ApiError, StandardError => e
+        unless skip_errors
+          raise TranslationError.new(
+            "Failed to translate text: #{e.message}",
+            context: { text: text, target_lang: target_lang_code, original_error: e }
+          )
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/better_translate/errors.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Base error class for all BetterTranslate errors
+  #
+  # @abstract
+  class Error < StandardError
+    # @return [Hash] Additional context about the error
+    attr_reader :context
+
+    # Initialize a new error with optional context
+    #
+    # @param message [String] The error message
+    # @param context [Hash] Additional context information
+    def initialize(message = nil, context: {})
+      @context = context
+      super(message)
+    end
+  end
+
+  # Raised when configuration is invalid or incomplete
+  #
+  # @example Raising with context
+  #   raise ConfigurationError.new(
+  #     "Invalid provider",
+  #     context: { provider: :invalid_name }
+  #   )
+  class ConfigurationError < Error; end
+
+  # Raised when input validation fails
+  #
+  # @example File validation failure
+  #   raise ValidationError.new(
+  #     "File does not exist",
+  #     context: { file_path: "/path/to/file.yml" }
+  #   )
+  class ValidationError < Error; end
+
+  # Raised when translation fails
+  #
+  # @example Translation error
+  #   raise TranslationError.new(
+  #     "Failed to translate text",
+  #     context: { text: "Hello", target_lang: "it" }
+  #   )
+  class TranslationError < Error; end
+
+  # Raised when a provider encounters an error
+  #
+  # @example Provider initialization error
+  #   raise ProviderError.new(
+  #     "Provider not initialized",
+  #     context: { provider: :chatgpt }
+  #   )
+  class ProviderError < Error; end
+
+  # Raised when an API call fails
+  #
+  # @example API call failure
+  #   raise ApiError.new(
+  #     "API request failed",
+  #     context: { status_code: 500, response: "Internal Server Error" }
+  #   )
+  class ApiError < Error; end
+
+  # Raised when rate limit is exceeded
+  #
+  # @example Rate limit error
+  #   raise RateLimitError.new(
+  #     "Rate limit exceeded",
+  #     context: { retry_after: 60 }
+  #   )
+  class RateLimitError < ApiError; end
+
+  # Raised when file operations fail
+  #
+  # @example File read error
+  #   raise FileError.new(
+  #     "Cannot read file",
+  #     context: { file_path: "config/locales/en.yml", error: "Permission denied" }
+  #   )
+  class FileError < Error; end
+
+  # Raised when YAML parsing fails
+  #
+  # @example YAML syntax error
+  #   raise YamlError.new(
+  #     "Invalid YAML syntax",
+  #     context: { file_path: "config/locales/en.yml", line: 5 }
+  #   )
+  class YamlError < Error; end
+
+  # Raised when a provider is not found
+  #
+  # @example Provider not found
+  #   raise ProviderNotFoundError.new(
+  #     "Provider 'unknown' not found",
+  #     context: { provider: :unknown, available: [:chatgpt, :gemini, :anthropic] }
+  #   )
+  class ProviderNotFoundError < Error; end
+end

data/lib/better_translate/progress_tracker.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Tracks and displays translation progress
+  #
+  # Shows real-time progress updates with colored console output.
+  #
+  # @example Basic usage
+  #   tracker = ProgressTracker.new(enabled: true)
+  #   tracker.update(language: "Italian", current_key: "greeting", progress: 50.0)
+  #   tracker.complete("Italian", 100)
+  #
+  class ProgressTracker
+    # @return [Boolean] Whether to show progress
+    attr_reader :enabled
+
+    # Initialize progress tracker
+    #
+    # @param enabled [Boolean] Whether to show progress (default: true)
+    #
+    # @example
+    #   tracker = ProgressTracker.new(enabled: true)
+    #
+    def initialize(enabled: true)
+      @enabled = enabled
+      @start_time = Time.now
+    end
+
+    # Update progress
+    #
+    # @param language [String] Current language being translated
+    # @param current_key [String] Current translation key
+    # @param progress [Float] Progress percentage (0-100)
+    # @return [void]
+    #
+    # @example
+    #   tracker.update(language: "Italian", current_key: "nav.home", progress: 75.5)
+    #
+    def update(language:, current_key:, progress:)
+      return unless enabled
+
+      elapsed = Time.now - @start_time
+      estimated_total = progress.positive? ? elapsed / (progress / 100.0) : 0
+      remaining = estimated_total - elapsed
+
+      message = format(
+        "\r[BetterTranslate] %s | %s | %.1f%% | Elapsed: %s | Remaining: ~%s",
+        colorize(language, :cyan),
+        truncate(current_key, 40),
+        progress,
+        format_time(elapsed),
+        format_time(remaining)
+      )
+
+      print message
+      $stdout.flush
+
+      puts "" if progress >= 100.0 # New line when complete
+    end
+
+    # Mark translation as complete for a language
+    #
+    # @param language [String] Language name
+    # @param total_strings [Integer] Total number of strings translated
+    # @return [void]
+    #
+    # @example
+    #   tracker.complete("Italian", 150)
+    #
+    def complete(language, total_strings)
+      return unless enabled
+
+      elapsed = Time.now - @start_time
+      puts colorize("✓ #{language}: #{total_strings} strings translated in #{format_time(elapsed)}", :green)
+    end
+
+    # Display an error
+    #
+    # @param language [String] Language name
+    # @param error [StandardError] The error that occurred
+    # @return [void]
+    #
+    # @example
+    #   tracker.error("Italian", StandardError.new("API error"))
+    #
+    def error(language, error)
+      return unless enabled
+
+      puts colorize("✗ #{language}: #{error.message}", :red)
+    end
+
+    # Reset the progress tracker
+    #
+    # @return [void]
+    #
+    # @example
+    #   tracker.reset
+    #
+    def reset
+      @start_time = Time.now
+    end
+
+    private
+
+    # Format time in human-readable format
+    #
+    # @param seconds [Float] Seconds
+    # @return [String] Formatted time
+    # @api private
+    #
+    def format_time(seconds)
+      return "0s" if seconds <= 0
+
+      minutes = (seconds / 60).to_i
+      secs = (seconds % 60).to_i
+
+      if minutes.positive?
+        "#{minutes}m #{secs}s"
+      else
+        "#{secs}s"
+      end
+    end
+
+    # Truncate text to max length
+    #
+    # @param text [String] Text to truncate
+    # @param max_length [Integer] Maximum length
+    # @return [String] Truncated text
+    # @api private
+    #
+    def truncate(text, max_length)
+      return text if text.length <= max_length
+
+      "#{text[0...(max_length - 3)]}..."
+    end
+
+    # Colorize text for terminal output
+    #
+    # @param text [String] Text to colorize
+    # @param color [Symbol] Color name (:red, :green, :cyan)
+    # @return [String] Colorized text
+    # @api private
+    #
+    def colorize(text, color)
+      return text unless $stdout.tty?
+
+      colors = {
+        red: "\e[31m",
+        green: "\e[32m",
+        cyan: "\e[36m",
+        reset: "\e[0m"
+      }
+
+      "#{colors[color]}#{text}#{colors[:reset]}"
+    end
+  end
+end

data/lib/better_translate/provider_factory.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Factory for creating translation providers
+  #
+  # Creates the appropriate provider instance based on configuration.
+  #
+  # @example Creating a ChatGPT provider
+  #   config = Configuration.new
+  #   config.provider = :chatgpt
+  #   config.openai_key = ENV['OPENAI_API_KEY']
+  #   provider = ProviderFactory.create(:chatgpt, config)
+  #   #=> #<BetterTranslate::Providers::ChatGPTProvider>
+  #
+  # @example Creating a Gemini provider
+  #   config.provider = :gemini
+  #   config.google_gemini_key = ENV['GOOGLE_GEMINI_KEY']
+  #   provider = ProviderFactory.create(:gemini, config)
+  #   #=> #<BetterTranslate::Providers::GeminiProvider>
+  #
+  class ProviderFactory
+    # Create a provider instance
+    #
+    # @param provider_name [Symbol] Provider name (:chatgpt, :gemini, :anthropic)
+    # @param config [Configuration] Configuration object
+    # @return [Providers::BaseHttpProvider] Provider instance
+    # @raise [ProviderNotFoundError] if provider is unknown
+    #
+    # @example
+    #   provider = ProviderFactory.create(:chatgpt, config)
+    #
+    def self.create(provider_name, config)
+      case provider_name
+      when :chatgpt
+        Providers::ChatGPTProvider.new(config)
+      when :gemini
+        Providers::GeminiProvider.new(config)
+      when :anthropic
+        Providers::AnthropicProvider.new(config)
+      else
+        raise ProviderNotFoundError, "Unknown provider: #{provider_name}. Supported: :chatgpt, :gemini, :anthropic"
+      end
+    end
+  end
+end

data/lib/better_translate/providers/anthropic_provider.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Providers
+    # Anthropic Claude translation provider
+    #
+    # Uses claude-3-5-sonnet-20241022 model for high-quality translations.
+    #
+    # @example Basic usage
+    #   config = Configuration.new
+    #   config.anthropic_key = ENV['ANTHROPIC_API_KEY']
+    #   provider = AnthropicProvider.new(config)
+    #   result = provider.translate_text("Hello", "it", "Italian")
+    #   #=> "Ciao"
+    #
+    class AnthropicProvider < BaseHttpProvider
+      # Anthropic API endpoint
+      API_URL = "https://api.anthropic.com/v1/messages"
+
+      # Model to use for translations
+      MODEL = "claude-3-5-sonnet-20241022"
+
+      # API version
+      API_VERSION = "2023-06-01"
+
+      # 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"
+      #
+      def translate_text(text, target_lang_code, target_lang_name)
+        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
+          messages = build_messages(text, target_lang_name)
+          response = make_messages_request(messages)
+          extract_translation(response)
+        end
+      rescue ApiError => e
+        raise TranslationError.new(
+          "Failed to translate text with Anthropic: #{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 for Anthropic API
+      #
+      # @param text [String] Text to translate
+      # @param target_lang_name [String] Target language name
+      # @return [Hash] Messages hash
+      # @api private
+      #
+      def build_messages(text, target_lang_name)
+        system_message = build_system_message(target_lang_name)
+
+        {
+          system: system_message,
+          messages: [
+            { 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 messages request to Anthropic API
+      #
+      # @param message_data [Hash] Message data with system and messages
+      # @return [Faraday::Response] HTTP response
+      # @api private
+      #
+      def make_messages_request(message_data)
+        body = {
+          model: MODEL,
+          max_tokens: 1024,
+          system: message_data[:system],
+          messages: message_data[:messages]
+        }
+
+        headers = {
+          "Content-Type" => "application/json",
+          "x-api-key" => config.anthropic_key || "",
+          "anthropic-version" => API_VERSION
+        }
+
+        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("content", 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 Anthropic response",
+          context: { error: e.message, body: response.body }
+        )
+      end
+    end
+  end
+end