better_translate 1.0.0.1 → 1.1.1

data/lib/better_translate/analyzer/reporter.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "csv"
+
+module BetterTranslate
+  module Analyzer
+    # Generates reports for orphan key analysis
+    #
+    # Supports multiple output formats: text, JSON, CSV
+    #
+    # @example Basic usage
+    #   reporter = Reporter.new(
+    #     orphans: ["orphan_key"],
+    #     orphan_details: { "orphan_key" => "Unused" },
+    #     total_keys: 10,
+    #     used_keys: 9,
+    #     usage_percentage: 90.0,
+    #     format: :text
+    #   )
+    #   puts reporter.generate
+    #
+    class Reporter
+      # @return [Array<String>] List of orphan keys
+      attr_reader :orphans
+
+      # @return [Hash] Orphan keys with their values
+      attr_reader :orphan_details
+
+      # @return [Integer] Total number of keys
+      attr_reader :total_keys
+
+      # @return [Integer] Number of used keys
+      attr_reader :used_keys
+
+      # @return [Float] Usage percentage
+      attr_reader :usage_percentage
+
+      # @return [Symbol] Output format (:text, :json, :csv)
+      attr_reader :format
+
+      # Initialize reporter
+      #
+      # @param orphans [Array<String>] List of orphan keys
+      # @param orphan_details [Hash] Orphan keys with values
+      # @param total_keys [Integer] Total number of keys
+      # @param used_keys [Integer] Number of used keys
+      # @param usage_percentage [Float] Usage percentage
+      # @param format [Symbol] Output format (:text, :json, :csv)
+      #
+      def initialize(orphans:, orphan_details:, total_keys:, used_keys:, usage_percentage:, format: :text)
+        @orphans = orphans
+        @orphan_details = orphan_details
+        @total_keys = total_keys
+        @used_keys = used_keys
+        @usage_percentage = usage_percentage
+        @format = format
+      end
+
+      # Generate report in specified format
+      #
+      # @return [String] Generated report
+      #
+      def generate
+        case format
+        when :json
+          generate_json
+        when :csv
+          generate_csv
+        else
+          generate_text
+        end
+      end
+
+      # Save report to file
+      #
+      # @param file_path [String] Output file path
+      #
+      def save_to_file(file_path)
+        File.write(file_path, generate)
+      end
+
+      private
+
+      # Generate text format report
+      #
+      # @return [String] Text report
+      #
+      def generate_text
+        lines = [] # : Array[String]
+        lines << "=" * 60
+        lines << "Orphan Keys Analysis Report"
+        lines << "=" * 60
+        lines << ""
+        lines << "Statistics:"
+        lines << "  Total keys: #{total_keys}"
+        lines << "  Used keys: #{used_keys}"
+        lines << "  Orphan keys: #{orphans.size}"
+        lines << "  Usage: #{usage_percentage}%"
+        lines << ""
+
+        if orphans.empty?
+          lines << "✓ No orphan keys found! All translation keys are being used."
+        else
+          lines << "Orphan Keys (#{orphans.size}):"
+          lines << "-" * 60
+
+          orphans.each do |key|
+            value = orphan_details[key]
+            lines << ""
+            lines << "  Key: #{key}"
+            lines << "  Value: #{value}" if value
+          end
+        end
+
+        lines << ""
+        lines << "=" * 60
+
+        lines.join("\n")
+      end
+
+      # Generate JSON format report
+      #
+      # @return [String] JSON report
+      #
+      def generate_json
+        data = {
+          orphans: orphans,
+          orphan_details: orphan_details,
+          orphan_count: orphans.size,
+          total_keys: total_keys,
+          used_keys: used_keys,
+          usage_percentage: usage_percentage
+        }
+
+        JSON.pretty_generate(data)
+      end
+
+      # Generate CSV format report
+      #
+      # @return [String] CSV report
+      #
+      def generate_csv
+        CSV.generate do |csv|
+          csv << %w[Key Value]
+
+          orphans.each do |key|
+            value = orphan_details[key]
+            csv << [key, value]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_translate/cli.rb

@@ -53,6 +53,8 @@ module BetterTranslate
         run_generate
       when "direct"
         run_direct
+      when "analyze"
+        run_analyze
       when "--version", "-v"
         puts "BetterTranslate version #{VERSION}"
       when "--help", "-h", nil
@@ -79,6 +81,7 @@ module BetterTranslate
           translate              Translate YAML files using config file
           generate OUTPUT_FILE   Generate sample config file
           direct TEXT            Translate text directly
+          analyze                Analyze YAML files for orphan keys
 
         Options:
           --help, -h             Show this help message
@@ -88,6 +91,7 @@ module BetterTranslate
           better_translate translate --config config.yml
           better_translate generate config.yml
           better_translate direct "Hello" --to it --provider chatgpt --api-key KEY
+          better_translate analyze --source config/locales/en.yml --scan-path app/
       HELP
     end
 
@@ -221,8 +225,8 @@ module BetterTranslate
         "dry_run" => false,
         "translation_mode" => "override",
         "preserve_variables" => true,
-        "global_exclusions" => [],
-        "exclusions_per_language" => {},
+        "global_exclusions" => [], # : Array[String]
+        "exclusions_per_language" => {}, # : Hash[String, Array[String]]
         "model" => nil,
         "temperature" => 0.3,
         "max_tokens" => 2000,
@@ -300,5 +304,80 @@ module BetterTranslate
     rescue StandardError => e
       puts "Error: #{e.message}"
     end
+
+    # Run analyze command
+    #
+    # @return [void]
+    # @api private
+    #
+    def run_analyze
+      # @type var options: Hash[Symbol, String]
+      options = {}
+      OptionParser.new do |opts|
+        opts.on("--source FILE", "Source YAML file path") { |v| options[:source] = v }
+        opts.on("--scan-path PATH", "Path to scan for code files") { |v| options[:scan_path] = v }
+        opts.on("--format FORMAT", "Output format (text, json, csv)") { |v| options[:format] = v }
+        opts.on("--output FILE", "Output file path") { |v| options[:output] = v }
+      end.parse!(args[1..])
+
+      # Validate required options
+      unless options[:source]
+        puts "Error: --source is required"
+        return
+      end
+
+      unless options[:scan_path]
+        puts "Error: --scan-path is required"
+        return
+      end
+
+      # Validate paths exist
+      unless File.exist?(options[:source])
+        puts "Error: Source file not found: #{options[:source]}"
+        return
+      end
+
+      unless File.exist?(options[:scan_path])
+        puts "Error: Scan path not found: #{options[:scan_path]}"
+        return
+      end
+
+      # Default format
+      format = (options[:format] || "text").to_sym
+
+      # Scan keys from YAML
+      key_scanner = Analyzer::KeyScanner.new(options[:source])
+      all_keys = key_scanner.scan
+
+      # Scan code for used keys
+      code_scanner = Analyzer::CodeScanner.new(options[:scan_path])
+      used_keys = code_scanner.scan
+
+      # Detect orphans
+      detector = Analyzer::OrphanDetector.new(all_keys, used_keys)
+      orphans = detector.detect
+
+      # Generate report
+      reporter = Analyzer::Reporter.new(
+        orphans: orphans,
+        orphan_details: detector.orphan_details,
+        total_keys: all_keys.size,
+        used_keys: used_keys.size,
+        usage_percentage: detector.usage_percentage,
+        format: format
+      )
+
+      report = reporter.generate
+
+      # Output or save
+      if options[:output]
+        reporter.save_to_file(options[:output])
+        puts "Report saved to #{options[:output]}"
+      else
+        puts report
+      end
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+    end
   end
 end

data/lib/better_translate/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "json"
+
 module BetterTranslate
   # Configuration class for BetterTranslate
   #
@@ -13,6 +16,15 @@ module BetterTranslate
   #   config.target_languages = [{ short_name: "it", name: "Italian" }]
   #   config.validate!
   #
+  # @example Provider-specific options
+  #   config.model = "gpt-5-nano"           # Specify model (optional, provider-specific)
+  #   config.temperature = 0.7              # Control creativity (0.0-2.0, default: 0.3)
+  #   config.max_tokens = 1500              # Limit response length (default: 2000)
+  #
+  # @example Backup configuration
+  #   config.create_backup = true           # Enable automatic backups (default: true)
+  #   config.max_backups = 5                # Keep up to 5 backup files (default: 3)
+  #
   class Configuration
     # @return [Symbol] The translation provider (:chatgpt, :gemini, :anthropic)
     attr_accessor :provider
@@ -40,9 +52,12 @@ module BetterTranslate
     # @return [Array<Hash>] Target languages with :short_name and :name
     attr_accessor :target_languages
 
-    # @return [String] Path to input YAML file
+    # @return [String] Path to input YAML file (for backward compatibility, use input_files for multiple files)
     attr_accessor :input_file
 
+    # @return [Array<String>, String] Multiple input files (array or glob pattern)
+    attr_accessor :input_files
+
     # @return [String] Output folder for translated files
     attr_accessor :output_folder
 
@@ -88,6 +103,21 @@ module BetterTranslate
     # @return [Boolean] Preserve interpolation variables during translation (default: true)
     attr_accessor :preserve_variables
 
+    # @return [String, nil] AI model to use (provider-specific, e.g., "gpt-5-nano", "gemini-2.0-flash-exp")
+    attr_accessor :model
+
+    # @return [Float] Temperature for AI generation (0.0-2.0, higher = more creative)
+    attr_accessor :temperature
+
+    # @return [Integer] Maximum tokens for AI response
+    attr_accessor :max_tokens
+
+    # @return [Boolean] Create backup files before overwriting (default: true)
+    attr_accessor :create_backup
+
+    # @return [Integer] Maximum number of backup files to keep (default: 3)
+    attr_accessor :max_backups
+
     # Initialize a new configuration with defaults
     def initialize
       @translation_mode = :override
@@ -104,6 +134,11 @@ module BetterTranslate
       @exclusions_per_language = {}
       @target_languages = []
       @preserve_variables = true
+      @model = nil
+      @temperature = 0.3
+      @max_tokens = 2000
+      @create_backup = true
+      @max_backups = 3
     end
 
     # Validate the configuration
@@ -176,9 +211,20 @@ module BetterTranslate
     # @return [void]
     # @api private
     def validate_files!
-      raise ConfigurationError, "Input file must be set" if input_file.nil? || input_file.empty?
+      # Check if either input_file or input_files is set
+      has_input = (input_file && !input_file.empty?) || input_files
+
+      raise ConfigurationError, "Input file or input_files must be set" unless has_input
       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)
+
+      # Only validate input_file exists if using single file mode (not glob pattern or array)
+      return unless input_file && !input_file.empty? && !input_files
+
+      # Create input file if it doesn't exist
+      return if File.exist?(input_file)
+
+      create_default_input_file!(input_file)
+      puts "Created empty input file: #{input_file}" if verbose
     end
 
     # Validate optional settings (timeouts, retries, cache, etc.)
@@ -196,6 +242,33 @@ module BetterTranslate
       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
+
+      # Validate temperature range (AI providers typically accept 0.0-2.0)
+      if temperature && (temperature < 0.0 || temperature > 2.0)
+        raise ConfigurationError, "Temperature must be between 0.0 and 2.0"
+      end
+
+      # Validate max_tokens is positive
+      raise ConfigurationError, "Max tokens must be positive" if max_tokens && max_tokens <= 0
+    end
+
+    # Create a default input file with root language key
+    #
+    # @param file_path [String] Path to the input file
+    # @return [void]
+    # @api private
+    def create_default_input_file!(file_path)
+      # Create directory if needed
+      FileUtils.mkdir_p(File.dirname(file_path))
+
+      # Determine file format (YAML or JSON)
+      content = if file_path.end_with?(".json")
+                  JSON.pretty_generate({ source_language => {} })
+                else
+                  { source_language => {} }.to_yaml
+                end
+
+      File.write(file_path, content)
     end
   end
 end

data/lib/better_translate/errors.rb

@@ -90,6 +90,15 @@ module BetterTranslate
   #   )
   class YamlError < Error; end
 
+  # Raised when JSON parsing fails
+  #
+  # @example JSON syntax error
+  #   raise JsonError.new(
+  #     "Invalid JSON syntax",
+  #     context: { file_path: "config/locales/en.json", error: "unexpected token" }
+  #   )
+  class JsonError < Error; end
+
   # Raised when a provider is not found
   #
   # @example Provider not found

data/lib/better_translate/json_handler.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module BetterTranslate
+  # Handles JSON file operations
+  #
+  # Provides methods for:
+  # - Reading and parsing JSON files
+  # - Writing JSON files with proper formatting
+  # - Merging translations (incremental mode)
+  # - Handling exclusions
+  # - Flattening/unflattening nested structures
+  #
+  # @example Reading a JSON file
+  #   handler = JsonHandler.new(config)
+  #   data = handler.read_json("config/locales/en.json")
+  #
+  # @example Writing translations
+  #   handler.write_json("config/locales/it.json", { "it" => { "greeting" => "Ciao" } })
+  #
+  class JsonHandler
+    # @return [Configuration] Configuration object
+    attr_reader :config
+
+    # Initialize JSON handler
+    #
+    # @param config [Configuration] Configuration object
+    #
+    # @example
+    #   config = Configuration.new
+    #   handler = JsonHandler.new(config)
+    #
+    def initialize(config)
+      @config = config
+    end
+
+    # Read and parse JSON file
+    #
+    # @param file_path [String] Path to JSON file
+    # @return [Hash] Parsed JSON content
+    # @raise [FileError] if file cannot be read
+    # @raise [JsonError] if JSON is invalid
+    #
+    # @example
+    #   data = handler.read_json("config/locales/en.json")
+    #   #=> { "en" => { "greeting" => "Hello" } }
+    #
+    def read_json(file_path)
+      Validator.validate_file_exists!(file_path)
+
+      content = File.read(file_path)
+      return {} if content.strip.empty?
+
+      JSON.parse(content)
+    rescue Errno::ENOENT => e
+      raise FileError.new("File does not exist: #{file_path}", context: { error: e.message })
+    rescue JSON::ParserError => e
+      raise JsonError.new("Invalid JSON syntax in #{file_path}", context: { error: e.message })
+    end
+
+    # Write hash to JSON file
+    #
+    # @param file_path [String] Output file path
+    # @param data [Hash] Data to write
+    # @param diff_preview [DiffPreview, nil] Optional diff preview instance
+    # @return [Hash, nil] Summary hash if dry_run, nil otherwise
+    # @raise [FileError] if file cannot be written
+    #
+    # @example
+    #   handler.write_json("config/locales/it.json", { "it" => { "greeting" => "Ciao" } })
+    #
+    def write_json(file_path, data, diff_preview: nil)
+      summary = nil
+
+      # Show diff preview if in dry run mode
+      if config.dry_run && diff_preview
+        existing_data = File.exist?(file_path) ? read_json(file_path) : {} # : Hash[untyped, untyped]
+        summary = diff_preview.show_diff(existing_data, data, file_path)
+      end
+
+      return summary if config.dry_run
+
+      # Create backup if enabled and file exists
+      create_backup_file(file_path) if config.create_backup && File.exist?(file_path)
+
+      # Ensure output directory exists
+      FileUtils.mkdir_p(File.dirname(file_path))
+
+      # Write JSON with proper indentation
+      File.write(file_path, JSON.pretty_generate(data))
+
+      nil
+    rescue Errno::EACCES => e
+      raise FileError.new("Permission denied: #{file_path}", context: { error: e.message })
+    rescue StandardError => e
+      raise FileError.new("Failed to write JSON: #{file_path}", context: { error: e.message })
+    end
+
+    # Get translatable strings from source JSON
+    #
+    # Reads the input file and returns a flattened hash of strings.
+    # Removes the root language key if present.
+    #
+    # @return [Hash] Flattened hash of translatable strings
+    #
+    # @example
+    #   strings = handler.get_source_strings
+    #   #=> { "greeting" => "Hello", "nav.home" => "Home" }
+    #
+    def get_source_strings
+      return {} unless config.input_file
+
+      source_data = read_json(config.input_file)
+      # Remove root language key if present (e.g., "en:")
+      source_data = source_data[config.source_language] || source_data
+
+      Utils::HashFlattener.flatten(source_data)
+    end
+
+    # Filter out excluded keys for a specific language
+    #
+    # @param strings [Hash] Flattened strings
+    # @param target_lang_code [String] Target language code
+    # @return [Hash] Filtered strings
+    #
+    # @example
+    #   filtered = handler.filter_exclusions(strings, "it")
+    #
+    def filter_exclusions(strings, target_lang_code)
+      excluded_keys = config.global_exclusions.dup
+      excluded_keys += config.exclusions_per_language[target_lang_code] || []
+
+      strings.reject { |key, _| excluded_keys.include?(key) }
+    end
+
+    # Merge translated strings with existing file (incremental mode)
+    #
+    # @param file_path [String] Existing file path
+    # @param new_translations [Hash] New translations (flattened)
+    # @return [Hash] Merged translations (nested)
+    #
+    # @example
+    #   merged = handler.merge_translations("config/locales/it.json", new_translations)
+    #
+    def merge_translations(file_path, new_translations)
+      if File.exist?(file_path)
+        existing = read_json(file_path)
+        # Extract actual translations (remove language wrapper if present)
+        target_lang = config.target_languages.first[:short_name]
+        existing = existing[target_lang] || existing
+      else
+        existing = {} # : Hash[untyped, untyped]
+      end
+
+      existing_flat = Utils::HashFlattener.flatten(existing)
+
+      # Merge: existing takes precedence
+      merged = new_translations.merge(existing_flat)
+
+      Utils::HashFlattener.unflatten(merged)
+    end
+
+    # Build output file path for target language
+    #
+    # @param target_lang_code [String] Target language code
+    # @return [String] Output file path
+    #
+    # @example
+    #   path = handler.build_output_path("it")
+    #   #=> "config/locales/it.json"
+    #
+    def build_output_path(target_lang_code)
+      return "#{target_lang_code}.json" unless config.output_folder
+
+      File.join(config.output_folder, "#{target_lang_code}.json")
+    end
+
+    private
+
+    # Create backup file with rotation support
+    #
+    # @param file_path [String] Path to file to backup
+    # @return [void]
+    # @api private
+    #
+    def create_backup_file(file_path)
+      return unless File.exist?(file_path)
+
+      # Rotate existing backups if max_backups > 1
+      rotate_backups(file_path) if config.max_backups > 1
+
+      # Create primary backup
+      backup_path = "#{file_path}.bak"
+      FileUtils.cp(file_path, backup_path)
+    end
+
+    # Rotate backup files, keeping only max_backups
+    #
+    # @param file_path [String] Base file path
+    # @return [void]
+    # @api private
+    #
+    def rotate_backups(file_path)
+      primary_backup = "#{file_path}.bak"
+      return unless File.exist?(primary_backup)
+
+      # Clean up ANY backups that would exceed max_backups after rotation
+      10.downto(config.max_backups) do |i|
+        numbered_backup = "#{file_path}.bak.#{i}"
+        FileUtils.rm_f(numbered_backup) if File.exist?(numbered_backup)
+      end
+
+      # Rotate numbered backups from high to low to avoid overwrites
+      (config.max_backups - 2).downto(1) do |i|
+        old_path = "#{file_path}.bak.#{i}"
+        new_path = "#{file_path}.bak.#{i + 1}"
+
+        FileUtils.mv(old_path, new_path) if File.exist?(old_path)
+      end
+
+      # Move primary backup to .bak.1
+      FileUtils.mv(primary_backup, "#{file_path}.bak.1")
+    end
+  end
+end