better_translate 1.0.0 → 1.1.0

data/lib/better_translate/translator.rb

@@ -34,12 +34,19 @@ module BetterTranslate
       @config.validate!
       provider_name = config.provider || :chatgpt
       @provider = ProviderFactory.create(provider_name, config)
-      @yaml_handler = YAMLHandler.new(config)
+
+      # Resolve input files (supports input_file, input_files array, or glob pattern)
+      @input_files = resolve_input_files
+
+      # We'll determine handler per file during translation
       @progress_tracker = ProgressTracker.new(enabled: config.verbose)
     end
 
     # Translate to all target languages
     #
+    # Uses parallel execution when max_concurrent_requests > 1,
+    # sequential execution otherwise. Supports multiple input files.
+    #
     # @return [Hash] Results hash with :success_count, :failure_count, :errors
     #
     # @example
@@ -47,8 +54,128 @@ module BetterTranslate
     #   #=> { success_count: 2, failure_count: 0, errors: [] }
     #
     def translate_all
-      source_strings = @yaml_handler.get_source_strings
+      # @type var combined_results: translation_results
+      combined_results = {
+        success_count: 0,
+        failure_count: 0,
+        errors: []
+      }
+
+      @input_files.each do |input_file|
+        # Create appropriate handler for this file
+        handler = if input_file.end_with?(".json")
+                    JsonHandler.new(config)
+                  else
+                    YAMLHandler.new(config)
+                  end
+
+        # Temporarily set input_file for this iteration
+        original_input_file = config.input_file
+        config.input_file = input_file
+
+        source_strings = handler.get_source_strings
+
+        results = if config.max_concurrent_requests > 1
+                    translate_parallel(source_strings, handler)
+                  else
+                    translate_sequential(source_strings, handler)
+                  end
+
+        # Restore original config
+        config.input_file = original_input_file
+
+        # Accumulate results
+        combined_results[:success_count] += results[:success_count]
+        combined_results[:failure_count] += results[:failure_count]
+        combined_results[:errors].concat(results[:errors])
+      end
+
+      combined_results
+    end
+
+    private
+
+    # Resolve input files from config
+    #
+    # Handles input_file, input_files array, or glob patterns
+    #
+    # @return [Array<String>] Resolved file paths
+    # @raise [FileError] if no files found
+    # @api private
+    #
+    def resolve_input_files
+      files = if config.input_files
+                # Handle input_files (array or glob pattern)
+                if config.input_files.is_a?(Array)
+                  config.input_files
+                else
+                  # Glob pattern
+                  Dir.glob(config.input_files)
+                end
+              elsif config.input_file
+                # Backward compatibility with single input_file
+                [config.input_file]
+              else
+                []
+              end
+
+      # Validate files exist (unless glob pattern that found nothing)
+      if files.empty?
+        if config.input_files && !config.input_files.is_a?(Array)
+          raise FileError, "No files found matching pattern: #{config.input_files}"
+        end
+
+        raise FileError, "No input files specified"
+
+      end
+
+      files.each do |file|
+        Validator.validate_file_exists!(file)
+      end
+
+      files
+    end
+
+    # Translate languages in parallel
+    #
+    # @param source_strings [Hash] Source strings (flattened)
+    # @param handler [YAMLHandler, JsonHandler] File handler for this file
+    # @return [Hash] Results hash with counts and errors
+    # @api private
+    #
+    def translate_parallel(source_strings, handler)
+      # @type var results: translation_results
+      results = {
+        success_count: 0,
+        failure_count: 0,
+        errors: []
+      }
+      mutex = Mutex.new
+
+      # Process languages in batches of max_concurrent_requests
+      config.target_languages.each_slice(config.max_concurrent_requests) do |batch|
+        threads = batch.map do |lang|
+          Thread.new do
+            translate_language(source_strings, lang, handler)
+            mutex.synchronize { results[:success_count] += 1 }
+          rescue StandardError => e
+            mutex.synchronize { record_error(results, lang, e) }
+          end
+        end
+        threads.each(&:join)
+      end
+
+      results
+    end
 
+    # Translate languages sequentially
+    #
+    # @param source_strings [Hash] Source strings (flattened)
+    # @param handler [YAMLHandler, JsonHandler] File handler for this file
+    # @return [Hash] Results hash with counts and errors
+    # @api private
+    #
+    def translate_sequential(source_strings, handler)
       # @type var results: translation_results
       results = {
         success_count: 0,
@@ -57,38 +184,53 @@ module BetterTranslate
       }
 
       config.target_languages.each do |lang|
-        translate_language(source_strings, lang)
+        translate_language(source_strings, lang, handler)
         results[:success_count] += 1
       rescue StandardError => e
-        results[:failure_count] += 1
-        # @type var error_context: Hash[Symbol, untyped]
-        error_context = e.respond_to?(:context) ? e.context : {}
-        results[:errors] << {
-          language: lang[:name],
-          error: e.message,
-          context: error_context
-        }
-        @progress_tracker.error(lang[:name], e)
+        record_error(results, lang, e)
       end
 
       results
     end
 
-    private
+    # Record translation error in results
+    #
+    # @param results [Hash] Results hash to update
+    # @param lang [Hash] Language config
+    # @param error [StandardError] The error that occurred
+    # @return [void]
+    # @api private
+    #
+    def record_error(results, lang, error)
+      results[:failure_count] += 1
+      # @type var error_context: Hash[Symbol, untyped]
+      error_context = if error.is_a?(BetterTranslate::Error)
+                        error.context
+                      else
+                        {}
+                      end
+      results[:errors] << {
+        language: lang[:name],
+        error: error.message,
+        context: error_context
+      }
+      @progress_tracker.error(lang[:name], error)
+    end
 
     # Translate to a single language
     #
     # @param source_strings [Hash] Source strings (flattened)
     # @param lang [Hash] Language config with :short_name and :name
+    # @param handler [YAMLHandler, JsonHandler] File handler for this file
     # @return [void]
     # @api private
     #
-    def translate_language(source_strings, lang)
+    def translate_language(source_strings, lang, handler)
       target_lang_code = lang[:short_name]
       target_lang_name = lang[:name]
 
       # Filter exclusions
-      strings_to_translate = @yaml_handler.filter_exclusions(source_strings, target_lang_code)
+      strings_to_translate = handler.filter_exclusions(source_strings, target_lang_code)
 
       return if strings_to_translate.empty?
 
@@ -104,20 +246,63 @@ module BetterTranslate
       @progress_tracker.reset
       translated = strategy.translate(strings_to_translate, target_lang_code, target_lang_name)
 
-      # Save
-      output_path = @yaml_handler.build_output_path(target_lang_code)
+      # Save - generate output path with proper filename
+      output_path = build_output_path_for_file(config.input_file, target_lang_code)
 
       final_translations = if config.translation_mode == :incremental
-                             @yaml_handler.merge_translations(output_path, translated)
+                             handler.merge_translations(output_path, translated)
                            else
                              Utils::HashFlattener.unflatten(translated)
                            end
 
       # Wrap in language key (e.g., "it:")
       wrapped = { target_lang_code => final_translations }
-      @yaml_handler.write_yaml(output_path, wrapped)
+
+      # Write using appropriate handler method (write_yaml or write_json)
+      if handler.is_a?(JsonHandler)
+        handler.write_json(output_path, wrapped)
+      else
+        handler.write_yaml(output_path, wrapped)
+      end
 
       @progress_tracker.complete(target_lang_name, translated.size)
     end
+
+    # Build output path for a specific file and language
+    #
+    # Replaces source language code with target language code in filename
+    # and preserves directory structure
+    #
+    # @param input_file [String] Input file path
+    # @param target_lang_code [String] Target language code
+    # @return [String] Output file path
+    # @api private
+    #
+    # @example
+    #   build_output_path_for_file("config/locales/common.en.yml", "it")
+    #   #=> "config/locales/common.it.yml"
+    #
+    def build_output_path_for_file(input_file, target_lang_code)
+      # Get file basename and directory
+      dir = File.dirname(input_file)
+      basename = File.basename(input_file)
+      ext = File.extname(basename)
+      name_without_ext = File.basename(basename, ext)
+
+      # Replace source language code with target language code
+      # Handles patterns like: common.en.yml -> common.it.yml
+      new_basename = name_without_ext.gsub(/\.#{config.source_language}$/, ".#{target_lang_code}") + ext
+
+      # If no language code in filename, use simple pattern
+      new_basename = "#{target_lang_code}#{ext}" if new_basename == basename
+
+      # Build output path
+      if config.output_folder
+        # Use output_folder but preserve relative directory structure if input was nested
+        File.join(config.output_folder, new_basename)
+      else
+        File.join(dir, new_basename)
+      end
+    end
   end
 end

data/lib/better_translate/utils/hash_flattener.rb

@@ -47,7 +47,7 @@ module BetterTranslate
       #   #=> { "config/database/host" => "localhost" }
       #
       def self.flatten(hash, parent_key = "", separator = ".")
-        initial_hash = {} #: Hash[String, untyped]
+        initial_hash = {} # : Hash[String, untyped]
         hash.each_with_object(initial_hash) do |(key, value), result|
           new_key = parent_key.empty? ? key.to_s : "#{parent_key}#{separator}#{key}"
 
@@ -85,7 +85,7 @@ module BetterTranslate
       #   #=> { "config" => { "database" => { "host" => "localhost" } } }
       #
       def self.unflatten(hash, separator = ".")
-        initial_hash = {} #: Hash[String, untyped]
+        initial_hash = {} # : Hash[String, untyped]
         hash.each_with_object(initial_hash) do |(key, value), result|
           keys = key.split(separator)
           last_key = keys.pop

data/lib/better_translate/variable_extractor.rb

@@ -15,9 +15,9 @@ module BetterTranslate
   # @example Basic usage
   #   extractor = VariableExtractor.new("Hello %{name}, you have {{count}} messages")
   #   safe_text = extractor.extract
-  #   #=> "Hello __VAR_0__, you have __VAR_1__ messages"
+  #   #=> "Hello VARIABLE_0, you have VARIABLE_1 messages"
   #
-  #   translated = translate(safe_text)  # "Ciao __VAR_0__, hai __VAR_1__ messaggi"
+  #   translated = translate(safe_text)  # "Ciao VARIABLE_0, hai VARIABLE_1 messaggi"
   #   final = extractor.restore(translated)
   #   #=> "Ciao %{name}, hai {{count}} messaggi"
   #
@@ -41,10 +41,10 @@ module BetterTranslate
     COMBINED_PATTERN = Regexp.union(*VARIABLE_PATTERNS.values).freeze
 
     # Placeholder prefix
-    PLACEHOLDER_PREFIX = "__VAR_"
+    PLACEHOLDER_PREFIX = "VARIABLE_"
 
     # Placeholder suffix
-    PLACEHOLDER_SUFFIX = "__"
+    PLACEHOLDER_SUFFIX = ""
 
     # @return [String] Original text with variables
     attr_reader :original_text
@@ -72,13 +72,13 @@ module BetterTranslate
     # Extract variables and replace with placeholders
     #
     # Scans the text for all supported variable formats and replaces them
-    # with numbered placeholders (__VAR_0__, __VAR_1__, etc.).
+    # with numbered placeholders (VARIABLE_0, VARIABLE_1, etc.).
     #
     # @return [String] Text with variables replaced by placeholders
     #
     # @example
     #   extractor = VariableExtractor.new("Hello %{name}")
-    #   extractor.extract  #=> "Hello __VAR_0__"
+    #   extractor.extract  #=> "Hello VARIABLE_0"
     #
     def extract
       return "" if original_text.nil? || original_text.empty?
@@ -112,7 +112,7 @@ module BetterTranslate
     # @example Successful restore
     #   extractor = VariableExtractor.new("Hello %{name}")
     #   extractor.extract
-    #   extractor.restore("Ciao __VAR_0__")  #=> "Ciao %{name}"
+    #   extractor.restore("Ciao VARIABLE_0")  #=> "Ciao %{name}"
     #
     # @example Strict mode with missing variable
     #   extractor = VariableExtractor.new("Hello %{name}")

data/lib/better_translate/version.rb

@@ -2,5 +2,5 @@
 
 module BetterTranslate
   # Current version of BetterTranslate gem
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/better_translate/yaml_handler.rb

@@ -81,6 +81,9 @@ module BetterTranslate
 
       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))
 
@@ -164,5 +167,61 @@ module BetterTranslate
 
       File.join(config.output_folder, "#{target_lang_code}.yml")
     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
+    #
+    # Rotation strategy:
+    # - .bak is always the most recent
+    # - .bak.1, .bak.2, etc. are progressively older
+    # - When we reach max_backups, oldest is deleted
+    #
+    # @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
+      # max_backups includes .bak itself, so numbered backups go from 1 to max_backups-1
+      # After rotation, .bak -> .bak.1, so we can have at most .bak.1 through .bak.(max_backups-1)
+      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
+      # max_backups=2: nothing to rotate (only .bak -> .bak.1)
+      # max_backups=3: .bak.1 -> .bak.2 (if exists)
+      (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

data/lib/better_translate.rb

@@ -14,6 +14,7 @@ require_relative "better_translate/providers/gemini_provider"
 require_relative "better_translate/providers/anthropic_provider"
 require_relative "better_translate/provider_factory"
 require_relative "better_translate/yaml_handler"
+require_relative "better_translate/json_handler"
 require_relative "better_translate/progress_tracker"
 require_relative "better_translate/strategies/base_strategy"
 require_relative "better_translate/strategies/deep_strategy"
@@ -21,6 +22,10 @@ require_relative "better_translate/strategies/batch_strategy"
 require_relative "better_translate/strategies/strategy_selector"
 require_relative "better_translate/translator"
 require_relative "better_translate/direct_translator"
+require_relative "better_translate/analyzer/key_scanner"
+require_relative "better_translate/analyzer/code_scanner"
+require_relative "better_translate/analyzer/orphan_detector"
+require_relative "better_translate/analyzer/reporter"
 require_relative "better_translate/cli"
 
 # Load Rails integration if Rails is present

data/lib/generators/better_translate/analyze/analyze_generator.rb

@@ -12,7 +12,8 @@ module BetterTranslate
     #   rails generate better_translate:analyze config/locales/en.yml
     #
     class AnalyzeGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
+      dir = __dir__
+      source_root File.expand_path("templates", dir) if dir
 
       desc "Analyze YAML locale file structure and statistics"
 

data/lib/generators/better_translate/install/install_generator.rb

@@ -12,7 +12,8 @@ module BetterTranslate
     #   rails generate better_translate:install
     #
     class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
+      dir = __dir__
+      source_root File.expand_path("templates", dir) if dir
 
       desc "Creates BetterTranslate initializer and config files"
 
@@ -46,8 +47,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,

data/lib/generators/better_translate/install/templates/initializer.rb.tt

@@ -14,15 +14,47 @@ BetterTranslate.configure do |config|
   config.anthropic_key = ENV["ANTHROPIC_API_KEY"]
 
   # Source and target languages
-  config.source_language = "en"
-  config.target_languages = [
-    { short_name: "it", name: "Italian" },
-    { short_name: "es", name: "Spanish" },
-    { short_name: "fr", name: "French" }
-  ]
+  # Automatically uses Rails I18n configuration
+  # To configure I18n in your Rails app, set in config/application.rb:
+  #   config.i18n.default_locale = :it
+  #   config.i18n.available_locales = [:it, :en, :es, :fr]
+  config.source_language = I18n.default_locale.to_s
+
+  # Target languages: automatically derived from I18n.available_locales
+  # Excludes the source language from targets
+  available_targets = (I18n.available_locales - [I18n.default_locale]).map(&:to_s)
+
+  # Language name mapping for common languages
+  language_names = {
+    "en" => "English", "it" => "Italian", "es" => "Spanish", "fr" => "French",
+    "de" => "German", "pt" => "Portuguese", "ru" => "Russian", "zh" => "Chinese",
+    "ja" => "Japanese", "ko" => "Korean", "ar" => "Arabic", "nl" => "Dutch",
+    "pl" => "Polish", "tr" => "Turkish", "sv" => "Swedish", "da" => "Danish",
+    "fi" => "Finnish", "no" => "Norwegian", "cs" => "Czech", "el" => "Greek",
+    "he" => "Hebrew", "hi" => "Hindi", "th" => "Thai", "vi" => "Vietnamese"
+  }
+
+  if available_targets.any?
+    # Use I18n available locales
+    config.target_languages = available_targets.map do |locale|
+      {
+        short_name: locale,
+        name: language_names[locale] || locale.capitalize
+      }
+    end
+  else
+    # Fallback: suggest common languages
+    # Uncomment and modify the languages you want to translate to
+    config.target_languages = [
+      { short_name: "it", name: "Italian" },
+      { short_name: "es", name: "Spanish" },
+      { short_name: "fr", name: "French" }
+    ]
+  end
 
   # File paths
-  config.input_file = Rails.root.join("config", "locales", "en.yml").to_s
+  # Uses source_language for input file
+  config.input_file = Rails.root.join("config", "locales", "#{config.source_language}.yml").to_s
   config.output_folder = Rails.root.join("config", "locales").to_s
 
   # Options

data/lib/generators/better_translate/translate/translate_generator.rb

@@ -15,7 +15,8 @@ module BetterTranslate
     #   rails generate better_translate:translate --dry-run
     #
     class TranslateGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
+      dir = __dir__
+      source_root File.expand_path("templates", dir) if dir
 
       desc "Run BetterTranslate translation task"
 

data/regenerate_vcr.rb

@@ -0,0 +1,47 @@
+#!/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

data/sig/better_translate/configuration.rbs

@@ -27,12 +27,20 @@ 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?
     attr_accessor google_gemini_key: String?
-    attr_accessor gemini_key: String?
-    attr_accessor anthropic_key: String?
+    attr_accessor claude_key: String?
+
+    # Aliases (these are methods created by alias in configuration.rb)
+    alias gemini_key google_gemini_key
+    alias gemini_key= google_gemini_key=
+    alias anthropic_key claude_key
+    alias anthropic_key= claude_key=
     attr_accessor source_language: String?
     attr_accessor target_languages: Array[target_language]
     attr_accessor input_file: String?
@@ -51,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/providers/base_http_provider.rbs

@@ -36,7 +36,7 @@ module BetterTranslate
 
       def http_client: () -> Faraday::Connection
 
-      def with_cache: [T] (String cache_key) { () -> T } -> T
+      def with_cache: (String cache_key) { () -> String } -> String
 
       def build_cache_key: (String text, String target_lang_code) -> String
     end

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