better_translate 1.0.0.1 → 1.1.1

data/lib/tasks/better_translate.rake

@@ -9,59 +9,75 @@ unless Rake::Task.task_defined?(:environment)
   end
 end
 
+# rubocop:disable Metrics/BlockLength
 namespace :better_translate do
   desc "Translate YAML locale files using AI providers"
   task translate: :environment do
-    config_file = Rails.root.join("config", "better_translate.yml")
+    # Check if configuration is already loaded (from initializer)
+    if BetterTranslate.configuration.provider.nil?
+      # No initializer configuration found, try loading from YAML
+      config_file = Rails.root.join("config", "better_translate.yml")
 
-    unless File.exist?(config_file)
-      puts "Error: Configuration file not found at #{config_file}"
-      puts "Run 'rake better_translate:config:generate' to create one."
-      exit 1
-    end
+      unless File.exist?(config_file)
+        puts "Error: No configuration found"
+        puts "Either:"
+        puts "  1. Create config/initializers/better_translate.rb (recommended)"
+        puts "  2. Run 'rake better_translate:config:generate' to create YAML config"
+        exit 1
+      end
 
-    # Load configuration from YAML
-    yaml_config = YAML.load_file(config_file)
-
-    # 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
+      # Load configuration from YAML
+      yaml_config = YAML.load_file(config_file)
+
+      # 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
+    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"]
+    # Validate configuration (whether from initializer or YAML)
+    begin
+      BetterTranslate.configuration.validate!
+    rescue BetterTranslate::ConfigurationError => e
+      puts "Error: Invalid configuration"
+      puts e.message
+      exit 1
     end
 
     # Perform translation
@@ -134,3 +150,4 @@ namespace :better_translate do
     end
   end
 end
+# rubocop:enable Metrics/BlockLength

data/sig/better_translate/analyzer/code_scanner.rbs

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Scans code files to find i18n key references
+    class CodeScanner
+      # I18n patterns to match
+      I18N_PATTERNS: Array[Regexp]
+
+      # File extensions to scan
+      SCANNABLE_EXTENSIONS: Array[String]
+
+      # Path to scan (file or directory)
+      attr_reader path: String
+
+      # Found i18n keys
+      attr_reader keys: Set[String]
+
+      # List of scanned files
+      attr_reader files_scanned: Array[String]
+
+      # Initialize scanner with path
+      #
+      # @param path File or directory path to scan
+      def initialize: (String path) -> void
+
+      # Scan path and extract i18n keys
+      #
+      # @return Set of found i18n keys
+      def scan: () -> Set[String]
+
+      # Get count of unique keys found
+      #
+      # @return Number of unique keys
+      def key_count: () -> Integer
+
+      private
+
+      # Validate that path exists
+      def validate_path!: () -> void
+
+      # Collect all scannable files from path
+      #
+      # @return List of file paths
+      def collect_files: () -> Array[String]
+
+      # Check if file should be scanned
+      #
+      # @param file File path
+      # @return Boolean
+      def scannable_file?: (String file) -> bool
+
+      # Scan single file and extract keys
+      #
+      # @param file File path
+      def scan_file: (String file) -> void
+    end
+  end
+end

data/sig/better_translate/analyzer/key_scanner.rbs

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Scans YAML translation files and extracts all keys in flatten format
+    class KeyScanner
+      # Path to the YAML file
+      attr_reader file_path: String
+
+      # Flatten keys extracted from YAML
+      attr_reader keys: Hash[String, untyped]
+
+      # Initialize scanner with YAML file path
+      #
+      # @param file_path Path to YAML file
+      def initialize: (String file_path) -> void
+
+      # Scan YAML file and extract all flatten keys
+      #
+      # @return Flatten keys with their values
+      def scan: () -> Hash[String, untyped]
+
+      # Get total count of keys
+      #
+      # @return Number of keys
+      def key_count: () -> Integer
+
+      private
+
+      # Validate that file exists
+      def validate_file!: () -> void
+
+      # Flatten nested hash into dot-notation keys
+      #
+      # @param hash Nested hash to flatten
+      # @param prefix Prefix for current level
+      def flatten_keys: (Hash[untyped, untyped] hash, ?String? prefix) -> void
+    end
+  end
+end

data/sig/better_translate/analyzer/orphan_detector.rbs

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Detects orphan i18n keys (keys defined but never used in code)
+    class OrphanDetector
+      # All translation keys with their values
+      attr_reader all_keys: Hash[String, untyped]
+
+      # Keys that are used in code
+      attr_reader used_keys: Set[String]
+
+      # Orphan keys (not used in code)
+      attr_reader orphans: Array[String]
+
+      # Initialize detector
+      #
+      # @param all_keys All translation keys from YAML files
+      # @param used_keys Keys found in code
+      def initialize: (Hash[String, untyped] all_keys, Set[String] used_keys) -> void
+
+      # Detect orphan keys
+      #
+      # @return List of orphan key names
+      def detect: () -> Array[String]
+
+      # Get count of orphan keys
+      #
+      # @return Number of orphan keys
+      def orphan_count: () -> Integer
+
+      # Get details of orphan keys with their values
+      #
+      # @return Hash of orphan keys and their translation values
+      def orphan_details: () -> Hash[String, untyped]
+
+      # Calculate usage percentage
+      #
+      # @return Percentage of keys that are used (0.0 to 100.0)
+      def usage_percentage: () -> Float
+    end
+  end
+end

data/sig/better_translate/analyzer/reporter.rbs

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Generates reports for orphan key analysis
+    class Reporter
+      # List of orphan keys
+      attr_reader orphans: Array[String]
+
+      # Orphan keys with their values
+      attr_reader orphan_details: Hash[String, untyped]
+
+      # Total number of keys
+      attr_reader total_keys: Integer
+
+      # Number of used keys
+      attr_reader used_keys: Integer
+
+      # Usage percentage
+      attr_reader usage_percentage: Float
+
+      # Output format (:text, :json, :csv)
+      attr_reader format: Symbol
+
+      # Initialize reporter
+      #
+      # @param orphans List of orphan keys
+      # @param orphan_details Orphan keys with values
+      # @param total_keys Total number of keys
+      # @param used_keys Number of used keys
+      # @param usage_percentage Usage percentage
+      # @param format Output format (:text, :json, :csv)
+      def initialize: (
+        orphans: Array[String],
+        orphan_details: Hash[String, untyped],
+        total_keys: Integer,
+        used_keys: Integer,
+        usage_percentage: Float,
+        ?format: Symbol
+      ) -> void
+
+      # Generate report in specified format
+      #
+      # @return Generated report
+      def generate: () -> String
+
+      # Save report to file
+      #
+      # @param file_path Output file path
+      def save_to_file: (String file_path) -> void
+
+      private
+
+      # Generate text format report
+      #
+      # @return Text report
+      def generate_text: () -> String
+
+      # Generate JSON format report
+      #
+      # @return JSON report
+      def generate_json: () -> String
+
+      # Generate CSV format report
+      #
+      # @return CSV report
+      def generate_csv: () -> String
+    end
+  end
+end

data/sig/better_translate/cli.rbs

@@ -20,5 +20,7 @@ module BetterTranslate
     def run_generate: () -> void
 
     def run_direct: () -> void
+
+    def run_analyze: () -> void
   end
 end

data/sig/better_translate/configuration.rbs

@@ -27,6 +27,9 @@ module BetterTranslate
     @global_exclusions: Array[String]
     @exclusions_per_language: Hash[String, Array[String]]
     @preserve_variables: bool
+    @input_files: (String | Array[String])?
+    @create_backup: bool
+    @max_backups: Integer
 
     attr_accessor provider: (Symbol | nil)
     attr_accessor openai_key: String?
@@ -56,6 +59,9 @@ module BetterTranslate
     attr_accessor global_exclusions: Array[String]
     attr_accessor exclusions_per_language: Hash[String, Array[String]]
     attr_accessor preserve_variables: bool
+    attr_accessor input_files: (String | Array[String])?
+    attr_accessor create_backup: bool
+    attr_accessor max_backups: Integer
 
     # Provider-specific options
     attr_accessor model: String?

data/sig/better_translate/errors.rbs

@@ -40,6 +40,10 @@ module BetterTranslate
   class YamlError < Error
   end
 
+  # Raised when JSON parsing fails
+  class JsonError < Error
+  end
+
   # Raised when a provider is not found
   class ProviderNotFoundError < Error
   end

data/sig/better_translate/json_handler.rbs

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Handles JSON file operations
+  class JsonHandler
+    # Configuration object
+    attr_reader config: Configuration
+
+    # Initialize JSON handler
+    #
+    # @param config Configuration object
+    def initialize: (Configuration config) -> void
+
+    # Read and parse JSON file
+    #
+    # @param file_path Path to JSON file
+    # @return Parsed JSON content
+    def read_json: (String file_path) -> Hash[untyped, untyped]
+
+    # Write hash to JSON file
+    #
+    # @param file_path Output file path
+    # @param data Data to write
+    # @param diff_preview Optional diff preview instance
+    # @return Summary hash if dry_run, nil otherwise
+    def write_json: (String file_path, Hash[untyped, untyped] data, ?diff_preview: untyped) -> (Hash[Symbol, untyped] | nil)
+
+    # Get translatable strings from source JSON
+    #
+    # @return Flattened hash of translatable strings
+    def get_source_strings: () -> Hash[String, untyped]
+
+    # Filter out excluded keys for a specific language
+    #
+    # @param strings Flattened strings
+    # @param target_lang_code Target language code
+    # @return Filtered strings
+    def filter_exclusions: (Hash[String, untyped] strings, String target_lang_code) -> Hash[String, untyped]
+
+    # Merge translated strings with existing file (incremental mode)
+    #
+    # @param file_path Existing file path
+    # @param new_translations New translations (flattened)
+    # @return Merged translations (nested)
+    def merge_translations: (String file_path, Hash[String, untyped] new_translations) -> Hash[String, untyped]
+
+    # Build output file path for target language
+    #
+    # @param target_lang_code Target language code
+    # @return Output file path
+    def build_output_path: (String target_lang_code) -> String
+
+    private
+
+    # Create backup file with rotation support
+    #
+    # @param file_path Path to file to backup
+    def create_backup_file: (String file_path) -> void
+
+    # Rotate backup files, keeping only max_backups
+    #
+    # @param file_path Base file path
+    def rotate_backups: (String file_path) -> void
+  end
+end

data/sig/better_translate/progress_tracker.rbs

@@ -14,7 +14,7 @@ module BetterTranslate
 
     def complete: (String language, Integer total_strings) -> void
 
-    def error: (String language, StandardError error) -> void
+    def error: (String language, Exception error) -> void
 
     def reset: () -> void
 

data/sig/better_translate/translator.rbs

@@ -10,6 +10,7 @@ module BetterTranslate
     @provider: Providers::BaseHttpProvider
     @yaml_handler: YAMLHandler
     @progress_tracker: ProgressTracker
+    @input_files: Array[String]
 
     attr_reader config: Configuration
 
@@ -19,6 +20,16 @@ module BetterTranslate
 
     private
 
-    def translate_language: (Hash[String, untyped] source_strings, Hash[Symbol, String] lang) -> void
+    def resolve_input_files: () -> Array[String]
+
+    def translate_parallel: (Hash[String, untyped] source_strings, (YAMLHandler | JsonHandler) handler) -> translation_results
+
+    def translate_sequential: (Hash[String, untyped] source_strings, (YAMLHandler | JsonHandler) handler) -> translation_results
+
+    def translate_language: (Hash[String, untyped] source_strings, Hash[Symbol, String] lang, (YAMLHandler | JsonHandler) handler) -> void
+
+    def record_error: (translation_results results, Hash[Symbol, String] lang, Exception error) -> void
+
+    def build_output_path_for_file: (String input_file, String target_lang_code) -> String
   end
 end

data/sig/better_translate/yaml_handler.rbs

@@ -25,5 +25,11 @@ module BetterTranslate
     def merge_translations: (String file_path, Hash[String, untyped] new_translations) -> Hash[String, untyped]
 
     def build_output_path: (String target_lang_code) -> String
+
+    private
+
+    def create_backup_file: (String file_path) -> void
+
+    def rotate_backups: (String file_path) -> void
   end
 end

data/sig/better_translate.rbs

@@ -5,6 +5,10 @@
 module BetterTranslate
   type translation_results = { success_count: Integer, failure_count: Integer, errors: Array[Hash[Symbol, untyped]] }
 
+  # Analyzer module for translation file analysis
+  module Analyzer
+  end
+
   # Module-level instance variable (for singleton methods)
   self.@configuration: Configuration?
 

data/sig/csv.rbs

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# CSV library type signatures
+class CSV
+  # Generate CSV string
+  #
+  # @yield CSV instance for writing rows
+  # @return CSV string
+  def self.generate: () { (CSV) -> void } -> String
+
+  # Add row to CSV
+  #
+  # @param row Array of values
+  # @return CSV instance
+  def <<: (Array[untyped]) -> CSV
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: better_translate
 version: !ruby/object:Gem::Version
-  version: 1.0.0.1
+  version: 1.1.1
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-22 00:00:00.000000000 Z
+date: 2025-10-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -36,15 +50,20 @@ files:
 - ".env.example"
 - ".rspec"
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - ".yardopts"
 - CHANGELOG.md
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
 - RELEASE_NOTES_v1.0.0.md
 - Rakefile
+- SECURITY.md
 - Steepfile
+- brakeman.yml
+- codecov.yml
 - docs/implementation/00-overview.md
 - docs/implementation/01-setup_dependencies.md
 - docs/implementation/02-error_handling.md
@@ -61,11 +80,16 @@ files:
 - docs/implementation/12-cli_standalone.md
 - exe/better_translate
 - lib/better_translate.rb
+- lib/better_translate/analyzer/code_scanner.rb
+- lib/better_translate/analyzer/key_scanner.rb
+- lib/better_translate/analyzer/orphan_detector.rb
+- lib/better_translate/analyzer/reporter.rb
 - lib/better_translate/cache.rb
 - lib/better_translate/cli.rb
 - lib/better_translate/configuration.rb
 - lib/better_translate/direct_translator.rb
 - lib/better_translate/errors.rb
+- lib/better_translate/json_handler.rb
 - lib/better_translate/progress_tracker.rb
 - lib/better_translate/provider_factory.rb
 - lib/better_translate/providers/anthropic_provider.rb
@@ -93,13 +117,17 @@ files:
 - lib/generators/better_translate/translate/USAGE
 - lib/generators/better_translate/translate/translate_generator.rb
 - lib/tasks/better_translate.rake
-- regenerate_vcr.rb
 - sig/better_translate.rbs
+- sig/better_translate/analyzer/code_scanner.rbs
+- sig/better_translate/analyzer/key_scanner.rbs
+- sig/better_translate/analyzer/orphan_detector.rbs
+- sig/better_translate/analyzer/reporter.rbs
 - sig/better_translate/cache.rbs
 - sig/better_translate/cli.rbs
 - sig/better_translate/configuration.rbs
 - sig/better_translate/direct_translator.rbs
 - sig/better_translate/errors.rbs
+- sig/better_translate/json_handler.rbs
 - sig/better_translate/progress_tracker.rbs
 - sig/better_translate/provider_factory.rbs
 - sig/better_translate/providers/anthropic_provider.rbs
@@ -118,6 +146,7 @@ files:
 - sig/better_translate/variable_extractor.rbs
 - sig/better_translate/version.rbs
 - sig/better_translate/yaml_handler.rbs
+- sig/csv.rbs
 - sig/faraday.rbs
 - sig/generators/better_translate/analyze/analyze_generator.rbs
 - sig/generators/better_translate/install/install_generator.rbs

data/regenerate_vcr.rb

@@ -1,47 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "dotenv/load"
-require "vcr"
-require "webmock/rspec"
-require_relative "lib/better_translate"
-require "tmpdir"
-
-# Setup VCR
-VCR.configure do |config|
-  config.cassette_library_dir = "spec/vcr_cassettes"
-  config.hook_into :webmock
-  config.filter_sensitive_data("<GEMINI_API_KEY>") { ENV["GEMINI_API_KEY"] }
-  config.default_cassette_options = { record: :all }
-end
-
-test_dir = Dir.mktmpdir("gemini_test")
-puts "Test output dir: #{test_dir}"
-
-VCR.use_cassette("rails/dummy_app_gemini_translation", record: :all) do
-  config = BetterTranslate::Configuration.new
-  config.provider = :gemini
-  config.gemini_key = ENV["GEMINI_API_KEY"]
-  config.source_language = "en"
-  config.target_languages = [{ short_name: "fr", name: "French" }]
-  config.input_file = "spec/dummy/config/locales/en.yml"
-  config.output_folder = test_dir
-  config.cache_enabled = false
-  config.verbose = true
-  config.validate!
-
-  puts "Starting translation..."
-  translator = BetterTranslate::Translator.new(config)
-  results = translator.translate_all
-
-  puts "\nResults: #{results.inspect}"
-  puts "\nFiles created:"
-  Dir.entries(test_dir).each { |f| puts "  - #{f}" unless f.start_with?(".") }
-
-  if results[:success_count].positive?
-    puts "\n✓ Successfully regenerated VCR cassette!"
-  else
-    puts "\n✗ Translation failed"
-  end
-end