better_translate 0.5.0 → 1.0.0

data/lib/better_translate/translator.rb

@@ -1,292 +1,123 @@
+# frozen_string_literal: true
+
 module BetterTranslate
+  # Main translator class
+  #
+  # Coordinates the translation process using configuration, providers,
+  # strategies, and YAML handling.
+  #
+  # @example Basic usage
+  #   config = Configuration.new
+  #   config.provider = :chatgpt
+  #   config.openai_key = ENV['OPENAI_API_KEY']
+  #   config.source_language = "en"
+  #   config.target_languages = [{ short_name: "it", name: "Italian" }]
+  #   config.input_file = "config/locales/en.yml"
+  #   config.output_folder = "config/locales"
+  #
+  #   translator = Translator.new(config)
+  #   results = translator.translate_all
+  #
   class Translator
-    class << self
-      # Main method that orchestrates the translation process.
-      # Reads the source file, applies exclusions, and translates the content
-      # to all configured target languages sequentially.
-      #
-      # @return [void]
-      def work
-        message = "\n[BetterTranslate] Reading source file: #{BetterTranslate.configuration.input_file}\n"
-        BetterTranslate::Utils.logger(message: message)
-
-        translations = read_yml_source
-        message = "[BetterTranslate] Source file loaded successfully."
-        BetterTranslate::Utils.logger(message: message)
-
-        # Removes the keys to exclude (global_exclusions) from the read structure
-        message = "[BetterTranslate] Applying global exclusions..."
-        BetterTranslate::Utils.logger(message: message)
-        global_filtered_translations = remove_exclusions(
-          translations, BetterTranslate.configuration.global_exclusions
-        )
-        message = "[BetterTranslate] Global exclusions applied."
-        BetterTranslate::Utils.logger(message: message)
-
-        start_time = Time.now
-        results = []
-        
-        # Elabora ogni lingua target in sequenza invece di utilizzare thread
-        BetterTranslate.configuration.target_languages.each do |target_lang|
-          # Phase 2: Apply the target language specific filter
-          lang_exclusions = BetterTranslate.configuration.exclusions_per_language[target_lang[:short_name]] || []
-          filtered_translations = remove_exclusions(
-            global_filtered_translations, lang_exclusions
-          )
-
-          message = "Starting translation from #{BetterTranslate.configuration.source_language} to #{target_lang[:short_name]}"
-          BetterTranslate::Utils.logger(message: message)
-          message = "\n[BetterTranslate] Starting translation to #{target_lang[:name]} (#{target_lang[:short_name]})..."
-          BetterTranslate::Utils.logger(message: message)
-          
-          service = BetterTranslate::Service.new
-          translated_data = translate_with_progress(filtered_translations, service, target_lang[:short_name], target_lang[:name])
-          
-          message = "[BetterTranslate] Writing translations for #{target_lang[:short_name]}..."
-          BetterTranslate::Utils.logger(message: message)
-          BetterTranslate::Writer.write_translations(translated_data, target_lang[:short_name])
-          
-          lang_end_time = Time.now
-          duration = lang_end_time - start_time
-          BetterTranslate::Utils.track_metric("translation_duration", duration)
-          
-          message = "Translation completed from #{BetterTranslate.configuration.source_language} to #{target_lang[:short_name]} in #{duration.round(2)} seconds"
-          BetterTranslate::Utils.logger(message: message)
-          message = "[BetterTranslate] Completed translation to #{target_lang[:name]} in #{duration.round(2)} seconds."
-          BetterTranslate::Utils.logger(message: message)
-          
-          results << translated_data
-        end
-      end
-
-      private
-
-      # Reads the YAML file specified in the configuration.
-      # The file path is taken from BetterTranslate.configuration.input_file.
-      #
-      # @return [Hash] The parsed YAML data structure containing the translations
-      # @raise [StandardError] If the input file does not exist or cannot be parsed
-      def read_yml_source
-        file_path = BetterTranslate.configuration.input_file
-        unless File.exist?(file_path)
-          raise "File not found: #{file_path}"
-        end
-
-        YAML.load_file(file_path)
-      end
-
-      # Removes the global keys to exclude from the data structure,
-      # calculating paths starting from the source language content.
-      #
-      # For example, if the YAML file is:
-      #   { "en" => { "sample" => { "valid" => "valid", "excluded" => "Excluded" } } }
-      # and global_exclusions = ["sample.excluded"],
-      # the result will be:
-      #   { "en" => { "sample" => { "valid" => "valid" } } }
-      # Removes specified keys from the translation data structure.
-      # Recursively traverses the data structure and excludes any keys that match the exclusion list.
-      # Keys can be excluded at any nesting level using dot notation paths.
-      #
-      # @param data [Hash, Array, Object] The data structure to filter
-      # @param exclusion_list [Array<String>] List of dot-separated key paths to exclude
-      # @param current_path [Array] The current path in the traversal (used recursively, default: [])
-      # @return [Hash, Array, Object] The filtered data structure with excluded keys removed
-      def remove_exclusions(data, exclusion_list, current_path = [])
-        if data.is_a?(Hash)
-          data.each_with_object({}) do |(key, value), result|
-            # If we are at the top-level and the key matches the source language,
-            # reset the path (to exclude "en" from the final path)
-            new_path = if current_path.empty? && key == BetterTranslate.configuration.source_language
-                         []
-                       else
-                         current_path + [key]
-                       end
-
-            path_string = new_path.join(".")
-            unless exclusion_list.include?(path_string)
-              result[key] = remove_exclusions(value, exclusion_list, new_path)
-            end
-          end
-        elsif data.is_a?(Array)
-          data.map.with_index do |item, index|
-            remove_exclusions(item, exclusion_list, current_path + [index])
-          end
-        else
-          data
-        end
-      end
-
-      # Recursive method that traverses the structure, translating each string and updating progress.
-      #
-      # Recursively translates a data structure by traversing it deeply.
-      # This method is used for smaller datasets (less than 50 strings) and translates each string individually.
-      # It maintains the original structure of the data while replacing string values with their translations.
-      #
-      # @param data [Hash, Array, String] The data structure to translate
-      # @param service [BetterTranslate::Service] The service instance to use for translation
-      # @param target_lang_code [String] The target language code (e.g., 'fr', 'es')
-      # @param target_lang_name [String] The target language name (e.g., 'French', 'Spanish')
-      # @param progress [ProgressBar] A progress bar instance to track translation progress
-      # @return [Hash, Array, String] The translated data structure with the same structure as the input
-      def deep_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
-        if data.is_a?(Hash)
-          data.each_with_object({}) do |(key, value), result|
-            result[key] = deep_translate_with_progress(value, service, target_lang_code, target_lang_name, progress)
-          end
-        elsif data.is_a?(Array)
-          data.map do |item|
-            deep_translate_with_progress(item, service, target_lang_code, target_lang_name, progress)
-          end
-        elsif data.is_a?(String)
-          progress.increment
-          service.translate(data, target_lang_code, target_lang_name)
-        else
-          data
-        end
-      end
-
-      # Translates the entire data structure with progress monitoring.
-      # Automatically selects between batch and deep translation methods based on the number of strings.
-      # For datasets with more than 50 strings, batch processing is used for better performance.
-      #
-      # @param data [Hash, Array, String] The data structure to translate
-      # @param service [BetterTranslate::Service] The service instance to use for translation
-      # @param target_lang_code [String] The target language code (e.g., 'fr', 'es')
-      # @param target_lang_name [String] The target language name (e.g., 'French', 'Spanish')
-      # @return [Hash, Array, String] The translated data structure with the same structure as the input
-      def translate_with_progress(data, service, target_lang_code, target_lang_name)
-        total = count_strings(data)
-        message = "[BetterTranslate] Found #{total} strings to translate to #{target_lang_name}"
-        BetterTranslate::Utils.logger(message: message)
-        
-        # Creiamo la barra di progresso ma aggiungiamo anche output visibile
-        progress = ProgressBar.create(total: total, format: '%a %B %p%% %t')
-
-        start_time = Time.now
-        message = "[BetterTranslate] Using #{total > 50 ? 'batch' : 'deep'} translation method"
-        BetterTranslate::Utils.logger(message: message)
-        
-        result = if total > 50 # Usa il batch processing per dataset grandi
-          batch_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
-        else
-          deep_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
-        end
-
-        duration = Time.now - start_time
-        message = "[BetterTranslate] Translation processing completed in #{duration.round(2)} seconds"
-        BetterTranslate::Utils.logger(message: message)
-        
-        BetterTranslate::Utils.track_metric("translation_method_duration", {
-          method: total > 50 ? 'batch' : 'deep',
-          duration: duration,
-          total_strings: total
-        })
-
-        result
-      end
-
-      # Translates data in batches for improved performance with larger datasets.
-      # This method first extracts all translatable strings, processes them in batches of 10,
-      # and then reinserts the translations back into the original structure.
-      #
-      # @param data [Hash, Array, String] The data structure to translate
-      # @param service [BetterTranslate::Service] The service instance to use for translation
-      # @param target_lang_code [String] The target language code (e.g., 'fr', 'es')
-      # @param target_lang_name [String] The target language name (e.g., 'French', 'Spanish')
-      # @param progress [ProgressBar] A progress bar instance to track translation progress
-      # @return [Hash, Array, String] The translated data structure with the same structure as the input
-      def batch_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
-        texts = extract_translatable_texts(data)
-        translations = {}
-
-        texts.each_slice(10).each_with_index do |batch, index|
-          batch_start = Time.now
-          
-          batch_translations = batch.map do |text|
-            translated = service.translate(text, target_lang_code, target_lang_name)
-            progress.increment
-            [text, translated]
-          end.to_h
-
-          translations.merge!(batch_translations)
-          
-          batch_duration = Time.now - batch_start
-          BetterTranslate::Utils.track_metric("batch_translation_duration", {
-            batch_number: index + 1,
-            size: batch.size,
-            duration: batch_duration
-          })
-        end
-
-        replace_translations(data, translations)
-      end
-
-      # Extracts all unique translatable strings from a data structure.
-      # This is used by the batch translation method to collect all strings for efficient processing.
-      # Only non-empty strings are included in the result.
-      #
-      # @param data [Hash, Array, String] The data structure to extract strings from
-      # @return [Array<String>] An array of unique strings found in the data structure
-      def extract_translatable_texts(data)
-        texts = Set.new
-        traverse_structure(data) do |value|
-          texts.add(value) if value.is_a?(String) && !value.strip.empty?
-        end
-        texts.to_a
-      end
+    # @return [Configuration] Configuration object
+    attr_reader :config
+
+    # Initialize translator
+    #
+    # @param config [Configuration] Configuration object
+    #
+    # @example
+    #   translator = Translator.new(config)
+    #
+    def initialize(config)
+      @config = config
+      @config.validate!
+      provider_name = config.provider || :chatgpt
+      @provider = ProviderFactory.create(provider_name, config)
+      @yaml_handler = YAMLHandler.new(config)
+      @progress_tracker = ProgressTracker.new(enabled: config.verbose)
+    end
 
-      # Replaces strings in the original data structure with their translations.
-      # Used by the batch translation method to reinsert translated strings into the original structure.
-      # Only non-empty strings that have translations in the provided hash are replaced.
-      #
-      # @param data [Hash, Array, String] The original data structure
-      # @param translations [Hash] A hash mapping original strings to their translations
-      # @return [Hash, Array, String] The data structure with strings replaced by translations
-      def replace_translations(data, translations)
-        traverse_structure(data) do |value|
-          if value.is_a?(String) && !value.strip.empty? && translations.key?(value)
-            translations[value]
-          else
-            value
-          end
-        end
+    # Translate to all target languages
+    #
+    # @return [Hash] Results hash with :success_count, :failure_count, :errors
+    #
+    # @example
+    #   results = translator.translate_all
+    #   #=> { success_count: 2, failure_count: 0, errors: [] }
+    #
+    def translate_all
+      source_strings = @yaml_handler.get_source_strings
+
+      # @type var results: translation_results
+      results = {
+        success_count: 0,
+        failure_count: 0,
+        errors: []
+      }
+
+      config.target_languages.each do |lang|
+        translate_language(source_strings, lang)
+        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)
       end
 
-      # Traverses a nested data structure and applies a block to each element.
-      # This is a utility method used by extract_translatable_texts and replace_translations.
-      # Handles Hash, Array, and scalar values recursively.
-      #
-      # @param data [Hash, Array, Object] The data structure to traverse
-      # @yield [Object] Yields each value in the data structure to the block
-      # @return [Hash, Array, Object] The transformed data structure after applying the block
-      def traverse_structure(data, &block)
-        case data
-        when Hash
-          data.transform_values { |v| traverse_structure(v, &block) }
-        when Array
-          data.map { |v| traverse_structure(v, &block) }
-        else
-          yield data
-        end
-      end
+      results
+    end
 
-      # Counts the number of translatable strings in a data structure.
-      # Used to determine the total number of strings for progress tracking and method selection.
-      # Recursively traverses Hash and Array structures, counting each String as 1.
-      #
-      # @param data [Hash, Array, String, Object] The data structure to count strings in
-      # @return [Integer] The total number of strings found in the data structure
-      def count_strings(data)
-        if data.is_a?(Hash)
-          data.values.sum { |v| count_strings(v) }
-        elsif data.is_a?(Array)
-          data.sum { |item| count_strings(item) }
-        elsif data.is_a?(String)
-          1
-        else
-          0
-        end
-      end
+    private
+
+    # Translate to a single language
+    #
+    # @param source_strings [Hash] Source strings (flattened)
+    # @param lang [Hash] Language config with :short_name and :name
+    # @return [void]
+    # @api private
+    #
+    def translate_language(source_strings, lang)
+      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)
+
+      return if strings_to_translate.empty?
+
+      # Select strategy
+      strategy = Strategies::StrategySelector.select(
+        strings_to_translate.size,
+        config,
+        @provider,
+        @progress_tracker
+      )
+
+      # Translate
+      @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)
+
+      final_translations = if config.translation_mode == :incremental
+                             @yaml_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)
+
+      @progress_tracker.complete(target_lang_name, translated.size)
     end
   end
-end
+end

data/lib/better_translate/utils/hash_flattener.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Utility classes and helpers
+  #
+  # Contains various utility classes used throughout BetterTranslate.
+  module Utils
+    # Utilities for flattening and unflattening nested hashes
+    #
+    # Used to convert nested YAML structures to flat key-value pairs
+    # and back again.
+    #
+    # @example Flatten nested hash
+    #   nested = { "user" => { "name" => "John", "age" => 30 } }
+    #   flat = HashFlattener.flatten(nested)
+    #   #=> { "user.name" => "John", "user.age" => 30 }
+    #
+    # @example Unflatten to nested hash
+    #   flat = { "user.name" => "John", "user.age" => 30 }
+    #   HashFlattener.unflatten(flat)
+    #   #=> { "user" => { "name" => "John", "age" => 30 } }
+    #
+    class HashFlattener
+      # Flatten a nested hash to dot-notation keys
+      #
+      # Recursively converts nested hashes into a single-level hash
+      # with keys joined by a separator (default: ".").
+      #
+      # @param hash [Hash] Nested hash to flatten
+      # @param parent_key [String] Parent key prefix (used internally for recursion)
+      # @param separator [String] Key separator (default: ".")
+      # @return [Hash] Flattened hash
+      #
+      # @example Basic flattening
+      #   nested = {
+      #     "config" => {
+      #       "database" => {
+      #         "host" => "localhost"
+      #       }
+      #     }
+      #   }
+      #   HashFlattener.flatten(nested)
+      #   #=> { "config.database.host" => "localhost" }
+      #
+      # @example Custom separator
+      #   HashFlattener.flatten(nested, "", "/")
+      #   #=> { "config/database/host" => "localhost" }
+      #
+      def self.flatten(hash, parent_key = "", separator = ".")
+        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}"
+
+          if value.is_a?(Hash)
+            result.merge!(flatten(value, new_key, separator))
+          else
+            result[new_key] = value
+          end
+        end
+      end
+
+      # Unflatten a hash with dot-notation keys to nested structure
+      #
+      # Converts a flat hash with delimited keys back into a nested
+      # hash structure.
+      #
+      # @param hash [Hash] Flattened hash
+      # @param separator [String] Key separator (default: ".")
+      # @return [Hash] Nested hash
+      #
+      # @example Basic unflattening
+      #   flat = { "config.database.host" => "localhost" }
+      #   HashFlattener.unflatten(flat)
+      #   #=> {
+      #   #     "config" => {
+      #   #       "database" => {
+      #   #         "host" => "localhost"
+      #   #       }
+      #   #     }
+      #   #   }
+      #
+      # @example Custom separator
+      #   flat = { "config/database/host" => "localhost" }
+      #   HashFlattener.unflatten(flat, "/")
+      #   #=> { "config" => { "database" => { "host" => "localhost" } } }
+      #
+      def self.unflatten(hash, separator = ".")
+        initial_hash = {} #: Hash[String, untyped]
+        hash.each_with_object(initial_hash) do |(key, value), result|
+          keys = key.split(separator)
+          last_key = keys.pop
+
+          # Build nested structure
+          nested = keys.reduce(result) do |memo, k|
+            memo[k] ||= {}
+            memo[k]
+          end
+
+          nested[last_key] = value if last_key
+        end
+      end
+    end
+  end
+end

data/lib/better_translate/validator.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Input validation utilities
+  #
+  # Validates language codes, text, paths, and other inputs.
+  #
+  # @example Validate language code
+  #   Validator.validate_language_code!("en")  #=> true
+  #   Validator.validate_language_code!("invalid")  # raises ValidationError
+  #
+  class Validator
+    # Validate a language code
+    #
+    # Language codes must be 2-letter strings (e.g., "en", "it", "fr").
+    #
+    # @param code [String] Language code to validate
+    # @raise [ValidationError] if code is invalid
+    # @return [true] if valid
+    #
+    # @example Valid codes
+    #   Validator.validate_language_code!("en")  #=> true
+    #   Validator.validate_language_code!("IT")  #=> true
+    #
+    # @example Invalid codes
+    #   Validator.validate_language_code!("eng")  # raises ValidationError
+    #   Validator.validate_language_code!(nil)    # raises ValidationError
+    #
+    def self.validate_language_code!(code)
+      raise ValidationError, "Language code cannot be nil" if code.nil?
+      raise ValidationError, "Language code must be a String" unless code.is_a?(String)
+      raise ValidationError, "Language code cannot be empty" if code.empty?
+      raise ValidationError, "Language code must be 2 letters" unless code.match?(/^[a-z]{2}$/i)
+
+      true
+    end
+
+    # Validate text for translation
+    #
+    # Text must be a non-empty string.
+    #
+    # @param text [String] Text to validate
+    # @raise [ValidationError] if text is invalid
+    # @return [true] if valid
+    #
+    # @example Valid text
+    #   Validator.validate_text!("Hello world")  #=> true
+    #
+    # @example Invalid text
+    #   Validator.validate_text!("")      # raises ValidationError
+    #   Validator.validate_text!("   ")   # raises ValidationError
+    #
+    def self.validate_text!(text)
+      raise ValidationError, "Text cannot be nil" if text.nil?
+      raise ValidationError, "Text must be a String" unless text.is_a?(String)
+      raise ValidationError, "Text cannot be empty" if text.strip.empty?
+
+      true
+    end
+
+    # Validate a file path exists
+    #
+    # @param path [String] File path to validate
+    # @raise [FileError] if path is invalid
+    # @return [true] if valid
+    #
+    # @example Valid path
+    #   Validator.validate_file_exists!("config/locales/en.yml")  #=> true
+    #
+    # @example Invalid path
+    #   Validator.validate_file_exists!("/nonexistent/file.yml")  # raises FileError
+    #
+    def self.validate_file_exists!(path)
+      raise FileError, "File path cannot be nil" if path.nil?
+      raise FileError, "File path must be a String" unless path.is_a?(String)
+      raise FileError, "File does not exist: #{path}" unless File.exist?(path)
+
+      true
+    end
+
+    # Validate an API key
+    #
+    # API keys must be non-empty strings.
+    #
+    # @param key [String] API key to validate
+    # @param provider [Symbol] Provider name for error message
+    # @raise [ConfigurationError] if key is invalid
+    # @return [true] if valid
+    #
+    # @example Valid API key
+    #   Validator.validate_api_key!("sk-test123", provider: :chatgpt)  #=> true
+    #
+    # @example Invalid API key
+    #   Validator.validate_api_key!(nil, provider: :chatgpt)  # raises ConfigurationError
+    #   Validator.validate_api_key!("", provider: :gemini)    # raises ConfigurationError
+    #
+    def self.validate_api_key!(key, provider:)
+      raise ConfigurationError, "API key for #{provider} cannot be nil" if key.nil?
+      raise ConfigurationError, "API key for #{provider} must be a String" unless key.is_a?(String)
+      raise ConfigurationError, "API key for #{provider} cannot be empty" if key.strip.empty?
+
+      true
+    end
+  end
+end