better_translate 1.0.0 → 1.1.0

data/lib/better_translate/analyzer/code_scanner.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "set"
+
+module BetterTranslate
+  module Analyzer
+    # Scans code files to find i18n key references
+    #
+    # Supports multiple patterns:
+    # - t('key') / t("key")
+    # - I18n.t(:key) / I18n.t('key')
+    # - <%= t('key') %> in ERB
+    #
+    # @example Basic usage
+    #   scanner = CodeScanner.new("app/")
+    #   keys = scanner.scan
+    #   #=> #<Set: {"users.greeting", "products.list"}>
+    #
+    class CodeScanner
+      # I18n patterns to match
+      #
+      # Matches:
+      # - t('users.greeting')
+      # - t("users.greeting")
+      # - I18n.t(:users.greeting)
+      # - I18n.t('users.greeting')
+      # - I18n.translate('users.greeting')
+      I18N_PATTERNS = [
+        /\bt\(['"]([a-z0-9_.]+)['"]/i,             # t('key') or t("key")
+        /\bI18n\.t\(:([a-z0-9_.]+)/i,              # I18n.t(:key)
+        /\bI18n\.t\(['"]([a-z0-9_.]+)['"]/i,       # I18n.t('key')
+        /\bI18n\.translate\(['"]([a-z0-9_.]+)['"]/i # I18n.translate('key')
+      ].freeze
+
+      # File extensions to scan
+      SCANNABLE_EXTENSIONS = %w[.rb .erb .html.erb .haml .slim].freeze
+
+      # @return [String] Path to scan (file or directory)
+      attr_reader :path
+
+      # @return [Set] Found i18n keys
+      attr_reader :keys
+
+      # @return [Array<String>] List of scanned files
+      attr_reader :files_scanned
+
+      # Initialize scanner with path
+      #
+      # @param path [String] File or directory path to scan
+      #
+      def initialize(path)
+        @path = path
+        @keys = Set.new
+        @files_scanned = []
+      end
+
+      # Scan path and extract i18n keys
+      #
+      # @return [Set] Set of found i18n keys
+      # @raise [FileError] if path does not exist
+      #
+      # @example
+      #   scanner = CodeScanner.new("app/")
+      #   keys = scanner.scan
+      #   #=> #<Set: {"users.greeting"}>
+      #
+      def scan
+        validate_path!
+
+        files = collect_files
+        files.each do |file|
+          scan_file(file)
+          @files_scanned << file
+        end
+
+        @keys
+      end
+
+      # Get count of unique keys found
+      #
+      # @return [Integer] Number of unique keys
+      #
+      def key_count
+        @keys.size
+      end
+
+      private
+
+      # Validate that path exists
+      #
+      # @raise [FileError] if path does not exist
+      #
+      def validate_path!
+        return if File.exist?(path)
+
+        raise FileError.new(
+          "Path does not exist: #{path}",
+          context: { path: path }
+        )
+      end
+
+      # Collect all scannable files from path
+      #
+      # @return [Array<String>] List of file paths
+      #
+      def collect_files
+        if File.file?(path)
+          return [path] if scannable_file?(path)
+
+          return []
+        end
+
+        Dir.glob(File.join(path, "**", "*")).select do |file|
+          File.file?(file) && scannable_file?(file)
+        end
+      end
+
+      # Check if file should be scanned
+      #
+      # @param file [String] File path
+      # @return [Boolean]
+      #
+      def scannable_file?(file)
+        SCANNABLE_EXTENSIONS.any? { |ext| file.end_with?(ext) }
+      end
+
+      # Scan single file and extract keys
+      #
+      # @param file [String] File path
+      #
+      def scan_file(file)
+        content = File.read(file)
+
+        # Remove commented lines to avoid false positives
+        lines = content.split("\n")
+        active_lines = lines.reject { |line| line.strip.start_with?("#", "//", "<!--") }
+        active_content = active_lines.join("\n")
+
+        I18N_PATTERNS.each do |pattern|
+          active_content.scan(pattern) do |match|
+            key = match.is_a?(Array) ? match.first : match
+            @keys.add(key) if key
+          end
+        end
+      rescue StandardError => e
+        # Skip files that can't be read
+        warn "Warning: Could not scan #{file}: #{e.message}" if ENV["VERBOSE"]
+      end
+    end
+  end
+end

data/lib/better_translate/analyzer/key_scanner.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module BetterTranslate
+  module Analyzer
+    # Scans YAML translation files and extracts all keys in flatten format
+    #
+    # @example Basic usage
+    #   scanner = KeyScanner.new("config/locales/en.yml")
+    #   keys = scanner.scan
+    #   #=> { "users.greeting" => "Hello", "users.welcome" => "Welcome %{name}" }
+    #
+    class KeyScanner
+      # @return [String] Path to the YAML file
+      attr_reader :file_path
+
+      # @return [Hash] Flatten keys extracted from YAML
+      attr_reader :keys
+
+      # Initialize scanner with YAML file path
+      #
+      # @param file_path [String] Path to YAML file
+      #
+      def initialize(file_path)
+        @file_path = file_path
+        @keys = {}
+      end
+
+      # Scan YAML file and extract all flatten keys
+      #
+      # @return [Hash] Flatten keys with their values
+      # @raise [FileError] if file does not exist
+      # @raise [YamlError] if YAML is invalid
+      #
+      # @example
+      #   scanner = KeyScanner.new("en.yml")
+      #   keys = scanner.scan
+      #   #=> { "users.greeting" => "Hello" }
+      #
+      def scan
+        validate_file!
+
+        begin
+          content = YAML.load_file(file_path)
+
+          # Skip root language key (en, it, fr, etc.) and start from its content
+          if content.is_a?(Hash) && content.size == 1
+            root_key = content.keys.first.to_s
+            content = content[root_key] || {} if root_key.match?(/^[a-z]{2}(-[A-Z]{2})?$/)
+          end
+
+          flatten_keys(content)
+        rescue Psych::SyntaxError => e
+          raise YamlError.new(
+            "Invalid YAML syntax in #{file_path}",
+            context: { file: file_path, error: e.message }
+          )
+        end
+
+        @keys
+      end
+
+      # Get total count of keys
+      #
+      # @return [Integer] Number of keys
+      #
+      def key_count
+        @keys.size
+      end
+
+      private
+
+      # Validate that file exists
+      #
+      # @raise [FileError] if file does not exist
+      #
+      def validate_file!
+        return if File.exist?(file_path)
+
+        raise FileError.new(
+          "Translation file does not exist: #{file_path}",
+          context: { file: file_path }
+        )
+      end
+
+      # Flatten nested hash into dot-notation keys
+      #
+      # @param hash [Hash] Nested hash to flatten
+      # @param prefix [String] Prefix for current level
+      #
+      # @example
+      #   flatten_keys({ "users" => { "greeting" => "Hello" } })
+      #   #=> { "users.greeting" => "Hello" }
+      #
+      def flatten_keys(hash, prefix = nil)
+        hash.each do |key, value|
+          current_key = prefix ? "#{prefix}.#{key}" : key.to_s
+
+          if value.is_a?(Hash)
+            flatten_keys(value, current_key)
+          else
+            @keys[current_key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_translate/analyzer/orphan_detector.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Detects orphan i18n keys (keys defined but never used in code)
+    #
+    # @example Basic usage
+    #   all_keys = { "users.greeting" => "Hello", "orphan" => "Unused" }
+    #   used_keys = Set.new(["users.greeting"])
+    #
+    #   detector = OrphanDetector.new(all_keys, used_keys)
+    #   orphans = detector.detect
+    #   #=> ["orphan"]
+    #
+    class OrphanDetector
+      # @return [Hash] All translation keys with their values
+      attr_reader :all_keys
+
+      # @return [Set] Keys that are used in code
+      attr_reader :used_keys
+
+      # @return [Array<String>] Orphan keys (not used in code)
+      attr_reader :orphans
+
+      # Initialize detector
+      #
+      # @param all_keys [Hash] All translation keys from YAML files
+      # @param used_keys [Set] Keys found in code
+      #
+      def initialize(all_keys, used_keys)
+        @all_keys = all_keys
+        @used_keys = used_keys
+        @orphans = []
+      end
+
+      # Detect orphan keys
+      #
+      # Compares all keys with used keys and identifies those that are never referenced.
+      #
+      # @return [Array<String>] List of orphan key names
+      #
+      # @example
+      #   detector.detect
+      #   #=> ["orphan_key", "another.orphan"]
+      #
+      def detect
+        @orphans = all_keys.keys.reject { |key| used_keys.include?(key) }
+      end
+
+      # Get count of orphan keys
+      #
+      # @return [Integer] Number of orphan keys
+      #
+      def orphan_count
+        @orphans.size
+      end
+
+      # Get details of orphan keys with their values
+      #
+      # @return [Hash] Hash of orphan keys and their translation values
+      #
+      # @example
+      #   detector.orphan_details
+      #   #=> { "orphan_key" => "This is never used" }
+      #
+      def orphan_details
+        @orphans.each_with_object({}) do |key, details|
+          details[key] = all_keys[key]
+        end
+      end
+
+      # Calculate usage percentage
+      #
+      # @return [Float] Percentage of keys that are used (0.0 to 100.0)
+      #
+      # @example
+      #   detector.usage_percentage
+      #   #=> 75.0  # 6 out of 8 keys are used
+      #
+      def usage_percentage
+        return 0.0 if all_keys.empty?
+
+        used_count = all_keys.size - @orphans.size
+        (used_count.to_f / all_keys.size * 100).round(1)
+      end
+    end
+  end
+end

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 = []
+        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/cache.rb

@@ -52,7 +52,8 @@ module BetterTranslate
         entry = @cache[key]
 
         # Check TTL
-        if @ttl && entry && Time.now - entry[:timestamp] > @ttl
+        ttl_value = @ttl
+        if ttl_value && entry && Time.now - entry[:timestamp] > ttl_value
           @cache.delete(key)
           return nil
         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" => Array.new,
-        "exclusions_per_language" => Hash.new,
+        "global_exclusions" => [],
+        "exclusions_per_language" => {},
         "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