better_translate 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6941ef1c334c2ddbbb7141c8257f8906957fd0b60eadeee867d9a11b83788ae6
-  data.tar.gz: 8678aa23790a06d905592efc1571a91408e58a9f1359e70ee90174d5d2ee8975
+  metadata.gz: 04ce5f4b9e73378af8eec2409688e26dfef6fb42268b8817800c8c3433877eaf
+  data.tar.gz: 0b34308c1ef74dd3ad74b8cbc0b546cf831f2e43c3f3e2628cb636511ab33289
 SHA512:
-  metadata.gz: 548433e5223f37320a42c7ba35644b46470dc89baf42581612753d0542d039e2729cad8dd8bf4fbde1cd962ac970f397fdd1a3d98374f83fbc0380805771daae
-  data.tar.gz: 704eaeb04b49d7f165631443567e89afdff27a30c42893d0d04e424fe340fb113a9a4553ded29c1b4f8e9af36d75eccea0e138d0056c72442f75570340b9fa97
+  metadata.gz: e63e571fa9f0a881c25d35d4cb31f5cfaa0fbed2e84d3847e50f9b6f811685b5a13666408b48f0e61666232916c8cbf803dda11a6e51bcca9813f1e97b696435
+  data.tar.gz: 94f9664d32402395d9a575c2e1ae8f04b29781421fd7a4b266ae7bf0c7a2c21d345ab73762397d50028d01482255b0a10319c4799c25056256c39e0d43269df0

data/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to BetterTranslate will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2025-03-11
+
+### Added
+- Comprehensive YARD-style documentation across the entire codebase:
+  - Added detailed class and method documentation for all core components
+  - Added parameter and return type documentation
+  - Added usage examples for key classes and methods
+  - Improved inline comments for complex logic
+
+### Changed
+- Improved code readability and maintainability through better documentation
+- Enhanced developer experience with clearer API documentation
+
+## [0.4.1] - 2025-03-11
+
+### Fixed
+- Migliorati i test RSpec per garantire maggiore affidabilità:
+  - Corretti gli stub per i provider di traduzione
+  - Migliorata la gestione delle richieste HTTP nei test
+  - Ottimizzati i file YAML temporanei per i test di similarità
+- Risolti problemi di compatibilità con WebMock
+
+### Changed
+- Sostituito l'approccio di stubbing specifico con pattern più flessibili
+- Migliorata la struttura dei test per il SimilarityAnalyzer
+
 ## [0.4.0] - 2025-03-11
 
 ### Added

data/README.md

@@ -15,6 +15,7 @@ BetterTranslate simplifies the translation of YAML files in your Ruby/Rails appl
 - 🧪 Comprehensive test coverage
 - ⚡️ LRU caching for performance
 - 🔍 Translation similarity analysis
+- 📚 Extensive YARD documentation
 
 ## Why BetterTranslate? 🤔
 
@@ -31,6 +32,7 @@ BetterTranslate simplifies the translation of YAML files in your Ruby/Rails appl
   - Comprehensive test suite
   - LRU caching for performance
   - Progress tracking
+  - Detailed YARD documentation
 - 🔍 **Translation Analysis**:
   - Similarity detection
   - Detailed reports
@@ -45,7 +47,7 @@ BetterTranslate simplifies the translation of YAML files in your Ruby/Rails appl
 Add the gem to your Gemfile:
 
 ```ruby
-gem 'better_translate', '~> 0.1.0'
+gem 'better_translate', '~> 0.4.2'
 ```
 
 Then run:

data/lib/better_translate/helper.rb

@@ -1,4 +1,16 @@
 module BetterTranslate
+  # Helper class that provides utility methods for translating text and arrays of text
+  # to multiple target languages using different translation providers.
+  # This class simplifies the process of translating content by abstracting away
+  # the provider-specific implementation details.
+  #
+  # @example Translating a single text to multiple languages
+  #   BetterTranslate::Helper.translate_text_to_languages(
+  #     "Hello world!",
+  #     [{ short_name: "it", name: "Italian" }, { short_name: "fr", name: "French" }],
+  #     "en",
+  #     :chatgpt
+  #   )
   class Helper
     class << self
       # Translates a given text into multiple target languages.

data/lib/better_translate/providers/base_provider.rb

@@ -1,6 +1,21 @@
 module BetterTranslate
   module Providers
+    # Abstract base class for translation providers.
+    # Provides common functionality and defines the interface that all providers must implement.
+    # Handles rate limiting, input validation, and retry logic for failed translations.
+    #
+    # @abstract Subclass and override {#translate_text} to implement a provider
     class BaseProvider
+      # Number of retry attempts for failed translations
+      MAX_RETRIES = 3
+      
+      # Delay in seconds between retry attempts
+      RETRY_DELAY = 2 # seconds
+      
+      # Initializes a new provider instance with the specified API key.
+      #
+      # @param api_key [String] The API key for the translation service
+      # @return [BaseProvider] A new instance of the provider
       def initialize(api_key)
         @api_key = api_key
         @last_request_time = Time.now - 1
@@ -8,25 +23,36 @@ module BetterTranslate
 
       private
 
+      # Implements a simple rate limiting mechanism to prevent overloading the API.
+      # Ensures at least 0.5 seconds between consecutive requests.
+      #
+      # @return [void]
       def rate_limit
         time_since_last_request = Time.now - @last_request_time
         sleep(0.5 - time_since_last_request) if time_since_last_request < 0.5
         @last_request_time = Time.now
       end
 
+      # Validates the input parameters for translation.
+      # Ensures that the text is not empty and the language code is in a valid format.
+      #
+      # @param text [String] The text to translate
+      # @param target_lang_code [String] The target language code (e.g., "en", "fr-FR")
+      # @raise [ArgumentError] If the text is empty or the language code is invalid
+      # @return [void]
       def validate_input(text, target_lang_code)
         raise ArgumentError, "Text cannot be empty" if text.nil? || text.strip.empty?
         raise ArgumentError, "Invalid target language code" unless target_lang_code.match?(/^[a-z]{2}(-[A-Z]{2})?$/)
       end
 
-      # Method to be implemented in derived classes.
-      # @param text [String] text to translate.
-      # @param target_lang_code [String] target language code (e.g. "en").
-      # @param target_lang_name [String] target language name (e.g. "English").
-      # @return [String] testo tradotto.
-      MAX_RETRIES = 3
-      RETRY_DELAY = 2 # seconds
-
+      # Public method to translate text with built-in retry logic.
+      # Attempts to translate the text and retries on failure up to MAX_RETRIES times.
+      #
+      # @param text [String] The text to translate
+      # @param target_lang_code [String] The target language code (e.g., "en")
+      # @param target_lang_name [String] The target language name (e.g., "English")
+      # @return [String] The translated text
+      # @raise [StandardError] If translation fails after all retry attempts
       def translate(text, target_lang_code, target_lang_name)
         retries = 0
         begin
@@ -46,12 +72,28 @@ module BetterTranslate
         end
       end
 
+      # Performs the actual translation process.
+      # Validates input, applies rate limiting, and calls the provider-specific translation method.
+      #
+      # @param text [String] The text to translate
+      # @param target_lang_code [String] The target language code
+      # @param target_lang_name [String] The target language name
+      # @return [String] The translated text
       def perform_translation(text, target_lang_code, target_lang_name)
         validate_input(text, target_lang_code)
         rate_limit
         translate_text(text, target_lang_code, target_lang_name)
       end
 
+      # Provider-specific implementation of the translation logic.
+      # Must be overridden by subclasses to implement the actual translation.
+      #
+      # @abstract
+      # @param text [String] The text to translate
+      # @param target_lang_code [String] The target language code
+      # @param target_lang_name [String] The target language name
+      # @return [String] The translated text
+      # @raise [NotImplementedError] If the method is not overridden by a subclass
       def translate_text(text, target_lang_code, target_lang_name)
         raise NotImplementedError, "The provider #{self.class} must implement the translate_text method"
       end

data/lib/better_translate/providers/chatgpt_provider.rb

@@ -1,7 +1,23 @@
 module BetterTranslate
   module Providers
+    # Translation provider that uses OpenAI's ChatGPT API to perform translations.
+    # Implements the BaseProvider interface with ChatGPT-specific translation logic.
+    # Uses the gpt-3.5-turbo model with a specialized prompt for accurate translations.
+    #
+    # @example
+    #   provider = BetterTranslate::Providers::ChatgptProvider.new(ENV['OPENAI_API_KEY'])
+    #   translated_text = provider.translate("Hello world", "fr", "French")
     class ChatgptProvider < BaseProvider
-      # Uses the OpenAI API to translate the text.
+      # Translates text using the OpenAI ChatGPT API.
+      # Implements the provider-specific translation logic using OpenAI's ChatGPT API.
+      # Sends a carefully crafted prompt to the API to ensure high-quality translations
+      # without explanations or additional text.
+      #
+      # @param text [String] The text to translate
+      # @param target_lang_code [String] The target language code (e.g., "fr")
+      # @param target_lang_name [String] The target language name (e.g., "French")
+      # @return [String] The translated text
+      # @raise [StandardError] If the API request fails or returns an error
       def translate_text(text, target_lang_code, target_lang_name)
         uri = URI("https://api.openai.com/v1/chat/completions")
         headers = {
@@ -13,7 +29,7 @@ module BetterTranslate
         body = {
           model: "gpt-3.5-turbo",
           messages: [
-            { role: "system", content: "You are a professional translator. Translate the following text exactly from #{BetterTranslate.configuration.source_language} to #{target_lang_name} without adding comments, explanations, or alternatives. Provide only the direct translation:" },
+            { role: "system", content: "You are a professional translator. Translate the following text exactly from #{BetterTranslate.configuration.source_language} to #{target_lang_name}. Provide ONLY the direct translation without any explanations, alternatives, or additional text. Do not include the original text. Do not use markdown formatting. Do not add any prefixes or notes. Just return the plain translated text." },
             { role: "user", content: "#{text}" }
           ],
           temperature: 0.3
@@ -30,8 +46,10 @@ module BetterTranslate
           translated_text = json.dig("choices", 0, "message", "content")
           translated_text ? translated_text.strip : text
         else
-          raise "Error during translation with ChatGPT: #{response.body}"
+          raise "Errore HTTP #{response.code}: #{response.body}"
         end
+      rescue StandardError => e
+        raise "Errore durante la traduzione con ChatGPT: #{e.message}"
       end
     end
   end

data/lib/better_translate/providers/gemini_provider.rb

@@ -1,33 +1,74 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
 module BetterTranslate
   module Providers
+    # Translation provider that uses Google's Gemini API to perform translations.
+    # Implements the BaseProvider interface with Gemini-specific translation logic.
+    # Uses the gemini-2.0-flash model with a specialized prompt for accurate translations.
+    #
+    # @example
+    #   provider = BetterTranslate::Providers::GeminiProvider.new(ENV['GOOGLE_GEMINI_KEY'])
+    #   translated_text = provider.translate("Hello world", "fr", "French")
     class GeminiProvider < BaseProvider
-      # Esempio di implementazione per Google Gemini.
-      # Nota: L'endpoint e i parametri sono ipotetici e vanno sostituiti con quelli reali secondo la documentazione ufficiale.
+      # The base URL for the Gemini API
+      # @return [String] The API endpoint URL
+      GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent"
+
+      # Implements the provider-specific translation logic using Google's Gemini API.
+      # Sends a carefully crafted prompt to the API to ensure high-quality translations
+      # without explanations or additional text. Includes minimal text cleaning to handle
+      # any formatting issues in the response.
+      #
+      # @param text [String] The text to translate
+      # @param target_lang_code [String] The target language code (e.g., "fr")
+      # @param target_lang_name [String] The target language name (e.g., "French")
+      # @return [String] The translated text
+      # @raise [StandardError] If the API request fails or returns an error
       def translate_text(text, target_lang_code, target_lang_name)
-        uri = URI("https://gemini.googleapis.com/v1/translate")
-        headers = {
-          "Content-Type"  => "application/json",
-          "Authorization" => "Bearer #{@api_key}"
-        }
+        url = "#{GEMINI_API_URL}?key=#{@api_key}"
+        uri = URI(url)
 
+        headers = { "Content-Type" => "application/json" }
         body = {
-          input_text: text,
-          target_language: target_lang_code,
-          model: "gemini" # oppure altri parametri richiesti dall'API
+          contents: [{
+            parts: [{
+              text: "Translate the following text to #{target_lang_name}. Provide ONLY the direct translation without any explanations, alternatives, or additional text. Do not include the original text. Do not use markdown formatting. Do not add any prefixes or notes. Just return the plain translated text:\n\n#{text}"
+            }]
+          }]
         }
 
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true
-        request = Net::HTTP::Post.new(uri.path, headers)
+        request = Net::HTTP::Post.new(uri.path + "?" + uri.query, headers)
         request.body = body.to_json
 
-        response = http.request(request)
-        if response.is_a?(Net::HTTPSuccess)
-          json = JSON.parse(response.body)
-          translated_text = json["translatedText"]
-          translated_text ? translated_text.strip : text
-        else
-          raise "Errore durante la traduzione con Gemini: #{response.body}"
+        begin
+          response = http.request(request)
+          
+          if response.is_a?(Net::HTTPSuccess)
+            json = JSON.parse(response.body)
+            
+            if json["candidates"]&.any? && json["candidates"][0]["content"]["parts"]&.any?
+              translated_text = json["candidates"][0]["content"]["parts"][0]["text"]
+              
+              # Pulizia minima del testo, dato che il prompt è già specifico
+              cleaned_text = translated_text.strip
+                .gsub(/[\*\`\n"]/, '') # Rimuovi markdown, newline e virgolette
+                .gsub(/\s+/, ' ') # Riduci spazi multipli a uno singolo
+              
+              cleaned_text.empty? ? text : cleaned_text
+            else
+              raise "Risposta Gemini non valida: #{json}"
+            end
+          else
+            raise "Errore HTTP #{response.code}: #{response.body}"
+          end
+        rescue => e
+          raise "Errore durante la traduzione con Gemini: #{e.message}"
         end
       end
     end

data/lib/better_translate/service.rb

@@ -1,14 +1,33 @@
 module BetterTranslate
+  # Service class that handles translation requests using the configured provider.
+  # Implements a Least Recently Used (LRU) cache to avoid redundant translation requests.
+  #
+  # @example
+  #   service = BetterTranslate::Service.new
+  #   translated_text = service.translate("Hello world", "fr", "French")
   class Service
+    # Maximum number of translations to keep in the LRU cache
     MAX_CACHE_SIZE = 1000
 
+    # Initializes a new Service instance.
+    # Sets up the translation provider based on configuration and initializes the LRU cache.
+    #
+    # @return [BetterTranslate::Service] A new Service instance
     def initialize
       @provider_name = BetterTranslate.configuration.provider
       @translation_cache = {}
       @cache_order = []
     end
 
-    # Method to translate a text using the selected provider.
+    # Translates text using the configured provider with caching support.
+    # First checks if the translation is already in the cache. If not, it uses the
+    # provider to translate the text and then caches the result for future use.
+    # Also tracks metrics about the translation request duration.
+    #
+    # @param text [String] The text to translate
+    # @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 [String] The translated text
     def translate(text, target_lang_code, target_lang_name)
       cache_key = "#{text}:#{target_lang_code}"
       
@@ -32,6 +51,11 @@ module BetterTranslate
 
     private
 
+    # Retrieves a translation from the LRU cache if it exists.
+    # Updates the cache order to mark this key as most recently used.
+    #
+    # @param key [String] The cache key in the format "text:target_lang_code"
+    # @return [String, nil] The cached translation or nil if not found
     def cache_get(key)
       if @translation_cache.key?(key)
         # Aggiorna l'ordine LRU
@@ -41,6 +65,12 @@ module BetterTranslate
       end
     end
 
+    # Stores a translation in the LRU cache.
+    # If the cache is full, removes the least recently used item before adding the new one.
+    #
+    # @param key [String] The cache key in the format "text:target_lang_code"
+    # @param value [String] The translated text to cache
+    # @return [String] The value that was cached
     def cache_set(key, value)
       if @translation_cache.size >= MAX_CACHE_SIZE
         # Rimuovi l'elemento meno recentemente usato
@@ -55,6 +85,12 @@ module BetterTranslate
 
 
 
+    # Creates or returns a cached instance of the translation provider.
+    # The provider is determined by the configuration and instantiated with the appropriate API key.
+    # Supports ChatGPT and Gemini providers.
+    #
+    # @return [BetterTranslate::Providers::BaseProvider] An instance of the configured translation provider
+    # @raise [RuntimeError] If the configured provider is not supported
     def provider_instance
       @provider_instance ||= case @provider_name
                              when :chatgpt

data/lib/better_translate/similarity_analyzer.rb

@@ -6,15 +6,37 @@ require "json"
 require "time"
 
 module BetterTranslate
+  # Analyzes translation YAML files to find similar content across keys.
+  # Uses the Levenshtein distance algorithm to identify strings that are similar
+  # but not identical, which could indicate redundant translations.
+  #
+  # @example
+  #   analyzer = BetterTranslate::SimilarityAnalyzer.new(["config/locales/en.yml", "config/locales/fr.yml"])
+  #   analyzer.analyze
   class SimilarityAnalyzer
+    # Default threshold for considering two strings similar (75%)
+    # @return [Float] The similarity threshold as a decimal between 0 and 1
     SIMILARITY_THRESHOLD = 0.75 # Abbassiamo la soglia per trovare più similarità
+    
+    # Default filename for the detailed JSON report
+    # @return [String] The filename for the JSON report
     REPORT_FILE = "translation_similarities.json"
 
+    # Initializes a new SimilarityAnalyzer with the specified YAML files.
+    #
+    # @param yaml_files [Array<String>] An array of paths to YAML translation files
+    # @return [SimilarityAnalyzer] A new instance of the analyzer
     def initialize(yaml_files)
       @yaml_files = yaml_files
       @similarities = {}
     end
 
+    # Performs the complete analysis process:
+    # 1. Loads all translation files
+    # 2. Finds similarities between translations
+    # 3. Generates JSON and text reports
+    #
+    # @return [void]
     def analyze
       translations_by_language = load_translations
       find_similarities(translations_by_language)
@@ -23,6 +45,10 @@ module BetterTranslate
 
     private
 
+    # Loads all YAML translation files specified during initialization.
+    # Parses each file and organizes translations by language code.
+    #
+    # @return [Hash] A hash mapping language codes to their translation data structures
     def load_translations
       translations = {}
       puts "Loading YAML files..."
@@ -36,6 +62,12 @@ module BetterTranslate
       translations
     end
 
+    # Finds similar translations within each language file.
+    # For each language, flattens the translation structure and compares each pair of strings
+    # to identify similarities based on the Levenshtein distance algorithm.
+    #
+    # @param translations_by_language [Hash] A hash mapping language codes to their translation data
+    # @return [void]
     def find_similarities(translations_by_language)
       translations_by_language.each do |lang, translations|
         puts "\nAnalyzing #{lang} translations..."
@@ -62,6 +94,13 @@ module BetterTranslate
       end
     end
 
+    # Flattens a nested translation hash into a single-level hash with dot-notation keys.
+    # For example, {"en" => {"hello" => "world"}} becomes {"en.hello" => "world"}.
+    #
+    # @param hash [Hash] The nested hash to flatten
+    # @param prefix [String] The current key prefix (used recursively)
+    # @param result [Hash] The accumulator for flattened key-value pairs
+    # @return [Hash] A flattened hash with dot-notation keys
     def flatten_translations(hash, prefix = "", result = {})
       hash.each do |key, value|
         current_key = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
@@ -76,6 +115,13 @@ module BetterTranslate
       result
     end
 
+    # Calculates the similarity between two strings using normalized Levenshtein distance.
+    # Returns a value between 0 (completely different) and 1 (identical).
+    # The normalization accounts for the length of the strings.
+    #
+    # @param str1 [String] The first string to compare
+    # @param str2 [String] The second string to compare
+    # @return [Float] A similarity score between 0 and 1
     def calculate_similarity(str1, str2)
       # Implementazione della distanza di Levenshtein normalizzata
       matrix = Array.new(str1.length + 1) { Array.new(str2.length + 1) }
@@ -98,6 +144,16 @@ module BetterTranslate
       1 - (matrix[str1.length][str2.length].to_f / max_length)
     end
 
+    # Records a similarity finding in the internal data structure.
+    # Organizes findings by language and stores all relevant information about the similar strings.
+    #
+    # @param lang [String] The language code
+    # @param key1 [String] The first translation key
+    # @param key2 [String] The second translation key
+    # @param value1 [String] The first translation value
+    # @param value2 [String] The second translation value
+    # @param similarity [Float] The calculated similarity score
+    # @return [void]
     def record_similarity(lang, key1, key2, value1, value2, similarity)
       @similarities[lang] ||= []
       @similarities[lang] << {
@@ -109,6 +165,11 @@ module BetterTranslate
       }
     end
 
+    # Generates both JSON and human-readable reports of the similarity findings.
+    # The JSON report contains detailed information about each similarity found.
+    # The text summary provides a more readable format for quick review.
+    #
+    # @return [void]
     def generate_report
       puts "\nGenerating reports..."
       report = {
@@ -125,6 +186,12 @@ module BetterTranslate
       puts "  - Generated translation_similarities_summary.txt"
     end
 
+    # Generates a human-readable summary of the similarity findings.
+    # Creates a formatted text report organized by language, showing each pair of similar strings
+    # with their keys, values, and similarity percentage.
+    #
+    # @param report [Hash] The complete similarity report data
+    # @return [String] A formatted text summary
     def generate_summary(report)
       summary = ["Translation Similarities Report", "=" * 30, ""]
       

data/lib/better_translate/translator.rb

@@ -1,21 +1,33 @@
 module BetterTranslate
   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 = "Starting file translation..."
+        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
-        threads = BetterTranslate.configuration.target_languages.map do |target_lang|
-          Thread.new do
-
+        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(
@@ -24,26 +36,36 @@ module BetterTranslate
 
           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])
-          end_time = Time.now
-          duration = end_time - start_time
+          
+          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)
-        end
+          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 based on the provided path.
+      # Reads the YAML file specified in the configuration.
+      # The file path is taken from BetterTranslate.configuration.input_file.
       #
-      # @param file_path [String] path of the YAML file to read
-      # @return [Hash] data structure containing the translations
-      # @raise [StandardError] if the file does not exist
+      # @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)
@@ -61,11 +83,14 @@ module BetterTranslate
       # 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 global_exclusions [Array<String>] List of paths (in dot notation) to exclude globally.
-      # @param current_path [Array] The current path (used recursively, default: []).
-      # @return [Hash, Array, Object] The filtered data structure.
+      # @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|
@@ -93,12 +118,16 @@ module BetterTranslate
 
       # Recursive method that traverses the structure, translating each string and updating progress.
       #
-      # @param data [Hash, Array, String] The data structure to translate.
-      # @param provider [Object] The provider that responds to the translate method.
-      # @param target_lang_code [String] Target language code (e.g. "en").
-      # @param target_lang_name [String] Target language name (e.g. "English").
-      # @param progress [Hash] A hash with :count and :total keys to monitor progress.
-      # @return [Hash, Array, String] The translated structure.
+      # 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|
@@ -116,18 +145,27 @@ module BetterTranslate
         end
       end
 
-      # Main method to translate the entire data structure, with progress monitoring.
+      # 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 provider [Object] the provider to use for translation (must implement translate)
-      # @param target_lang_code [String] target language code
-      # @param target_lang_name [String] target language name
-      # @return the translated 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')
+      # @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
@@ -135,6 +173,9 @@ module BetterTranslate
         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,
@@ -144,6 +185,16 @@ module BetterTranslate
         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 = {}
@@ -170,6 +221,12 @@ module BetterTranslate
         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|
@@ -178,6 +235,13 @@ module BetterTranslate
         texts.to_a
       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)
@@ -188,6 +252,13 @@ module BetterTranslate
         end
       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
@@ -199,7 +270,12 @@ module BetterTranslate
         end
       end
 
-      # Recursively counts the number of translatable strings in the data structure.
+      # 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) }

data/lib/better_translate/utils.rb

@@ -1,25 +1,16 @@
 # frozen_string_literal: true
 
-# lib/better_seeder/utils.rb
-#
-# = BetterSeeder::Utils
-#
-# This module provides utility methods for seed management. In particular,
-# allows transforming class names into snake_case format with the "_structure.rb" suffix,
-# manage log messages and configure the logger level for ActiveRecord.
-
 module BetterTranslate
+  # Utility class providing helper methods for logging and metrics tracking.
+  # Used throughout the BetterTranslate gem to standardize logging and performance monitoring.
   class Utils
     class << self
-      ##
-      # Logs a message using the Rails logger if available, otherwise prints it to standard output.
-      #
-      # ==== Parametri
-      # * +message+ - The message to log (can be a string or nil).
-      #
-      # ==== Ritorno
-      # Does not return a significant value.
+      
+      # Logs a message using the Rails logger if available, otherwise prints to standard output.
+      # Provides a consistent logging interface across different environments.
       #
+      # @param message [String, nil] The message to log
+      # @return [void]
       def logger(message: nil)
         if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
           Rails.logger.info message
@@ -28,6 +19,13 @@ module BetterTranslate
         end
       end
 
+      # Tracks a metric with the given name and value.
+      # Stores metrics in memory with timestamps for performance analysis.
+      # Automatically limits each metric type to the most recent 1000 entries.
+      #
+      # @param name [Symbol, String] The name of the metric to track
+      # @param value [Numeric] The value to record for this metric
+      # @return [void]
       def track_metric(name, value)
         @metrics ||= {}
         @metrics[name] ||= []
@@ -37,10 +35,18 @@ module BetterTranslate
         @metrics[name] = @metrics[name].last(1000) if @metrics[name].size > 1000
       end
 
+      # Retrieves all tracked metrics.
+      # Returns a hash where keys are metric names and values are arrays of recorded values with timestamps.
+      #
+      # @return [Hash] The collected metrics or an empty hash if no metrics have been tracked
       def get_metrics
         @metrics || {}
       end
 
+      # Clears all tracked metrics.
+      # Useful for resetting metrics between translation jobs or testing.
+      #
+      # @return [Hash] An empty hash representing the cleared metrics
       def clear_metrics
         @metrics = {}
       end

data/lib/better_translate/version.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
 module BetterTranslate
-  VERSION = "0.4.0"
+  # 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.4.2"
 end

data/lib/better_translate/writer.rb

@@ -1,4 +1,8 @@
 module BetterTranslate
+  # Responsible for writing translated content to YAML files.
+  # Supports both incremental and override translation methods.
+  # Incremental mode preserves existing translations and adds new ones,
+  # while override mode completely replaces the target file.
   class Writer
     class << self
       # Writes the translation file for a target language.
@@ -35,14 +39,19 @@ module BetterTranslate
 
       private
 
-      # Metodo di deep merge: unisce in modo ricorsivo i due hash.
-      # Se una chiave esiste in entrambi gli hash e i valori sono hash, li unisce ricorsivamente.
-      # Otherwise, if the key already exists in the existing hash, it keeps it and doesn't overwrite it.
-      # Se la chiave non esiste, la aggiunge.
+      # Recursively merges two hashes while preserving existing values.
+      # If a key exists in both hashes and the values are hashes, they are merged recursively.
+      # If a key exists in both hashes but the values are not hashes, the existing value is preserved.
+      # If a key only exists in the new hash, it is added to the merged result.
       #
-      # @param existing [Hash] existing hash (current file)
-      # @param new_data [Hash] new hash with translations to merge
-      # @return [Hash] merged hash
+      # @param existing [Hash] The existing hash (current file content)
+      # @param new_data [Hash] The new hash with translations to merge
+      # @return [Hash] The merged hash with preserved existing values
+      # @example
+      #   existing = { "en" => { "hello" => "Hello", "nested" => { "key" => "Value" } } }
+      #   new_data = { "en" => { "hello" => "New Hello", "nested" => { "key2" => "Value2" } } }
+      #   deep_merge(existing, new_data)
+      #   # => { "en" => { "hello" => "Hello", "nested" => { "key" => "Value", "key2" => "Value2" } } }
       def deep_merge(existing, new_data)
         merged = existing.dup
         new_data.each do |key, value|

data/lib/better_translate.rb

@@ -15,17 +15,41 @@ require 'better_translate/providers/gemini_provider'
 
 require 'ostruct'
 
+# Main module for the BetterTranslate gem.
+# Provides functionality for translating YAML files using various AI providers.
+#
+# @example Basic configuration and 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'}]
+#   end
+#   
+#   BetterTranslate.magic # Start the translation process
 module BetterTranslate
   class << self
+    # Configuration object for the gem
+    # @return [OpenStruct] The configuration object
     attr_accessor :configuration
 
-    # Method to configure the gem
+    # Configures the gem with the provided block.
+    # Sets up the configuration object and yields it to the block.
+    #
+    # @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?
     end
 
-    # Install method to generate the configuration file (initializer)
+    # 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.
+    #
+    # @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."
@@ -48,13 +72,27 @@ module BetterTranslate
       end
     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.
+    #
+    # @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)
     end
 
   end

data/lib/generators/better_translate/analyze_generator.rb

@@ -4,9 +4,23 @@ require "rails/generators"
 
 module BetterTranslate
   module Generators
+    # Rails generator for analyzing translation files to find similar content.
+    # Uses the SimilarityAnalyzer to identify potentially redundant translations
+    # across locale files and generates both JSON and human-readable reports.
+    #
+    # @example
+    #   rails generate better_translate:analyze
     class AnalyzeGenerator < Rails::Generators::Base
       desc "Analyze translation files for similarities"
 
+      # Main generator method that analyzes translation files for similarities.
+      # Finds all YAML files in the config/locales directory, runs the analysis,
+      # and displays a summary of the results.
+      #
+      # The analysis uses the Levenshtein distance algorithm to identify strings
+      # that are similar but not identical, which could indicate redundant translations.
+      #
+      # @return [void]
       def analyze_translations
         say "Starting translation similarity analysis...", :blue
 

data/lib/generators/better_translate/translate_generator.rb

@@ -1,16 +1,83 @@
+# frozen_string_literal: true
+
 require 'rails/generators'
 
 module BetterTranslate
   module Generators
+    # Rails generator for executing translations with BetterTranslate.
+    # This generator validates the configuration and starts the translation process.
+    #
+    # @example
+    #   rails generate better_translate:translate
     class TranslateGenerator < Rails::Generators::Base
       desc "Starts the translation process configured in BetterTranslate"
 
-      def run_translation
-        message = "Starting translation with BetterTranslate..."
-        BetterTranslate::Utils.logger(message: message)
-        BetterTranslate.magic
-        message = "Translation completed."
-        BetterTranslate::Utils.logger(message: message)
+      # Main generator method that initiates the translation process.
+      # Validates the configuration before starting and provides status messages.
+      #
+      # @return [void]
+      def translate
+        say "Starting translation with BetterTranslate...", :blue
+        
+        # Verifica che la configurazione sia valida
+        if validate_configuration
+          say "Configuration validated. Starting translation...", :green
+          BetterTranslate.magic
+          say "Translation completed.", :green
+        else
+          say "Translation aborted due to configuration issues.", :red
+        end
+      end
+      
+      private
+      
+      # Validates the BetterTranslate configuration.
+      # Checks for required settings and reports any issues found.
+      #
+      # @return [Boolean] true if the configuration is valid, false otherwise
+      def validate_configuration
+        valid = true
+        
+        # Verifica che il file di input esista
+        unless BetterTranslate.configuration.respond_to?(:input_file)
+          say "Error: input_file not configured. Please check your initializer.", :red
+          return false
+        end
+        
+        input_file = BetterTranslate.configuration.input_file
+        unless File.exist?(input_file)
+          say "Error: Input file not found: #{input_file}", :red
+          valid = false
+        end
+        
+        # Verifica che ci siano lingue target attive
+        if !BetterTranslate.configuration.respond_to?(:target_languages) || 
+           BetterTranslate.configuration.target_languages.empty?
+          say "Error: No target languages configured. Please uncomment or add target languages in your initializer.", :red
+          valid = false
+        end
+        
+        # Verifica che il provider sia configurato
+        if !BetterTranslate.configuration.respond_to?(:provider)
+          say "Error: No provider configured. Please set config.provider in your initializer.", :red
+          valid = false
+        end
+        
+        # Verifica che la chiave API sia configurata per il provider selezionato
+        if BetterTranslate.configuration.respond_to?(:provider)
+          provider = BetterTranslate.configuration.provider
+          if provider == :chatgpt && (!BetterTranslate.configuration.respond_to?(:openai_key) || 
+             BetterTranslate.configuration.openai_key == "YOUR_OPENAI_API_KEY")
+            say "Error: OpenAI API key not configured. Please set config.openai_key in your initializer.", :red
+            valid = false
+          elsif provider == :gemini && (!BetterTranslate.configuration.respond_to?(:google_gemini_key) || 
+                BetterTranslate.configuration.google_gemini_key == "YOUR_GOOGLE_GEMINI_KEY")
+            say "Error: Gemini API key not configured. Please set config.google_gemini_key in your initializer.", :red
+            valid = false
+          end
+        end
+        
+        valid
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_translate
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Alessio Bussolari
@@ -179,19 +179,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.19'
 - !ruby/object:Gem::Dependency
-  name: vcr
+  name: dotenv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '2.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '2.8'
 description: |
   BetterTranslate is a powerful Ruby gem for translating YAML files using AI providers.