better_translate 0.5.0 → 1.0.0

data/lib/better_translate/variable_extractor.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Extracts and preserves interpolation variables during translation
+  #
+  # Supports multiple variable formats:
+  # - Rails I18n: %{name}, %{count}
+  # - I18n.js: {{user}}, {{email}}
+  # - ES6 templates: ${var}
+  # - Simple braces: {name}
+  #
+  # Variables are extracted before translation, replaced with safe placeholders,
+  # and then restored after translation to ensure they remain unchanged.
+  #
+  # @example Basic usage
+  #   extractor = VariableExtractor.new("Hello %{name}, you have {{count}} messages")
+  #   safe_text = extractor.extract
+  #   #=> "Hello __VAR_0__, you have __VAR_1__ messages"
+  #
+  #   translated = translate(safe_text)  # "Ciao __VAR_0__, hai __VAR_1__ messaggi"
+  #   final = extractor.restore(translated)
+  #   #=> "Ciao %{name}, hai {{count}} messaggi"
+  #
+  # @example Variable validation
+  #   extractor = VariableExtractor.new("Total: %{amount}")
+  #   extractor.extract
+  #   extractor.validate_variables!("Totale: %{amount}")  #=> true
+  #   extractor.validate_variables!("Totale:")  # raises ValidationError
+  #
+  class VariableExtractor
+    # Variable patterns to detect and preserve
+    VARIABLE_PATTERNS = {
+      rails_template: /%\{[^}]+\}/, # %{name}, %{count}
+      rails_annotated: /%<[^>]+>[a-z]/i,    # %<name>s, %<count>d
+      i18n_js: /\{\{[^}]+\}\}/,             # {{user}}, {{email}}
+      es6: /\$\{[^}]+\}/,                   # ${var}
+      simple: /\{[a-zA-Z_][a-zA-Z0-9_]*\}/  # {name} but not {1,2,3}
+    }.freeze
+
+    # Combined pattern to match any variable format
+    COMBINED_PATTERN = Regexp.union(*VARIABLE_PATTERNS.values).freeze
+
+    # Placeholder prefix
+    PLACEHOLDER_PREFIX = "__VAR_"
+
+    # Placeholder suffix
+    PLACEHOLDER_SUFFIX = "__"
+
+    # @return [String] Original text with variables
+    attr_reader :original_text
+
+    # @return [Array<String>] Extracted variables in order
+    attr_reader :variables
+
+    # @return [Hash<String, String>] Mapping of placeholders to original variables
+    attr_reader :placeholder_map
+
+    # Initialize extractor with text
+    #
+    # @param text [String] Text containing variables
+    #
+    # @example
+    #   extractor = VariableExtractor.new("Hello %{name}")
+    #
+    def initialize(text)
+      @original_text = text
+      @variables = []
+      @placeholder_map = {}
+      @reverse_map = {}
+    end
+
+    # 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.).
+    #
+    # @return [String] Text with variables replaced by placeholders
+    #
+    # @example
+    #   extractor = VariableExtractor.new("Hello %{name}")
+    #   extractor.extract  #=> "Hello __VAR_0__"
+    #
+    def extract
+      return "" if original_text.nil? || original_text.empty?
+
+      result = original_text.dup
+      index = 0
+
+      # Find and replace all variables
+      result.gsub!(COMBINED_PATTERN) do |match|
+        placeholder = "#{PLACEHOLDER_PREFIX}#{index}#{PLACEHOLDER_SUFFIX}"
+        @variables << match
+        @placeholder_map[placeholder] = match
+        @reverse_map[match] = placeholder
+        index += 1
+        placeholder
+      end
+
+      result
+    end
+
+    # Restore variables from placeholders in translated text
+    #
+    # Replaces all placeholders with their original variable formats.
+    # In strict mode, validates that all original variables are present.
+    #
+    # @param translated_text [String] Translated text with placeholders
+    # @param strict [Boolean] If true, raises error if variables are missing
+    # @return [String] Translated text with original variables restored
+    # @raise [ValidationError] if strict mode and variables are missing
+    #
+    # @example Successful restore
+    #   extractor = VariableExtractor.new("Hello %{name}")
+    #   extractor.extract
+    #   extractor.restore("Ciao __VAR_0__")  #=> "Ciao %{name}"
+    #
+    # @example Strict mode with missing variable
+    #   extractor = VariableExtractor.new("Hello %{name}")
+    #   extractor.extract
+    #   extractor.restore("Ciao", strict: true)  # raises ValidationError
+    #
+    def restore(translated_text, strict: true)
+      return "" if translated_text.nil? || translated_text.empty?
+
+      result = translated_text.dup
+
+      # Restore all placeholders
+      @placeholder_map.each do |placeholder, original_var|
+        result.gsub!(placeholder, original_var)
+      end
+
+      # Validate all variables are present
+      validate_variables!(result) if strict
+
+      result
+    end
+
+    # Check if text contains variables
+    #
+    # @return [Boolean] true if variables are present
+    #
+    # @example
+    #   extractor = VariableExtractor.new("Hello %{name}")
+    #   extractor.extract
+    #   extractor.variables?  #=> true
+    #
+    def variables?
+      !@variables.empty?
+    end
+
+    # Get count of variables
+    #
+    # @return [Integer] Number of variables
+    #
+    # @example
+    #   extractor = VariableExtractor.new("Hi %{name}, {{count}} items")
+    #   extractor.extract
+    #   extractor.variable_count  #=> 2
+    #
+    def variable_count
+      @variables.size
+    end
+
+    # Validate that all original variables are present in text
+    #
+    # Checks that:
+    # 1. All original variables are still present
+    # 2. No unexpected/extra variables have been added
+    #
+    # @param text [String] Text to validate
+    # @raise [ValidationError] if variables are missing or modified
+    # @return [true] if all variables are present
+    #
+    # @example Valid text
+    #   extractor = VariableExtractor.new("Hello %{name}")
+    #   extractor.extract
+    #   extractor.validate_variables!("Ciao %{name}")  #=> true
+    #
+    # @example Missing variable
+    #   extractor = VariableExtractor.new("Hello %{name}")
+    #   extractor.extract
+    #   extractor.validate_variables!("Ciao")  # raises ValidationError
+    #
+    def validate_variables!(text)
+      # @type var missing: Array[String]
+      missing = []
+      # @type var extra: Array[String]
+      extra = []
+
+      # Check for missing variables
+      @variables.each do |var|
+        var_str = var.is_a?(String) ? var : var.to_s
+        missing << var_str unless text.include?(var_str)
+      end
+
+      # Check for extra/unknown variables (potential corruption)
+      found_vars = text.scan(COMBINED_PATTERN)
+      found_vars.each do |var|
+        var_str = var.is_a?(String) ? var : var.to_s
+        extra << var_str unless @variables.include?(var_str)
+      end
+
+      if missing.any? || extra.any?
+        # @type var error_msg: Array[String]
+        error_msg = []
+        error_msg << "Missing variables: #{missing.join(", ")}" if missing.any?
+        error_msg << "Unexpected variables: #{extra.join(", ")}" if extra.any?
+
+        raise ValidationError.new(
+          "Variable validation failed: #{error_msg.join("; ")}",
+          context: {
+            original_variables: @variables,
+            missing: missing,
+            extra: extra,
+            text: text
+          }
+        )
+      end
+
+      true
+    end
+
+    # Extract variables from text without creating instance
+    #
+    # Static method to find all variables in text without needing
+    # to instantiate the extractor.
+    #
+    # @param text [String] Text to analyze
+    # @return [Array<String>] List of variables found
+    #
+    # @example
+    #   VariableExtractor.find_variables("Hi %{name}, {{count}} items")
+    #   #=> ["%{name}", "{{count}}"]
+    #
+    def self.find_variables(text)
+      return [] if text.nil? || text.empty?
+
+      text.scan(COMBINED_PATTERN)
+    end
+
+    # Check if text contains variables
+    #
+    # Static method to quickly check if text contains any supported
+    # variable format.
+    #
+    # @param text [String] Text to check
+    # @return [Boolean] true if variables are present
+    #
+    # @example
+    #   VariableExtractor.contains_variables?("Hello %{name}")  #=> true
+    #   VariableExtractor.contains_variables?("Hello world")    #=> false
+    #
+    def self.contains_variables?(text)
+      return false if text.nil? || text.empty?
+
+      text.match?(COMBINED_PATTERN)
+    end
+  end
+end

data/lib/better_translate/version.rb

@@ -1,13 +1,6 @@
 # frozen_string_literal: true
 
 module BetterTranslate
-  # Current version of the BetterTranslate gem.
-  # 
-  # The versioning follows Semantic Versioning 2.0.0 (https://semver.org/):
-  # - MAJOR version for incompatible API changes
-  # - MINOR version for backwards-compatible functionality additions
-  # - PATCH version for backwards-compatible bug fixes
-  #
-  # @return [String] The current version in the format "MAJOR.MINOR.PATCH"
-  VERSION = "0.5.0"
+  # Current version of BetterTranslate gem
+  VERSION = "1.0.0"
 end

data/lib/better_translate/yaml_handler.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module BetterTranslate
+  # Handles YAML file operations
+  #
+  # Provides methods for:
+  # - Reading and parsing YAML files
+  # - Writing YAML files with proper formatting
+  # - Merging translations (incremental mode)
+  # - Handling exclusions
+  # - Flattening/unflattening nested structures
+  #
+  # @example Reading a YAML file
+  #   handler = YAMLHandler.new(config)
+  #   data = handler.read_yaml("config/locales/en.yml")
+  #
+  # @example Writing translations
+  #   handler.write_yaml("config/locales/it.yml", { "it" => { "greeting" => "Ciao" } })
+  #
+  class YAMLHandler
+    # @return [Configuration] Configuration object
+    attr_reader :config
+
+    # Initialize YAML handler
+    #
+    # @param config [Configuration] Configuration object
+    #
+    # @example
+    #   config = Configuration.new
+    #   handler = YAMLHandler.new(config)
+    #
+    def initialize(config)
+      @config = config
+    end
+
+    # Read and parse YAML file
+    #
+    # @param file_path [String] Path to YAML file
+    # @return [Hash] Parsed YAML content
+    # @raise [FileError] if file cannot be read
+    # @raise [YamlError] if YAML is invalid
+    #
+    # @example
+    #   data = handler.read_yaml("config/locales/en.yml")
+    #   #=> { "en" => { "greeting" => "Hello" } }
+    #
+    def read_yaml(file_path)
+      Validator.validate_file_exists!(file_path)
+
+      content = File.read(file_path)
+      YAML.safe_load(content) || {}
+    rescue Errno::ENOENT => e
+      raise FileError.new("File not found: #{file_path}", context: { error: e.message })
+    rescue Psych::SyntaxError => e
+      raise YamlError.new("Invalid YAML syntax in #{file_path}", context: { error: e.message })
+    end
+
+    # Write hash to YAML 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_yaml("config/locales/it.yml", { "it" => { "greeting" => "Ciao" } })
+    #
+    def write_yaml(file_path, data, diff_preview: nil)
+      summary = nil
+
+      # Show diff preview if in dry run mode
+      if config.dry_run && diff_preview
+        # @type var existing_data: Hash[String, untyped]
+        existing_data = File.exist?(file_path) ? read_yaml(file_path) : {}
+        summary = diff_preview.show_diff(existing_data, data, file_path)
+      end
+
+      return summary if config.dry_run
+
+      # Ensure output directory exists
+      FileUtils.mkdir_p(File.dirname(file_path))
+
+      File.write(file_path, YAML.dump(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 YAML: #{file_path}", context: { error: e.message })
+    end
+
+    # Get translatable strings from source YAML
+    #
+    # 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_yaml(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.yml", new_translations)
+    #
+    def merge_translations(file_path, new_translations)
+      # @type var existing: Hash[String, untyped]
+      existing = File.exist?(file_path) ? read_yaml(file_path) : {}
+      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.yml"
+    #
+    def build_output_path(target_lang_code)
+      return "#{target_lang_code}.yml" unless config.output_folder
+
+      File.join(config.output_folder, "#{target_lang_code}.yml")
+    end
+  end
+end

data/lib/better_translate.rb

@@ -1,99 +1,123 @@
 # frozen_string_literal: true
-require "ruby-progressbar"
 
-require "better_translate/version"
-require "better_translate/utils"
-require "better_translate/translator"
-require "better_translate/service"
-require "better_translate/writer"
-require "better_translate/helper"
-require "better_translate/similarity_analyzer"
+require_relative "better_translate/version"
+require_relative "better_translate/errors"
+require_relative "better_translate/configuration"
+require_relative "better_translate/cache"
+require_relative "better_translate/rate_limiter"
+require_relative "better_translate/validator"
+require_relative "better_translate/variable_extractor"
+require_relative "better_translate/utils/hash_flattener"
+require_relative "better_translate/providers/base_http_provider"
+require_relative "better_translate/providers/chatgpt_provider"
+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/progress_tracker"
+require_relative "better_translate/strategies/base_strategy"
+require_relative "better_translate/strategies/deep_strategy"
+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/cli"
 
-require 'better_translate/providers/base_provider'
-require 'better_translate/providers/chatgpt_provider'
-require 'better_translate/providers/gemini_provider'
+# Load Rails integration if Rails is present
+require_relative "better_translate/railtie" if defined?(Rails::Railtie)
 
-require 'ostruct'
-
-# Main module for the BetterTranslate gem.
-# Provides functionality for translating YAML files using various AI providers.
+# BetterTranslate - AI-powered YAML locale file translator
+#
+# Automatically translate YAML locale files using AI providers (ChatGPT, Gemini, Claude).
+# Features intelligent caching, batch processing, and Rails integration.
 #
-# @example Basic configuration and usage
+# @example Basic usage
 #   BetterTranslate.configure do |config|
 #     config.provider = :chatgpt
 #     config.openai_key = ENV['OPENAI_API_KEY']
-#     config.input_file = 'config/locales/en.yml'
-#     config.target_languages = [{short_name: 'fr', name: 'French'}]
+#     config.source_language = "en"
+#     config.target_languages = [
+#       { short_name: "it", name: "Italian" },
+#       { short_name: "fr", name: "French" }
+#     ]
+#     config.input_file = "config/locales/en.yml"
+#     config.output_folder = "config/locales"
 #   end
-#   
-#   BetterTranslate.magic # Start the translation process
+#
+#   BetterTranslate.translate_files
+#
 module BetterTranslate
   class << self
-    # Configuration object for the gem
-    # @return [OpenStruct] The configuration object
-    attr_accessor :configuration
-
-    # Configures the gem with the provided block.
-    # Sets up the configuration object and yields it to the block.
+    # Configure BetterTranslate
+    #
+    # @yieldparam config [Configuration] Configuration object to modify
+    # @return [Configuration] The configuration object
+    #
+    # @example
+    #   BetterTranslate.configure do |config|
+    #     config.provider = :chatgpt
+    #     config.openai_key = ENV['OPENAI_API_KEY']
+    #     config.source_language = "en"
+    #     config.target_languages = [{ short_name: "it", name: "Italian" }]
+    #   end
     #
-    # @yield [configuration] Yields the configuration object to the block
-    # @yieldparam configuration [OpenStruct] The configuration object
-    # @return [OpenStruct] The updated configuration object
     def configure
-      self.configuration ||= OpenStruct.new
-      yield(configuration) if block_given?
+      yield(configuration)
+      configuration
     end
 
-    # Installs the gem configuration file (initializer) in a Rails application.
-    # Copies the template initializer to the Rails config/initializers directory.
-    # Only works in a Rails environment.
+    # Get current configuration
     #
-    # @return [void]
-    # @note This method will log an error if not called from a Rails application
-    def install
-      unless defined?(Rails) && Rails.respond_to?(:root)
-        message = "The install method is only available in a Rails application."
-        BetterTranslate::Utils.logger(message: message)
-        return
-      end
-
-      # Builds the path to the template folder inside the gem
-      source = File.expand_path("../generators/better_translate/templates/better_translate.rb", __dir__)
-      destination = File.join(Rails.root, "config", "initializers", "better_translate.rb")
+    # @return [Configuration] Current configuration instance
+    #
+    # @example
+    #   config = BetterTranslate.configuration
+    #   config.provider #=> :chatgpt
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
 
-      if File.exist?(destination)
-        message = "The initializer file already exists: #{destination}"
-        BetterTranslate::Utils.logger(message: message)
-      else
-        FileUtils.mkdir_p(File.dirname(destination))
-        FileUtils.cp(source, destination)
-        message = "The initializer file already exists: #{destination}"
-        BetterTranslate::Utils.logger(message: message)
+    # Translate files using current configuration
+    #
+    # @return [Hash] Results with :success_count, :failure_count, :errors
+    # @raise [ConfigurationError] if configuration is invalid or missing
+    #
+    # @example
+    #   results = BetterTranslate.translate_files
+    #   puts "Success: #{results[:success_count]}, Failures: #{results[:failure_count]}"
+    #
+    def translate_files
+      unless @configuration
+        raise ConfigurationError,
+              "BetterTranslate is not configured. Call BetterTranslate.configure first."
       end
+
+      translator = Translator.new(configuration)
+      translator.translate_all
     end
 
-    # Starts the translation process using the configured settings.
-    # This is the main entry point for the translation functionality.
-    # Logs the start and completion of the translation process.
+    # Reset configuration
     #
     # @return [void]
+    #
     # @example
-    #   BetterTranslate.magic
-    def magic
-      message = "Magic method invoked: Translation will begin..."
-      BetterTranslate::Utils.logger(message: message)
-      # Utilizziamo il logger per tutti i messaggi
-      message = "\n[BetterTranslate] Starting translation process...\n"
-      BetterTranslate::Utils.logger(message: message)
-
-      BetterTranslate::Translator.work
-      
-      message = "Magic method invoked: Translation completed successfully!"
-      BetterTranslate::Utils.logger(message: message)
-      # Utilizziamo il logger per tutti i messaggi
-      message = "\n[BetterTranslate] Translation completed successfully!\n"
-      BetterTranslate::Utils.logger(message: message)
+    #   BetterTranslate.reset!
+    #   BetterTranslate.configuration.provider #=> nil
+    #
+    def reset!
+      @configuration = nil
     end
 
+    # Get gem version
+    #
+    # @return [String] Version string
+    #
+    # @example
+    #   BetterTranslate.version #=> "0.1.0"
+    #
+    def version
+      VERSION
+    end
   end
-end
+end

data/lib/generators/better_translate/analyze/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Analyzes YAML locale file structure and provides statistics.
+
+    This will show you:
+    - Total number of translation strings
+    - File structure with nested keys
+    - String counts per section
+
+Example:
+    bin/rails generate better_translate:analyze config/locales/en.yml
+
+    This will analyze the en.yml file and display statistics.