better_translate 0.5.0 → 1.0.0

data/lib/better_translate/cache.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # LRU (Least Recently Used) Cache implementation
+  #
+  # Thread-safe cache with configurable capacity and optional TTL.
+  #
+  # @example Basic usage
+  #   cache = Cache.new(capacity: 100)
+  #   cache.set("hello:it", "ciao")
+  #   cache.get("hello:it") #=> "ciao"
+  #
+  # @example With TTL
+  #   cache = Cache.new(capacity: 100, ttl: 3600)
+  #   cache.set("key", "value")
+  #   # After 3600 seconds, get("key") will return nil
+  #
+  class Cache
+    # @return [Integer] Maximum number of items in cache
+    attr_reader :capacity
+
+    # @return [Integer, nil] Time to live in seconds
+    attr_reader :ttl
+
+    # Initialize a new cache
+    #
+    # @param capacity [Integer] Maximum cache size
+    # @param ttl [Integer, nil] Time to live in seconds (nil = no expiration)
+    #
+    # @example Create cache with capacity and TTL
+    #   cache = Cache.new(capacity: 500, ttl: 1800)
+    #
+    def initialize(capacity: 1000, ttl: nil)
+      @capacity = capacity
+      @ttl = ttl
+      @cache = {}
+      @mutex = Mutex.new
+    end
+
+    # Get a value from the cache
+    #
+    # @param key [String] Cache key
+    # @return [String, nil] Cached value or nil if not found/expired
+    #
+    # @example Get cached value
+    #   value = cache.get("translation:en:it:hello")
+    #
+    def get(key)
+      @mutex.synchronize do
+        return nil unless @cache.key?(key)
+
+        entry = @cache[key]
+
+        # Check TTL
+        if @ttl && entry && Time.now - entry[:timestamp] > @ttl
+          @cache.delete(key)
+          return nil
+        end
+
+        # Move to end (most recently used)
+        @cache.delete(key)
+        @cache[key] = entry
+        entry[:value]
+      end
+    end
+
+    # Set a value in the cache
+    #
+    # @param key [String] Cache key
+    # @param value [String] Value to cache
+    # @return [String] The cached value
+    #
+    # @example Store value in cache
+    #   cache.set("translation:en:it:hello", "ciao")
+    #
+    def set(key, value)
+      @mutex.synchronize do
+        # Remove oldest entry if at capacity
+        @cache.shift if @cache.size >= @capacity && !@cache.key?(key)
+
+        @cache[key] = {
+          value: value,
+          timestamp: Time.now
+        }
+        value
+      end
+    end
+
+    # Clear the cache
+    #
+    # @return [void]
+    #
+    # @example Clear all cached values
+    #   cache.clear
+    #
+    def clear
+      @mutex.synchronize { @cache.clear }
+    end
+
+    # Get cache size
+    #
+    # @return [Integer] Number of items in cache
+    #
+    # @example Check cache size
+    #   puts "Cache contains #{cache.size} items"
+    #
+    def size
+      @mutex.synchronize { @cache.size }
+    end
+
+    # Check if key exists in cache
+    #
+    # @param key [String] Cache key
+    # @return [Boolean] true if key exists and not expired
+    #
+    # @example Check if key exists
+    #   if cache.key?("translation:en:it:hello")
+    #     puts "Translation is cached"
+    #   end
+    #
+    def key?(key)
+      !get(key).nil?
+    end
+  end
+end

data/lib/better_translate/cli.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "yaml"
+
+module BetterTranslate
+  # Command-line interface for BetterTranslate
+  #
+  # Provides standalone CLI commands for translation without Rails.
+  #
+  # @example Run translation from config file
+  #   cli = CLI.new(["translate", "--config", "config.yml"])
+  #   cli.run
+  #
+  # @example Generate config file
+  #   cli = CLI.new(["generate", "config.yml"])
+  #   cli.run
+  #
+  # @example Direct translation
+  #   cli = CLI.new(["direct", "Hello", "--to", "it", "--provider", "chatgpt"])
+  #   cli.run
+  #
+  class CLI
+    # @return [Array<String>] Command-line arguments
+    attr_reader :args
+
+    # Initialize CLI
+    #
+    # @param args [Array<String>] Command-line arguments
+    #
+    # @example
+    #   cli = CLI.new(ARGV)
+    #
+    def initialize(args)
+      @args = args
+    end
+
+    # Run CLI command
+    #
+    # @return [void]
+    #
+    # @example
+    #   cli = CLI.new(ARGV)
+    #   cli.run
+    #
+    def run
+      command = args.first
+
+      case command
+      when "translate"
+        run_translate
+      when "generate"
+        run_generate
+      when "direct"
+        run_direct
+      when "--version", "-v"
+        puts "BetterTranslate version #{VERSION}"
+      when "--help", "-h", nil
+        show_help
+      else
+        puts "Unknown command: #{command}"
+        puts
+        show_help
+      end
+    end
+
+    private
+
+    # Show help message
+    #
+    # @return [void]
+    # @api private
+    #
+    def show_help
+      puts <<~HELP
+        Usage: better_translate COMMAND [OPTIONS]
+
+        Commands:
+          translate              Translate YAML files using config file
+          generate OUTPUT_FILE   Generate sample config file
+          direct TEXT            Translate text directly
+
+        Options:
+          --help, -h             Show this help message
+          --version, -v          Show version
+
+        Examples:
+          better_translate translate --config config.yml
+          better_translate generate config.yml
+          better_translate direct "Hello" --to it --provider chatgpt --api-key KEY
+      HELP
+    end
+
+    # Run translate command
+    #
+    # @return [void]
+    # @api private
+    #
+    def run_translate
+      # @type var options: Hash[Symbol, String]
+      options = {}
+      OptionParser.new do |opts|
+        opts.on("--config FILE", "Config file path") { |v| options[:config] = v }
+      end.parse!(args[1..])
+
+      unless options[:config]
+        puts "Error: --config is required"
+        return
+      end
+
+      unless File.exist?(options[:config])
+        puts "Error: Config file not found: #{options[:config]}"
+        return
+      end
+
+      # Load configuration from YAML
+      yaml_config = YAML.load_file(options[:config])
+
+      # Configure BetterTranslate
+      BetterTranslate.configure do |config|
+        config.provider = yaml_config["provider"]&.to_sym
+        config.openai_key = yaml_config["openai_key"] || ENV["OPENAI_API_KEY"]
+        config.gemini_key = yaml_config["gemini_key"] || ENV["GEMINI_API_KEY"]
+        config.anthropic_key = yaml_config["anthropic_key"] || ENV["ANTHROPIC_API_KEY"]
+
+        config.source_language = yaml_config["source_language"]
+        config.target_languages = yaml_config["target_languages"]&.map do |lang|
+          if lang.is_a?(Hash)
+            { short_name: lang["short_name"], name: lang["name"] }
+          else
+            lang
+          end
+        end
+
+        config.input_file = yaml_config["input_file"]
+        config.output_folder = yaml_config["output_folder"]
+        config.verbose = yaml_config.fetch("verbose", true)
+        config.dry_run = yaml_config.fetch("dry_run", false)
+
+        # Map "full" to :override for backward compatibility
+        translation_mode = yaml_config.fetch("translation_mode", "override")
+        translation_mode = "override" if translation_mode == "full"
+        config.translation_mode = translation_mode.to_sym
+
+        config.preserve_variables = yaml_config.fetch("preserve_variables", true)
+
+        # Exclusions
+        config.global_exclusions = yaml_config["global_exclusions"] || []
+        config.exclusions_per_language = yaml_config["exclusions_per_language"] || {}
+
+        # Provider options
+        config.model = yaml_config["model"] if yaml_config["model"]
+        config.temperature = yaml_config["temperature"] if yaml_config["temperature"]
+        config.max_tokens = yaml_config["max_tokens"] if yaml_config["max_tokens"]
+        config.timeout = yaml_config["timeout"] if yaml_config["timeout"]
+        config.max_retries = yaml_config["max_retries"] if yaml_config["max_retries"]
+        config.rate_limit = yaml_config["rate_limit"] if yaml_config["rate_limit"]
+      end
+
+      # Perform translation
+      puts "Starting translation..."
+      puts "Provider: #{BetterTranslate.configuration.provider}"
+      puts "Source: #{BetterTranslate.configuration.source_language}"
+      puts "Targets: #{BetterTranslate.configuration.target_languages.map { |l| l[:name] }.join(", ")}"
+      puts
+
+      results = BetterTranslate.translate_files
+
+      # Report results
+      puts
+      puts "=" * 60
+      puts "Translation Complete"
+      puts "=" * 60
+      puts "Success: #{results[:success_count]}"
+      puts "Failure: #{results[:failure_count]}"
+
+      return unless results[:errors].any?
+
+      puts
+      puts "Errors:"
+      results[:errors].each do |error|
+        puts "  - #{error[:language]}: #{error[:error]}"
+      end
+    end
+
+    # Run generate command
+    #
+    # @return [void]
+    # @api private
+    #
+    def run_generate
+      output_file = args[1]
+      force = args.include?("--force")
+
+      unless output_file
+        puts "Error: Output file path is required"
+        puts "Usage: better_translate generate OUTPUT_FILE [--force]"
+        return
+      end
+
+      if File.exist?(output_file) && !force
+        puts "Config file already exists at #{output_file}"
+        puts "Use --force to overwrite"
+        return
+      end
+
+      sample_config = {
+        "provider" => "chatgpt",
+        "openai_key" => "YOUR_OPENAI_API_KEY",
+        "gemini_key" => "YOUR_GEMINI_API_KEY",
+        "anthropic_key" => "YOUR_ANTHROPIC_API_KEY",
+        "source_language" => "en",
+        "target_languages" => [
+          { "short_name" => "it", "name" => "Italian" },
+          { "short_name" => "es", "name" => "Spanish" },
+          { "short_name" => "fr", "name" => "French" }
+        ],
+        "input_file" => "locales/en.yml",
+        "output_folder" => "locales",
+        "verbose" => true,
+        "dry_run" => false,
+        "translation_mode" => "override",
+        "preserve_variables" => true,
+        "global_exclusions" => Array.new,
+        "exclusions_per_language" => Hash.new,
+        "model" => nil,
+        "temperature" => 0.3,
+        "max_tokens" => 2000,
+        "timeout" => 30,
+        "max_retries" => 3,
+        "rate_limit" => 10
+      }
+
+      File.write(output_file, sample_config.to_yaml)
+      puts "Generated configuration file at #{output_file}"
+      puts "Please edit it with your API keys and preferences."
+    end
+
+    # Run direct translation command
+    #
+    # @return [void]
+    # @api private
+    #
+    def run_direct
+      text = args[1]
+      # @type var options: Hash[Symbol, String]
+      options = {}
+
+      remaining_args = args[2..] || []
+      OptionParser.new do |opts|
+        opts.on("--to LANG", "Target language code") { |v| options[:to] = v }
+        opts.on("--language-name NAME", "Target language name") { |v| options[:language_name] = v }
+        opts.on("--provider PROVIDER", "Provider (chatgpt, gemini, anthropic)") { |v| options[:provider] = v }
+        opts.on("--api-key KEY", "API key") { |v| options[:api_key] = v }
+      end.parse!(remaining_args)
+
+      unless text
+        puts "Error: Text is required"
+        puts "Usage: better_translate direct TEXT --to LANG --provider PROVIDER --api-key KEY"
+        return
+      end
+
+      unless options[:to]
+        puts "Error: --to is required"
+        return
+      end
+
+      unless options[:provider]
+        puts "Error: --provider is required"
+        return
+      end
+
+      # Default language name
+      options[:language_name] ||= options[:to].upcase
+
+      # Configure
+      BetterTranslate.configure do |config|
+        config.provider = options[:provider].to_sym
+        config.source_language = "en"
+
+        case options[:provider].to_sym
+        when :chatgpt
+          config.openai_key = options[:api_key] || ENV["OPENAI_API_KEY"]
+        when :gemini
+          config.gemini_key = options[:api_key] || ENV["GEMINI_API_KEY"]
+        when :anthropic
+          config.anthropic_key = options[:api_key] || ENV["ANTHROPIC_API_KEY"]
+        end
+      end
+
+      # Translate
+      translator = DirectTranslator.new(BetterTranslate.configuration)
+      result = translator.translate(
+        text,
+        to: options[:to],
+        language_name: options[:language_name]
+      )
+
+      puts result
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+    end
+  end
+end

data/lib/better_translate/configuration.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Configuration class for BetterTranslate
+  #
+  # Manages all configuration options with type safety and validation.
+  #
+  # @example Basic configuration
+  #   config = Configuration.new
+  #   config.provider = :chatgpt
+  #   config.openai_key = ENV['OPENAI_API_KEY']
+  #   config.source_language = "en"
+  #   config.target_languages = [{ short_name: "it", name: "Italian" }]
+  #   config.validate!
+  #
+  class Configuration
+    # @return [Symbol] The translation provider (:chatgpt, :gemini, :anthropic)
+    attr_accessor :provider
+
+    # @return [String, nil] OpenAI API key
+    attr_accessor :openai_key
+
+    # @return [String, nil] Google Gemini API key
+    attr_accessor :google_gemini_key
+
+    # Alias for google_gemini_key (for convenience in configuration)
+    alias gemini_key google_gemini_key
+    alias gemini_key= google_gemini_key=
+
+    # @return [String, nil] Anthropic API key (Claude)
+    attr_accessor :claude_key
+
+    # Alias for claude_key (for convenience in configuration)
+    alias anthropic_key claude_key
+    alias anthropic_key= claude_key=
+
+    # @return [String] Source language code (e.g., "en")
+    attr_accessor :source_language
+
+    # @return [Array<Hash>] Target languages with :short_name and :name
+    attr_accessor :target_languages
+
+    # @return [String] Path to input YAML file
+    attr_accessor :input_file
+
+    # @return [String] Output folder for translated files
+    attr_accessor :output_folder
+
+    # @return [Symbol] Translation mode (:override or :incremental)
+    attr_accessor :translation_mode
+
+    # @return [String, nil] Translation context for domain-specific terminology
+    attr_accessor :translation_context
+
+    # @return [Integer] Maximum concurrent requests
+    attr_accessor :max_concurrent_requests
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :request_timeout
+
+    # @return [Integer] Maximum number of retries
+    attr_accessor :max_retries
+
+    # @return [Float] Retry delay in seconds
+    attr_accessor :retry_delay
+
+    # @return [Boolean] Enable/disable caching
+    attr_accessor :cache_enabled
+
+    # @return [Integer] Cache size (LRU capacity)
+    attr_accessor :cache_size
+
+    # @return [Integer, nil] Cache TTL in seconds (nil = no expiration)
+    attr_accessor :cache_ttl
+
+    # @return [Boolean] Verbose logging
+    attr_accessor :verbose
+
+    # @return [Boolean] Dry run mode (no files written)
+    attr_accessor :dry_run
+
+    # @return [Array<String>] Global exclusions (apply to all languages)
+    attr_accessor :global_exclusions
+
+    # @return [Hash] Language-specific exclusions
+    attr_accessor :exclusions_per_language
+
+    # @return [Boolean] Preserve interpolation variables during translation (default: true)
+    attr_accessor :preserve_variables
+
+    # Initialize a new configuration with defaults
+    def initialize
+      @translation_mode = :override
+      @max_concurrent_requests = 3
+      @request_timeout = 30
+      @max_retries = 3
+      @retry_delay = 2.0
+      @cache_enabled = true
+      @cache_size = 1000
+      @cache_ttl = nil
+      @verbose = false
+      @dry_run = false
+      @global_exclusions = []
+      @exclusions_per_language = {}
+      @target_languages = []
+      @preserve_variables = true
+    end
+
+    # Validate the configuration
+    #
+    # @raise [ConfigurationError] if configuration is invalid
+    # @return [true] if configuration is valid
+    def validate!
+      validate_provider!
+      validate_api_keys!
+      validate_languages!
+      validate_files!
+      validate_optional_settings!
+      true
+    end
+
+    private
+
+    # Validate provider configuration
+    #
+    # @raise [ConfigurationError] if provider is not set or not a Symbol
+    # @return [void]
+    # @api private
+    def validate_provider!
+      raise ConfigurationError, "Provider must be set" if provider.nil?
+      raise ConfigurationError, "Provider must be a Symbol" unless provider.is_a?(Symbol)
+    end
+
+    # Validate API keys based on selected provider
+    #
+    # @raise [ConfigurationError] if required API key is missing
+    # @return [void]
+    # @api private
+    def validate_api_keys!
+      case provider
+      when :chatgpt
+        if openai_key.nil? || openai_key.empty?
+          raise ConfigurationError, "OpenAI API key is required for ChatGPT provider"
+        end
+      when :gemini
+        if google_gemini_key.nil? || google_gemini_key.empty?
+          raise ConfigurationError, "Google Gemini API key is required for Gemini provider"
+        end
+      when :anthropic
+        if anthropic_key.nil? || anthropic_key.empty?
+          raise ConfigurationError, "Anthropic API key is required for Anthropic provider"
+        end
+      end
+    end
+
+    # Validate language configuration
+    #
+    # @raise [ConfigurationError] if source or target languages are invalid
+    # @return [void]
+    # @api private
+    def validate_languages!
+      raise ConfigurationError, "Source language must be set" if source_language.nil? || source_language.empty?
+      raise ConfigurationError, "Target languages must be an array" unless target_languages.is_a?(Array)
+      raise ConfigurationError, "At least one target language is required" if target_languages.empty?
+
+      target_languages.each do |lang|
+        raise ConfigurationError, "Each target language must be a Hash" unless lang.is_a?(Hash)
+        raise ConfigurationError, "Target language must have :short_name" unless lang.key?(:short_name)
+        raise ConfigurationError, "Target language must have :name" unless lang.key?(:name)
+      end
+    end
+
+    # Validate file paths
+    #
+    # @raise [ConfigurationError] if input file or output folder are invalid
+    # @return [void]
+    # @api private
+    def validate_files!
+      raise ConfigurationError, "Input file must be set" if input_file.nil? || input_file.empty?
+      raise ConfigurationError, "Output folder must be set" if output_folder.nil? || output_folder.empty?
+      raise ConfigurationError, "Input file does not exist: #{input_file}" unless File.exist?(input_file)
+    end
+
+    # Validate optional settings (timeouts, retries, cache, etc.)
+    #
+    # @raise [ConfigurationError] if optional settings have invalid values
+    # @return [void]
+    # @api private
+    def validate_optional_settings!
+      valid_modes = %i[override incremental]
+      unless valid_modes.include?(translation_mode)
+        raise ConfigurationError, "Translation mode must be :override or :incremental"
+      end
+
+      raise ConfigurationError, "Max concurrent requests must be positive" if max_concurrent_requests <= 0
+      raise ConfigurationError, "Request timeout must be positive" if request_timeout <= 0
+      raise ConfigurationError, "Max retries must be non-negative" if max_retries.negative?
+      raise ConfigurationError, "Cache size must be positive" if cache_size <= 0
+    end
+  end
+end