better_translate 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1110968d8e49f85d5231775f9c05fcbca610021a33723999c75246b687f56b77
-  data.tar.gz: 255e51ff5e5105ebf314b703d9aa841c66eaa6b0ffb5ca1f631ea2cbe81ab6db
+  metadata.gz: a2ff034a6db3498226ddff2111cf66e94a371f65741f82986b6ec8324daaf2dc
+  data.tar.gz: 991a78781adfc647d789729f385bca6e7688a6269bf102e0bff8b40b7bf8aca7
 SHA512:
-  metadata.gz: b971940521bce1ad359990e13fe7d17a339f9d5e62fe5ea9b565fe1ffbd51fe2c2dd24789cd02b7e838a20a3ae88de919ed529adf325b3c11d7377c6bced68e5
-  data.tar.gz: 1d8d785607ba4439df35ceb70b0c302ba1944bfdd74e197d2686cbe7781cfab55bfc93ed7a2affa9ef50b5fc1a459034b1d3cdf6f60420cb2df1b0252d5e3ac5
+  metadata.gz: 68f06a1006c8fc3e43184485d8f71ec9b080649fa68e2f8c5563d55b20c356b501a20a308f0c00f967b5387ac8d3f62abf11d837ca25b325a646658bf8126146
+  data.tar.gz: 719cb1a9bb0217934ca0ecacd455bcc6c81afab081fbc43d24b8add5a50eb33b7947ab715a37938460d162fdcf88e9e629b8cc18d08e1f47ecec085101c35e8c

data/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+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.3.1] - 2025-03-11
+
+### Added
+- Comprehensive RSpec test suite covering:
+  - Core translation functionality
+  - LRU cache implementation
+  - Provider selection and initialization
+  - Error handling
+  - Configuration management
+- Improved documentation with badges and testing information
+
+### Changed
+- Made `translate` method public in `Service` class for better testability
+- Reorganized README.md with better structure and modern layout
+
+## [0.3.0] - 2025-03-11
+
+### Added
+- New translation helper methods:
+  - `translate_text_to_languages`: Translate single text to multiple languages
+  - `translate_texts_to_languages`: Translate multiple texts to multiple languages
+- LRU caching for improved performance
+
+### Changed
+- Enhanced error handling in translation providers
+- Improved method documentation
+
+## [0.2.0] - 2025-03-11
+
+### Added
+- Two-step filtering process:
+  - Global exclusions using `global_exclusions`
+  - Language-specific exclusions using `exclusions_per_language`
+
+### Changed
+- Improved filtering logic to handle language-specific exclusions independently
+- Enhanced documentation for exclusion configuration
+
+### Fixed
+- Issue with language-specific exclusions affecting global filtering
+
+## [0.1.1] - 2025-03-10
+
+### Added
+- New Rails generator: `rails generate better_translate:translate`
+  - Triggers translation process
+  - Displays progress messages
+  - Integrates with existing configuration
+
+## [0.1.0] - 2025-03-10
+
+### Added
+- Initial release with core features:
+  - YAML file translation from source to multiple target languages
+  - Multiple provider support (ChatGPT and Google Gemini)
+  - Progress tracking with ruby-progressbar
+  - Centralized configuration via initializer
+  - Two translation modes: override and incremental
+  - Key exclusion system
+  - Rails integration
+
+### Configuration
+- API key management for providers
+- Source and target language settings
+- Output folder configuration
+- Translation mode selection
+- Exclusion patterns support

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/README.md

@@ -1,30 +1,39 @@
-# BetterTranslate
-
-BetterTranslate is a Ruby gem that enables you to translate YAML files from a source language into one or more target languages using translation providers such as ChatGPT (OpenAI) and Google Gemini. The gem supports two translation modes:
-
-- **Override**: Completely rewrites the translated file.
-- **Incremental**: Updates the translated file only with new or modified keys while keeping the existing ones.
-
-Configuration is centralized via an initializer (for example, in a Rails app), where you can set API keys, the source language, target languages, key exclusions, the output folder, and the translation mode. Additionally, BetterTranslate integrates progress tracking using the [ruby-progressbar](https://github.com/jfelchner/ruby-progressbar) gem.
-
-## Features
-
-- **Multi-language YAML Translation**: Translates YAML files from a source language into one or more target languages.
-- **Multiple Providers**: Supports ChatGPT (OpenAI) and Google Gemini (with potential for extension to other providers in the future).
-- **Translation Modes**: 
-  - **Override**: Rewrites the file from scratch.
-  - **Incremental**: Updates only missing or modified keys.
-- **Centralized Configuration**: Configured via an initializer with settings for API keys, source language, target languages, exclusions (using dot notation), and the output folder.
-- **Two-Step Exclusion Filtering**: 
-  - **Global Exclusions**: Removes keys defined in `global_exclusions` from the entire YAML structure.
-  - **Language-Specific Exclusions**: Applies additional filtering using the `exclusions_per_language` map for each target language.
-- **Progress Bar**: Displays translation progress using ruby-progressbar.
-- **Rails Generators**: 
-  - `rails generate better_translate:install` to generate the initializer.
-  - `rails generate better_translate:translate` to trigger the translation process directly from your Rails app.
-- **Translation Helpers**: 
-  - `translate_text_to_languages` for translating a single text into multiple target languages.
-  - `translate_texts_to_languages` for translating an array of texts into multiple target languages.
+# BetterTranslate 🌍
+
+[![Gem Version](https://badge.fury.io/rb/better_translate.svg)](https://badge.fury.io/rb/better_translate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+
+> 🚀 A powerful Ruby gem for seamless YAML file translations using AI providers like ChatGPT and Google Gemini
+
+BetterTranslate simplifies the translation of YAML files in your Ruby/Rails applications by leveraging advanced AI models. With support for both ChatGPT (OpenAI) and Google Gemini, it offers:
+
+✨ **Key Features**
+- 🔄 Smart translation modes (Override/Incremental)
+- 🎯 Precise key exclusion control
+- 📊 Real-time progress tracking
+- 🧪 Comprehensive test coverage
+- ⚡️ LRU caching for performance
+
+## Why BetterTranslate? 🤔
+
+- 🌐 **AI-Powered Translation**: Leverage ChatGPT and Google Gemini for high-quality translations
+- 🔄 **Smart Translation Modes**:
+  - `Override`: Full file rewrite
+  - `Incremental`: Update only new/modified keys
+- 🎯 **Precise Control**:
+  - Global key exclusions
+  - Language-specific exclusions
+  - Dot notation support
+- 🛠 **Developer-Friendly**:
+  - Rails generators included
+  - Comprehensive test suite
+  - LRU caching for performance
+  - Progress tracking
+- 🔧 **Flexible Helpers**:
+  - Single text translation
+  - Bulk text translation
+  - Multiple target languages support
 
 ## Installation
 
@@ -194,11 +203,38 @@ puts translated_texts
 # }
 ```
 
-## Contact & Feature Requests
+## Testing 🧪
 
-For suggestions, bug reports, or to request new features, please reach out via email at: **alessio.bussolari@pandev.it**.
+BetterTranslate comes with a comprehensive test suite using RSpec. To run the tests:
 
-## Conclusions
+```bash
+bundle exec rspec
+```
+
+The test suite covers:
+- Core translation functionality
+- Cache implementation (LRU)
+- Provider selection and initialization
+- Error handling
+- Configuration management
+
+## Contributing 🤝
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Contact & Support 📬
+
+- **Email**: alessio.bussolari@pandev.it
+- **Issues**: [GitHub Issues](https://github.com/alessiobussolari/better_translate/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/alessiobussolari/better_translate/discussions)
+
+## License 📄
+
+This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
 
 BetterTranslate aims to simplify the translation of YAML files in Ruby projects by providing a flexible, configurable, and extensible system. Whether you need a complete file rewrite or an incremental update, BetterTranslate streamlines the translation process using advanced providers like ChatGPT and Google Gemini. Contributions, feedback, and feature requests are highly encouraged to help improve the gem further.
 

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/better_translate/helper.rb

@@ -68,8 +68,4 @@ module BetterTranslate
       end
     end
   end
-end
-
-__END__
-
-translated = BetterTranslate::Helper.translate_text_to_languages("Hello world!",[{ short_name: "it", name: "Italian" }, { short_name: "fr", name: "French" }],"en",:chatgpt)
+end

data/lib/better_translate/providers/base_provider.rb

@@ -3,15 +3,57 @@ module BetterTranslate
     class BaseProvider
       def initialize(api_key)
         @api_key = api_key
+        @last_request_time = Time.now - 1
       end
 
-      # Metodo da implementare nelle classi derivate.
-      # @param text [String] testo da tradurre.
-      # @param target_lang_code [String] codice della lingua di destinazione (es. "en").
-      # @param target_lang_name [String] nome della lingua di destinazione (es. "English").
+      private
+
+      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
+
+      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
+
       def translate(text, target_lang_code, target_lang_name)
-        raise NotImplementedError, "Il provider #{self.class} deve implementare il metodo translate"
+        retries = 0
+        begin
+          perform_translation(text, target_lang_code, target_lang_name)
+        rescue StandardError => e
+          retries += 1
+          if retries <= MAX_RETRIES
+            message = "Translation attempt #{retries} failed. Retrying in #{RETRY_DELAY} seconds..."
+            BetterTranslate::Utils.logger(message: message)
+            sleep(RETRY_DELAY)
+            retry
+          else
+            message = "Translation failed after #{MAX_RETRIES} attempts: #{e.message}"
+            BetterTranslate::Utils.logger(message: message)
+            raise
+          end
+        end
+      end
+
+      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
+
+      def translate_text(text, target_lang_code, target_lang_name)
+        raise NotImplementedError, "The provider #{self.class} must implement the translate_text method"
       end
     end
   end

data/lib/better_translate/providers/chatgpt_provider.rb

@@ -1,19 +1,19 @@
 module BetterTranslate
   module Providers
     class ChatgptProvider < BaseProvider
-      # Utilizza l'API di OpenAI per tradurre il testo.
-      def translate(text, target_lang_code, target_lang_name)
+      # Uses the OpenAI API to translate the text.
+      def translate_text(text, target_lang_code, target_lang_name)
         uri = URI("https://api.openai.com/v1/chat/completions")
         headers = {
           "Content-Type"  => "application/json",
           "Authorization" => "Bearer #{@api_key}"
         }
 
-        # Costruiamo il prompt per tradurre il testo.
+        # Build the prompt to translate the text.
         body = {
           model: "gpt-3.5-turbo",
           messages: [
-            { role: "system", content: "Sei un traduttore professionale. Traduci esattamente il seguente testo da #{BetterTranslate.configuration.source_language} a #{target_lang_name} senza aggiungere commenti, spiegazioni o alternative. Fornisci solamente la traduzione diretta:" },
+            { 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: "user", content: "#{text}" }
           ],
           temperature: 0.3
@@ -30,7 +30,7 @@ module BetterTranslate
           translated_text = json.dig("choices", 0, "message", "content")
           translated_text ? translated_text.strip : text
         else
-          raise "Errore durante la traduzione con ChatGPT: #{response.body}"
+          raise "Error during translation with ChatGPT: #{response.body}"
         end
       end
     end

data/lib/better_translate/providers/gemini_provider.rb

@@ -3,7 +3,7 @@ module BetterTranslate
     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.
-      def translate(text, target_lang_code, target_lang_name)
+      def translate_text(text, target_lang_code, target_lang_name)
         uri = URI("https://gemini.googleapis.com/v1/translate")
         headers = {
           "Content-Type"  => "application/json",

data/lib/better_translate/service.rb

@@ -1,16 +1,60 @@
 module BetterTranslate
   class Service
+    MAX_CACHE_SIZE = 1000
+
     def initialize
       @provider_name = BetterTranslate.configuration.provider
+      @translation_cache = {}
+      @cache_order = []
     end
 
-    # Metodo per tradurre un testo utilizzando il provider selezionato.
+    # Method to translate a text using the selected provider.
     def translate(text, target_lang_code, target_lang_name)
-      provider_instance.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
 
+    def cache_get(key)
+      if @translation_cache.key?(key)
+        # Aggiorna l'ordine LRU
+        @cache_order.delete(key)
+        @cache_order.push(key)
+        @translation_cache[key]
+      end
+    end
+
+    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
+    end
+
+
+
     def provider_instance
       @provider_instance ||= case @provider_name
                              when :chatgpt

data/lib/better_translate/translator.rb

@@ -2,65 +2,75 @@ module BetterTranslate
   class Translator
     class << self
       def work
-        puts "Avvio della traduzione dei file..."
+        message = "Starting file translation..."
+        BetterTranslate::Utils.logger(message: message)
 
         translations = read_yml_source
 
-        # Rimuove le chiavi da escludere (global_exclusions) dalla struttura letta
+        # Removes the keys to exclude (global_exclusions) from the read structure
         global_filtered_translations = remove_exclusions(
           translations, BetterTranslate.configuration.global_exclusions
         )
 
-        BetterTranslate.configuration.target_languages.each do |target_lang|
+        start_time = Time.now
+        threads = BetterTranslate.configuration.target_languages.map do |target_lang|
+          Thread.new do
 
-          # Fase 2: Applica il filtro specifico per la lingua target
+          # Phase 2: Apply the target language specific filter
           lang_exclusions = BetterTranslate.configuration.exclusions_per_language[target_lang[:short_name]] || []
           filtered_translations = remove_exclusions(
             global_filtered_translations, lang_exclusions
           )
 
-          puts "Inizio traduzione da #{BetterTranslate.configuration.source_language} a #{target_lang[:short_name]}"
+          message = "Starting translation from #{BetterTranslate.configuration.source_language} to #{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])
           BetterTranslate::Writer.write_translations(translated_data, target_lang[:short_name])
-          puts "Traduzione completata da #{BetterTranslate.configuration.source_language} a #{target_lang[:short_name]}"
+          end_time = Time.now
+          duration = 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
         end
       end
 
       private
 
-      # Legge il file YAML in base al percorso fornito.
+      # Reads the YAML file based on the provided path.
       #
-      # @param file_path [String] percorso del file YAML da leggere
-      # @return [Hash] struttura dati contenente le traduzioni
-      # @raise [StandardError] se il file non esiste
+      # @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
       def read_yml_source
         file_path = BetterTranslate.configuration.input_file
         unless File.exist?(file_path)
-          raise "File non trovato: #{file_path}"
+          raise "File not found: #{file_path}"
         end
 
         YAML.load_file(file_path)
       end
 
-      # Rimuove le chiavi globali da escludere dalla struttura dati,
-      # calcolando i percorsi a partire dal contenuto della lingua di partenza.
+      # Removes the global keys to exclude from the data structure,
+      # calculating paths starting from the source language content.
       #
-      # Ad esempio, se il file YAML è:
+      # For example, if the YAML file is:
       #   { "en" => { "sample" => { "valid" => "valid", "excluded" => "Excluded" } } }
-      # e global_exclusions = ["sample.excluded"],
-      # il risultato sarà:
+      # and global_exclusions = ["sample.excluded"],
+      # the result will be:
       #   { "en" => { "sample" => { "valid" => "valid" } } }
       #
-      # @param data [Hash, Array, Object] La struttura dati da filtrare.
-      # @param global_exclusions [Array<String>] Lista dei percorsi (in dot notation) da escludere globalmente.
-      # @param current_path [Array] Il percorso corrente (usato in maniera ricorsiva, default: []).
-      # @return [Hash, Array, Object] La struttura dati filtrata.
+      # @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.
       def remove_exclusions(data, exclusion_list, current_path = [])
         if data.is_a?(Hash)
           data.each_with_object({}) do |(key, value), result|
-            # Se siamo al livello top-level e la chiave corrisponde alla lingua di partenza,
-            # resettare il percorso (così da escludere "en" dal percorso finale)
+            # If we are at the top-level and the key matches the source language,
+            # reset the path (to exclude "en" from the final path)
             new_path = if current_path.empty? && key == BetterTranslate.configuration.source_language
                          []
                        else
@@ -81,14 +91,14 @@ module BetterTranslate
         end
       end
 
-      # Metodo ricorsivo che percorre la struttura, traducendo ogni stringa e aggiornando il progresso.
+      # Recursive method that traverses the structure, translating each string and updating progress.
       #
-      # @param data [Hash, Array, String] La struttura dati da tradurre.
-      # @param provider [Object] Il provider che risponde al metodo translate.
-      # @param target_lang_code [String] Codice della lingua target (es. "en").
-      # @param target_lang_name [String] Nome della lingua target (es. "English").
-      # @param progress [Hash] Un hash con le chiavi :count e :total per monitorare il progresso.
-      # @return [Hash, Array, String] La struttura tradotta.
+      # @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.
       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|
@@ -106,20 +116,90 @@ module BetterTranslate
         end
       end
 
-      # Metodo principale per tradurre l'intera struttura dati, con monitoraggio del progresso.
+      # Main method to translate the entire data structure, with progress monitoring.
       #
-      # @param data [Hash, Array, String] la struttura dati da tradurre
-      # @param provider [Object] il provider da usare per tradurre (deve implementare translate)
-      # @param target_lang_code [String] codice della lingua target
-      # @param target_lang_name [String] nome della lingua target
-      # @return la struttura tradotta
+      # @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
       def translate_with_progress(data, service, target_lang_code, target_lang_name)
         total = count_strings(data)
         progress = ProgressBar.create(total: total, format: '%a %B %p%% %t')
-        deep_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
+
+        start_time = Time.now
+        result = if total > 50 # Usa il batch processing per dataset grandi
+          batch_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
+        else
+          deep_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
+        end
+
+        duration = Time.now - start_time
+        BetterTranslate::Utils.track_metric("translation_method_duration", {
+          method: total > 50 ? 'batch' : 'deep',
+          duration: duration,
+          total_strings: total
+        })
+
+        result
+      end
+
+      def batch_translate_with_progress(data, service, target_lang_code, target_lang_name, progress)
+        texts = extract_translatable_texts(data)
+        translations = {}
+
+        texts.each_slice(10).each_with_index do |batch, index|
+          batch_start = Time.now
+          
+          batch_translations = batch.map do |text|
+            translated = service.translate(text, target_lang_code, target_lang_name)
+            progress.increment
+            [text, translated]
+          end.to_h
+
+          translations.merge!(batch_translations)
+          
+          batch_duration = Time.now - batch_start
+          BetterTranslate::Utils.track_metric("batch_translation_duration", {
+            batch_number: index + 1,
+            size: batch.size,
+            duration: batch_duration
+          })
+        end
+
+        replace_translations(data, translations)
+      end
+
+      def extract_translatable_texts(data)
+        texts = Set.new
+        traverse_structure(data) do |value|
+          texts.add(value) if value.is_a?(String) && !value.strip.empty?
+        end
+        texts.to_a
+      end
+
+      def replace_translations(data, translations)
+        traverse_structure(data) do |value|
+          if value.is_a?(String) && !value.strip.empty? && translations.key?(value)
+            translations[value]
+          else
+            value
+          end
+        end
+      end
+
+      def traverse_structure(data, &block)
+        case data
+        when Hash
+          data.transform_values { |v| traverse_structure(v, &block) }
+        when Array
+          data.map { |v| traverse_structure(v, &block) }
+        else
+          yield data
+        end
       end
 
-      # Conta ricorsivamente il numero di stringhe traducibili nella struttura dati.
+      # Recursively counts the number of translatable strings 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

@@ -4,21 +4,21 @@
 #
 # = BetterSeeder::Utils
 #
-# Questo modulo fornisce metodi di utilità per la gestione dei seed. In particolare,
-# consente di trasformare i nomi delle classi in formato snake_case con il suffisso "_structure.rb",
-# gestire i messaggi di log e configurare il livello del logger per ActiveRecord.
+# 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
   class Utils
     class << self
       ##
-      # Registra un messaggio usando il logger di Rails se disponibile, altrimenti lo stampa su standard output.
+      # Logs a message using the Rails logger if available, otherwise prints it to standard output.
       #
       # ==== Parametri
-      # * +message+ - Il messaggio da loggare (può essere una stringa o nil).
+      # * +message+ - The message to log (can be a string or nil).
       #
       # ==== Ritorno
-      # Non ritorna un valore significativo.
+      # Does not return a significant value.
       #
       def logger(message: nil)
         if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
@@ -27,6 +27,23 @@ module BetterTranslate
           puts message
         end
       end
+
+      def track_metric(name, value)
+        @metrics ||= {}
+        @metrics[name] ||= []
+        @metrics[name] << { value: value, timestamp: Time.now }
+
+        # Mantieni solo le ultime 1000 metriche per tipo
+        @metrics[name] = @metrics[name].last(1000) if @metrics[name].size > 1000
+      end
+
+      def get_metrics
+        @metrics || {}
+      end
+
+      def clear_metrics
+        @metrics = {}
+      end
     end
   end
 end

data/lib/better_translate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BetterTranslate
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/better_translate/writer.rb

@@ -1,19 +1,19 @@
 module BetterTranslate
   class Writer
     class << self
-      # Scrive il file di traduzione per una lingua target.
-      # Se il metodo di traduzione è :override, il file viene riscritto da zero;
-      # se è :incremental, il file esistente viene aggiornato inserendo le nuove traduzioni nelle posizioni corrette.
+      # Writes the translation file for a target language.
+      # If the translation method is :override, the file is rewritten from scratch;
+      # if it's :incremental, the existing file is updated by inserting new translations in the correct positions.
       #
-      # @param translated_data [Hash] La struttura dati tradotta (ad es. { "sample" => { "valid" => "tradotto", "new_key" => "nuova traduzione" } }).
-      # @param target_lang_code [String] Codice della lingua target (es. "ru").
+      # @param translated_data [Hash] The translated data structure (e.g. { "sample" => { "valid" => "translated", "new_key" => "new translation" } }).
+      # @param target_lang_code [String] Target language code (e.g. "ru").
       def write_translations(translated_data, target_lang_code)
         output_folder = BetterTranslate.configuration.output_folder
         output_file = File.join(output_folder, "#{target_lang_code}.yml")
 
-        # Riformatta la struttura per utilizzare il codice target come chiave principale.
+        # Reformats the structure to use the target code as the main key.
         output_content = if translated_data.is_a?(Hash) && translated_data.key?(BetterTranslate.configuration.source_language)
-                           # Sostituisce la chiave della lingua di partenza con quella target.
+                           # Replaces the source language key with the target one.
                            { target_lang_code => translated_data[BetterTranslate.configuration.source_language] }
                          else
                            { target_lang_code => translated_data }
@@ -23,11 +23,13 @@ module BetterTranslate
           existing_data = YAML.load_file(output_file)
           merged = deep_merge(existing_data, output_content)
           File.write(output_file, merged.to_yaml(line_width: -1))
-          puts "File aggiornato in modalità incremental: #{output_file}"
+          message = "File updated in incremental mode: #{output_file}"
+          BetterTranslate::Utils.logger(message: message)
         else
           FileUtils.mkdir_p(output_folder) unless Dir.exist?(output_folder)
           File.write(output_file, output_content.to_yaml(line_width: -1))
-          puts "File riscritto in modalità override: #{output_file}"
+          message = "File rewritten in override mode: #{output_file}"
+          BetterTranslate::Utils.logger(message: message)
         end
       end
 
@@ -35,12 +37,12 @@ module BetterTranslate
 
       # 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.
-      # Altrimenti, se la chiave esiste già nell'hash esistente, la mantiene e non la sovrascrive.
+      # 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.
       #
-      # @param existing [Hash] hash esistente (file corrente)
-      # @param new_data [Hash] nuovo hash con le traduzioni da unire
-      # @return [Hash] hash unito
+      # @param existing [Hash] existing hash (current file)
+      # @param new_data [Hash] new hash with translations to merge
+      # @return [Hash] merged hash
       def deep_merge(existing, new_data)
         merged = existing.dup
         new_data.each do |key, value|
@@ -48,8 +50,8 @@ module BetterTranslate
             if merged[key].is_a?(Hash) && value.is_a?(Hash)
               merged[key] = deep_merge(merged[key], value)
             else
-              # Se la chiave esiste già, non sovrascrivo il valore (modalità incrementale)
-              # oppure potresti decidere di aggiornare comunque, a seconda delle esigenze.
+              # If the key already exists, don't overwrite the value (incremental mode)
+              # or you might decide to update anyway, depending on the requirements.
               merged[key] = merged[key]
             end
           else

data/lib/better_translate.rb

@@ -12,45 +12,47 @@ require 'better_translate/providers/base_provider'
 require 'better_translate/providers/chatgpt_provider'
 require 'better_translate/providers/gemini_provider'
 
+require 'ostruct'
+
 module BetterTranslate
   class << self
     attr_accessor :configuration
 
-    # Metodo per configurare la gemma
+    # Method to configure the gem
     def configure
       self.configuration ||= OpenStruct.new
       yield(configuration) if block_given?
     end
 
-    # Metodo install per generare il file di configurazione (initializer)
+    # Install method to generate the configuration file (initializer)
     def install
       unless defined?(Rails) && Rails.respond_to?(:root)
-        message = "Il metodo install è disponibile solo in un'applicazione Rails."
+        message = "The install method is only available in a Rails application."
         BetterTranslate::Utils.logger(message: message)
         return
       end
 
-      # Costruisce il percorso della cartella template all'interno della gemma
+      # Builds the path to the template folder inside the gem
       source = File.expand_path("../generators/better_translate/templates/better_translate.rb", __dir__)
       destination = File.join(Rails.root, "config", "initializers", "better_translate.rb")
 
       if File.exist?(destination)
-        message = "Il file initializer esiste già: #{destination}"
+        message = "The initializer file already exists: #{destination}"
         BetterTranslate::Utils.logger(message: message)
       else
         FileUtils.mkdir_p(File.dirname(destination))
         FileUtils.cp(source, destination)
-        message = "Il file initializer esiste già: #{destination}"
+        message = "The initializer file already exists: #{destination}"
         BetterTranslate::Utils.logger(message: message)
       end
     end
 
     def magic
-      message = "Metodo magic invocato: eseguirò la traduzione dei file..."
+      message = "Magic method invoked: Translation will begin..."
       BetterTranslate::Utils.logger(message: message)
 
       BetterTranslate::Translator.work
-      message = "Metodo magic invocato: Traduzione completata con successo!"
+      message = "Magic method invoked: Translation completed successfully!"
       BetterTranslate::Utils.logger(message: message)
     end
 

data/lib/generators/better_translate/install_generator.rb

@@ -4,7 +4,7 @@ module BetterTranslate
   module Generators
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
-      desc "Genera il file config/initializers/better_translate.rb con la configurazione di default"
+      desc "Generates the config/initializers/better_translate.rb file with default configuration"
 
       def copy_initializer
         template "better_translate.rb", "config/initializers/better_translate.rb"

data/lib/generators/better_translate/templates/better_translate.rb

@@ -1,17 +1,17 @@
 BetterTranslate.configure do |config|
-  # Scegli il provider da utilizzare: :chatgpt oppure :gemini
+  # Choose the provider to use: :chatgpt or :gemini
   config.provider = :chatgpt
 
-  # API key per OpenAI
+  # API key for OpenAI
   config.openai_key = ENV.fetch("OPENAI_API_KEY") { "YOUR_OPENAI_API_KEY" }
 
-  # API key per Google Gemini
+  # API key for Google Gemini
   config.google_gemini_key = ENV.fetch("GOOGLE_GEMINI_KEY") { "YOUR_GOOGLE_GEMINI_KEY" }
 
-  # Lingua sorgente (ad esempio "en" se il file sorgente è in inglese)
+  # Source language (for example "en" if the source file is in English)
   config.source_language = "en"
 
-  # Lista delle lingue target (short_name e name)
+  # List of target languages (short_name and name)
   config.target_languages = [
     # { short_name: 'es', name: 'spagnolo' },
     # { short_name: 'it', name: 'italiano' },
@@ -21,12 +21,12 @@ BetterTranslate.configure do |config|
     { short_name: "ru", name: "russian" }
   ]
 
-  # Esclusioni globali (percorsi in dot notation) da escludere per tutte le lingue
+  # Global exclusions (paths in dot notation) to exclude for all languages
   config.global_exclusions = [
     "key.value"
   ]
 
-  # Esclusioni specifiche per lingua
+  # Language-specific exclusions
   config.exclusions_per_language = {
     "es" => [],
     "it" => [],
@@ -36,14 +36,14 @@ BetterTranslate.configure do |config|
     "ru" => []
   }
 
-  # Percorso del file di input (ad es. en.yml)
+  # Input file path (e.g. en.yml)
   config.input_file = Rails.root.join("config", "locales", "en.yml").to_s
 
-  # Cartella di output dove verranno salvati i file tradotti
+  # Output folder where translated files will be saved
   config.output_folder = Rails.root.join("config", "locales", "translated").to_s
 
-  # Metodo di traduzione:
-  # - :override => rigenera tutte le traduzioni
-  # - :incremental => aggiorna solo le chiavi mancanti (o quelle che hanno subito modifiche)
+  # Translation method:
+  # - :override => regenerates all translations
+  # - :incremental => updates only missing keys (or those that have been modified)
   config.translation_method = :override
 end

data/lib/generators/better_translate/translate_generator.rb

@@ -3,12 +3,14 @@ require 'rails/generators'
 module BetterTranslate
   module Generators
     class TranslateGenerator < Rails::Generators::Base
-      desc "Lancia il processo di traduzione configurato in BetterTranslate"
+      desc "Starts the translation process configured in BetterTranslate"
 
       def run_translation
-        say_status("Starting", "Esecuzione della traduzione con BetterTranslate...", :green)
+        message = "Starting translation with BetterTranslate..."
+        BetterTranslate::Utils.logger(message: message)
         BetterTranslate.magic
-        say_status("Done", "Traduzione completata.", :green)
+        message = "Translation completed."
+        BetterTranslate::Utils.logger(message: message)
       end
     end
   end

data/sig/better_translate.rbs

@@ -0,0 +1,4 @@
+module BetterTranslate
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -1,57 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: better_translate
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
-- alessio_bussolari
+- Alessio Bussolari
 autorequire:
 bindir: exe
 cert_chain: []
 date: 2025-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: yaml
+  name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.13'
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.21.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.21.0
 - !ruby/object:Gem::Dependency
-  name: ruby-progressbar
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,22 +80,142 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: "\nBetterTranslate is a gem that allows you to translate YAML files from
-  a source language into one or more target languages.\nThe gem supports different
-  translation providers, currently ChatGPT (OpenAI) and Google Gemini, and allows
-  you to choose\nthe translation mode: \"override\" to regenerate all translations
-  or \"incremental\" to update only the missing keys.\n\nThe gem's configuration is
-  centralized via an initializer, where you can define API keys, target languages,
-  source language,\nkey exclusions, and the output folder. BetterTranslate also integrates
-  translation progress tracking using a progress bar.\n  "
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.22'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: |
+  BetterTranslate is a powerful Ruby gem for translating YAML files using AI providers.
+
+  Key features:
+  * Multiple AI providers support (ChatGPT and Google Gemini)
+  * Smart translation modes (override/incremental)
+  * LRU caching for performance
+  * Precise key exclusion control
+  * Rails integration with generators
+  * Progress tracking with progress bar
+  * Comprehensive test coverage
+
+  Perfect for internationalizing Ruby/Rails applications with minimal effort.
 email:
 - alessio.bussolari@pandev.it
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
+- Rakefile
 - lib/better_translate.rb
 - lib/better_translate/helper.rb
 - lib/better_translate/providers/base_provider.rb
@@ -109,6 +229,7 @@ files:
 - lib/generators/better_translate/install_generator.rb
 - lib/generators/better_translate/templates/better_translate.rb
 - lib/generators/better_translate/translate_generator.rb
+- sig/better_translate.rbs
 homepage: https://github.com/alessiobussolari/better_translate
 licenses:
 - MIT
@@ -118,6 +239,9 @@ metadata:
   homepage_uri: https://github.com/alessiobussolari/better_translate
   source_code_uri: https://github.com/alessiobussolari/better_translate
   changelog_uri: https://github.com/alessiobussolari/better_translate/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/alessiobussolari/better_translate/issues
+  documentation_uri: https://github.com/alessiobussolari/better_translate
+  wiki_uri: https://github.com/alessiobussolari/better_translate/wiki
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -136,6 +260,5 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: Gem for translating YAML files into multiple languages using providers (ChatGPT
-  and Gemini)
+summary: AI-powered YAML translation with ChatGPT and Google Gemini
 test_files: []