better_translate 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf5e2fea9a6f6702124591e888a922072386b7dc3eca153008828448eae45357
-  data.tar.gz: 5c11456be0bda2b86ea385235a769d405af58233c096d306f710d451eecf6f2a
+  metadata.gz: '08c6af60f2eb66076d7f9fe0e603d13ae497f637380fba4a261961d570097312'
+  data.tar.gz: 7973a4254e17ae0a714e7fea96124916ffd27539e1610ef9ad1409627854af3b
 SHA512:
-  metadata.gz: 8ca97b7c5796b961e80de8a3247aecaf7e781965dfed89197977be2fc59326f8800d6a4b82ed91fbff592c82958b23088e09493d50c42f82458a697628a2a607
-  data.tar.gz: 6404f6b92fa55708db6127ade139d6f3f12170ef5c6617553ccbe383be3cb0971d31b2f956b9ac1bf0f8b4bc65bc46f702f55be13cc49cfc11541af319c72811
+  metadata.gz: 0bee7264dfe205b313a3326602c81590cda09ab283fc6a98145452c14c8d4ef4f756f1a2cfae6836c88a8fb9240f35549b7a8dc4ffdeb782d7fcfbc34d738bb0
+  data.tar.gz: ac9dc01081105b202448ac4dd0cec510b8f7bff7eb72426a009650a756cd9ff74ca97b2916fa569f14569f9963d3ce0798f7dadbfc1b7411e51ea975b645dd0a

data/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.5.0] - 2025-03-12
+
+### Added
+- Custom Translation Provider support:
+  - New generator: `rails generate better_translate:provider YourProviderName`
+  - Provider registration system via `BetterTranslate::Service.register_provider`
+  - Dynamic API key configuration for custom providers
+  - Comprehensive documentation and examples for creating custom providers
+  - Template files with implementation instructions
+- Enhanced Service class:
+  - Provider registry for managing custom providers
+  - Improved error handling with better error messages
+  - Method to list all available providers
+- Updated documentation:
+  - New section in README for custom providers
+  - Step-by-step guide for implementing custom translation services
+  - Example implementation for DeepL integration
+
+## [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

data/README.md

@@ -15,10 +15,11 @@ 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? 🤔
 
-- 🌐 **AI-Powered Translation**: Leverage ChatGPT and Google Gemini for high-quality translations
+- 🌐 **AI-Powered Translation**: Leverage ChatGPT, Google Gemini, and custom providers for high-quality translations
 - 🔄 **Smart Translation Modes**:
   - `Override`: Full file rewrite
   - `Incremental`: Update only new/modified keys
@@ -28,9 +29,11 @@ BetterTranslate simplifies the translation of YAML files in your Ruby/Rails appl
   - Dot notation support
 - 🛠 **Developer-Friendly**:
   - Rails generators included
+  - Custom provider support
   - Comprehensive test suite
   - LRU caching for performance
   - Progress tracking
+  - Detailed YARD documentation
 - 🔍 **Translation Analysis**:
   - Similarity detection
   - Detailed reports
@@ -45,7 +48,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.5.0'
 ```
 
 Then run:
@@ -157,6 +160,12 @@ The gem includes generators to simplify tasks:
   rails generate better_translate:analyze
   ```
 
+- **Create Custom Provider:**
+
+  ```bash
+  rails generate better_translate:provider YourProviderName
+  ```
+
   The `better_translate:analyze` generator will:
   - Scan all YAML files in your locales directory
   - Find similar translations using Levenshtein distance
@@ -170,6 +179,76 @@ The gem includes generators to simplify tasks:
   - Optimize your translation files
   - Reduce translation costs
 
+### Custom Translation Providers
+
+BetterTranslate allows you to create and use custom translation providers, enabling integration with any translation API or service. This feature is particularly useful if you want to use a translation service not natively supported by BetterTranslate, such as DeepL, Microsoft Translator, Amazon Translate, or any other API-based translation service.
+
+1. **Generate a custom provider template:**
+
+   ```bash
+   rails generate better_translate:provider DeepL
+   ```
+
+   This creates a new provider class in `app/providers/deep_l_provider.rb` and a README with implementation instructions.
+
+2. **Implement the translation logic:**
+
+   Edit the generated provider file to implement the `translate_text` method with your API-specific code:
+
+   ```ruby
+   # app/providers/deep_l_provider.rb
+   module Providers
+     class DeepLProvider < BetterTranslate::Providers::BaseProvider
+       def initialize(api_key)
+         @api_key = api_key
+       end
+
+       def translate_text(text, target_lang_code, target_lang_name)
+         # Implement your API call to DeepL here
+         # Return the translated text as a string
+       end
+     end
+   end
+   ```
+
+3. **Register your provider:**
+
+   Create an initializer to register your custom provider:
+
+   ```ruby
+   # config/initializers/better_translate_providers.rb
+   # Require the provider file to ensure it's loaded
+   require Rails.root.join('app', 'providers', 'deep_l_provider')
+   
+   BetterTranslate::Service.register_provider(
+     :deepl,
+     ->(api_key) { Providers::DeepLProvider.new(api_key) }
+   )
+   ```
+   
+   Note: The `require` statement is important to ensure the provider class is loaded before it's used.
+
+4. **Update your configuration:**
+
+   Add your API key to the BetterTranslate configuration:
+
+   ```ruby
+   # config/initializers/better_translate.rb
+   BetterTranslate.configure do |config|
+     config.provider = :deepl
+     config.deepl_key = ENV['DEEPL_API_KEY']
+     # ... other configuration
+   end
+   ```
+
+5. **Use your custom provider:**
+
+   Your custom provider will now be used when you call `BetterTranslate.magic` or any other translation method.
+
+6. **Troubleshooting:**
+
+   If you encounter a `NameError` related to the `Providers` module, make sure the provider file is properly required in your initializer as shown in step 3. The `require` statement ensures that the provider class is loaded before it's used.
+
 ### Translation Helpers
 
 BetterTranslate provides helper methods to simplify translation tasks.

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 = {

data/lib/better_translate/providers/gemini_provider.rb

@@ -6,9 +6,28 @@ 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
+      # 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)
         url = "#{GEMINI_API_URL}?key=#{@api_key}"
         uri = URI(url)

data/lib/better_translate/service.rb

@@ -1,37 +1,66 @@
 module BetterTranslate
+  # Service class that handles translation requests using the configured provider.
+  # Implements a Least Recently Used (LRU) cache to avoid redundant translation requests.
+  # Supports built-in providers (ChatGPT, Gemini) and custom providers registered via
+  # the register_provider class method.
+  #
+  # @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
 
+    # Registry for custom providers
+    @@provider_registry = {}
+
+    # 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}"
-      
+
       # Prova a recuperare dalla cache
       cached = cache_get(cache_key)
       return cached if cached
-      
+
       # Traduci e salva in cache
       start_time = Time.now
       result = provider_instance.translate_text(text, target_lang_code, target_lang_name)
       duration = Time.now - start_time
-      
+
       BetterTranslate::Utils.track_metric("translation_request_duration", {
         provider: @provider_name,
         text_length: text.length,
         duration: duration
       })
-      
+
       cache_set(cache_key, result)
     end
 
     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,13 +70,19 @@ 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
         oldest_key = @cache_order.shift
         @translation_cache.delete(oldest_key)
       end
-      
+
       @translation_cache[key] = value
       @cache_order.push(key)
       value
@@ -55,15 +90,55 @@ 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 built-in providers (ChatGPT, Gemini) and custom providers registered via
+    # the register_provider class method.
+    #
+    # @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
                                Providers::ChatgptProvider.new(BetterTranslate.configuration.openai_key)
                              when :gemini
-                               Providers::GeminiProvider.new(BetterTranslate.configuration.gemini_key)
+                               Providers::GeminiProvider.new(BetterTranslate.configuration.google_gemini_key)
                              else
-                               raise "Provider non supportato: #{@provider_name}"
+                               if @@provider_registry.key?(@provider_name)
+                                 # Get the API key from configuration dynamically
+                                 api_key_method = "#{@provider_name}_key".to_sym
+                                 if BetterTranslate.configuration.respond_to?(api_key_method)
+                                   api_key = BetterTranslate.configuration.send(api_key_method)
+                                   @@provider_registry[@provider_name].call(api_key)
+                                 else
+                                   raise "API key configuration missing for provider: #{@provider_name}. Add config.#{@provider_name}_key to your BetterTranslate configuration."
+                                 end
+                               else
+                                 raise "Provider not supported: #{@provider_name}. Available providers: #{available_providers.join(', ')}"
+                               end
                              end
     end
+
+    # Returns a list of all available provider names
+    # @return [Array<Symbol>] List of available provider names
+    def available_providers
+      [:chatgpt, :gemini] + @@provider_registry.keys
+    end
+
+    # Registers a custom provider for use with BetterTranslate
+    # 
+    # @param name [Symbol] The name of the provider to register
+    # @param factory [Proc] A proc that takes an API key and returns a provider instance
+    # @return [Symbol] The name of the registered provider
+    # 
+    # @example Register a custom DeepL provider
+    #   BetterTranslate::Service.register_provider(
+    #     :deepl,
+    #     ->(api_key) { Providers::DeepLProvider.new(api_key) }
+    #   )
+    def self.register_provider(name, factory)
+      @@provider_registry[name] = factory
+      name
+    end
   end
 end

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.1"
+  # 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"
 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/templates/better_translate.rb

@@ -1,5 +1,5 @@
 BetterTranslate.configure do |config|
-  # Choose the provider to use: :chatgpt or :gemini
+  # Choose the provider to use: :chatgpt, :gemini, or any custom provider registered with BetterTranslate::Service.register_provider
   config.provider = :chatgpt
 
   # API key for OpenAI
@@ -7,6 +7,13 @@ BetterTranslate.configure do |config|
 
   # API key for Google Gemini
   config.google_gemini_key = ENV.fetch("GOOGLE_GEMINI_KEY") { "YOUR_GOOGLE_GEMINI_KEY" }
+  
+  # Custom provider API keys
+  # If you've created a custom provider using 'rails generate better_translate:provider YourProvider',
+  # add its API key here following the naming convention: config.your_provider_key
+  # 
+  # Example for a custom DeepL provider:
+  # config.deepl_key = ENV.fetch("DEEPL_API_KEY") { "YOUR_DEEPL_API_KEY" }
 
   # Source language (for example "en" if the source file is in English)
   config.source_language = "en"

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.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Alessio Bussolari