better_translate 1.0.0 → 1.1.0

data/lib/better_translate/configuration.rb

@@ -13,6 +13,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 +49,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 +100,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 +131,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,8 +208,14 @@ 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?
+
+      # Only validate input_file exists if using single file mode (not glob pattern or array)
+      return unless input_file && !input_file.empty? && !input_files
       raise ConfigurationError, "Input file does not exist: #{input_file}" unless File.exist?(input_file)
     end
 
@@ -196,6 +234,14 @@ 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
   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) : {}
+        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 = {}
+      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

data/lib/better_translate/providers/anthropic_provider.rb

@@ -4,7 +4,7 @@ module BetterTranslate
   module Providers
     # Anthropic Claude translation provider
     #
-    # Uses claude-3-5-sonnet-20241022 model for high-quality translations.
+    # Uses claude-haiku-4-5 model for fast, efficient translations.
     #
     # @example Basic usage
     #   config = Configuration.new
@@ -18,7 +18,7 @@ module BetterTranslate
       API_URL = "https://api.anthropic.com/v1/messages"
 
       # Model to use for translations
-      MODEL = "claude-3-5-sonnet-20241022"
+      MODEL = "claude-haiku-4-5"
 
       # API version
       API_VERSION = "2023-06-01"
@@ -97,7 +97,8 @@ module BetterTranslate
       #
       def build_system_message(target_lang_name)
         base_message = "You are a professional translator. Translate the following text to #{target_lang_name}. " \
-                       "Return ONLY the translated text, without any explanations or additional text."
+                       "Return ONLY the translated text, without any explanations or additional text. " \
+                       "Words like VARIABLE_0, VARIABLE_1, etc. are placeholders and must be kept unchanged in the translation."
 
         if config.translation_context && !config.translation_context.empty?
           base_message += "\n\nContext: #{config.translation_context}"

data/lib/better_translate/providers/chatgpt_provider.rb

@@ -95,7 +95,8 @@ module BetterTranslate
       #
       def build_system_message(target_lang_name)
         base_message = "You are a professional translator. Translate the following text to #{target_lang_name}. " \
-                       "Return ONLY the translated text, without any explanations or additional text."
+                       "Return ONLY the translated text, without any explanations or additional text. " \
+                       "Words like VARIABLE_0, VARIABLE_1, etc. are placeholders and must be kept unchanged in the translation."
 
         if config.translation_context && !config.translation_context.empty?
           base_message += "\n\nContext: #{config.translation_context}"

data/lib/better_translate/providers/gemini_provider.rb

@@ -4,7 +4,7 @@ module BetterTranslate
   module Providers
     # Google Gemini translation provider
     #
-    # Uses gemini-2.0-flash-exp model for fast, high-quality translations.
+    # Uses gemini-2.5-flash-lite model for fast, high-quality translations.
     #
     # @example Basic usage
     #   config = Configuration.new
@@ -15,10 +15,10 @@ module BetterTranslate
     #
     class GeminiProvider < BaseHttpProvider
       # Google Gemini API endpoint
-      API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent"
+      API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent"
 
       # Model to use for translations
-      MODEL = "gemini-2.0-flash-exp"
+      MODEL = "gemini-2.5-flash-lite"
 
       # Translate a single text
       #
@@ -77,7 +77,8 @@ module BetterTranslate
       #
       def build_prompt(text, target_lang_name)
         base_prompt = "Translate the following text to #{target_lang_name}. " \
-                      "Return ONLY the translated text, without any explanations.\n\n" \
+                      "Return ONLY the translated text, without any explanations. " \
+                      "Words like VARIABLE_0, VARIABLE_1, etc. are placeholders and must be kept unchanged in the translation.\n\n" \
                       "Text: #{text}"
 
         if config.translation_context && !config.translation_context.empty?

data/lib/better_translate/railtie.rb

@@ -11,7 +11,8 @@ module BetterTranslate
   #
   class Railtie < Rails::Railtie
     rake_tasks do
-      rake_file = File.expand_path("../tasks/better_translate.rake", __dir__)
+      dir = __dir__
+      rake_file = File.expand_path("../tasks/better_translate.rake", dir) if dir
       load rake_file if rake_file
     end
   end

data/lib/better_translate/rate_limiter.rb

@@ -52,7 +52,10 @@ module BetterTranslate
       @mutex.synchronize do
         return if @last_request_time.nil?
 
-        elapsed = Time.now - @last_request_time
+        last_time = @last_request_time
+        return unless last_time
+
+        elapsed = Time.now - last_time
         sleep_time = @delay - elapsed.to_f
 
         sleep(sleep_time) if sleep_time.positive?

data/lib/better_translate/strategies/batch_strategy.rb

@@ -37,7 +37,7 @@ module BetterTranslate
           progress_tracker.update(
             language: target_lang_name,
             current_key: "Batch #{batch_index + 1}/#{total_batches}",
-            progress: ((batch_index + 1).to_f / total_batches * 100.0).round(1)
+            progress: ((batch_index + 1).to_f / total_batches * 100.0).round(1).to_f
           )
 
           translated_batch = provider.translate_batch(batch, target_lang_code, target_lang_name)

data/lib/better_translate/strategies/deep_strategy.rb

@@ -32,7 +32,7 @@ module BetterTranslate
           progress_tracker.update(
             language: target_lang_name,
             current_key: key,
-            progress: ((index + 1).to_f / total * 100.0).round(1)
+            progress: ((index + 1).to_f / total * 100.0).round(1).to_f
           )
 
           translated[key] = provider.translate_text(value, target_lang_code, target_lang_name)