better_translate 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39116f70ea2683daa65f22e5acad342e91010465dc76b00046a34f3f369b471b
-  data.tar.gz: d2687a9e7ab0867894b56ae4563715aa06b61d7071755ef337f86d80fe72dfbd
+  metadata.gz: 1110968d8e49f85d5231775f9c05fcbca610021a33723999c75246b687f56b77
+  data.tar.gz: 255e51ff5e5105ebf314b703d9aa841c66eaa6b0ffb5ca1f631ea2cbe81ab6db
 SHA512:
-  metadata.gz: 41e2a36c986088a37612c72d692a2ca89e9fa6b5c52951f7b5a3e41201820baa49aa362213670d1f1d52c3735afb2e06bad94dcea640fdc35fe88c3e90a2d468
-  data.tar.gz: 35035a09d3f7088739ecc0b8cc46ef9e7863a546dbeaf2809ce6ef611417933fd30950ed226d297a770d38fda7c4d04e31e5a3be6219ebd7a89301739261a1d9
+  metadata.gz: b971940521bce1ad359990e13fe7d17a339f9d5e62fe5ea9b565fe1ffbd51fe2c2dd24789cd02b7e838a20a3ae88de919ed529adf325b3c11d7377c6bced68e5
+  data.tar.gz: 1d8d785607ba4439df35ceb70b0c302ba1944bfdd74e197d2686cbe7781cfab55bfc93ed7a2affa9ef50b5fc1a459034b1d3cdf6f60420cb2df1b0252d5e3ac5

data/README.md

@@ -15,15 +15,23 @@ Configuration is centralized via an initializer (for example, in a Rails app), w
   - **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.
-- **Generators**: Includes Rails generators to easily install the initializer and to trigger the translation process (e.g., via `rails generate better_translate:translate`).
+- **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.
 
 ## Installation
 
 Add the gem to your Gemfile:
 
 ```ruby
-gem 'better_translate'
+gem 'better_translate', '~> 0.1.0'
 ```
 
 Then run:
@@ -76,8 +84,13 @@ BetterTranslate.configure do |config|
     "key.child_key"
   ]
   
-  # Language-specific exclusions (optional)
+  # Language-specific exclusions: keys to exclude only for specific target languages
   config.exclusions_per_language = {
+    "es" => [],
+    "it" => ["sample.valid"],
+    "fr" => [],
+    "de" => [],
+    "pt" => [],
     "ru" => []
   }
   
@@ -85,7 +98,7 @@ BetterTranslate.configure do |config|
   config.input_file = Rails.root.join("config", "locales", "en.yml").to_s
   
   # Translation mode: :override or :incremental
-  config.translation_method = :override
+  config.translation_mode = :override
 end
 ```
 
@@ -101,28 +114,89 @@ BetterTranslate.magic
 
 This will execute the process that:
 1. Reads the input YAML file.
-2. Applies any filters (exclusions).
-3. Translates the strings from the source language into the configured target languages.
-4. Writes the translated files to the output folder, either in **override** or **incremental** mode based on the configuration.
+2. Applies the global exclusion filtering.
+3. Applies additional language-specific exclusion filtering for each target language.
+4. Translates the strings from the source language into the configured target languages.
+5. Writes the translated files to the output folder, either in **override** or **incremental** mode based on the configuration.
 
 ### Using Rails Generators
 
-The gem includes a generator to trigger the translation process. You can run:
+The gem includes generators to simplify tasks:
 
-```bash
-rails generate better_translate:translate
+- **Generate Initializer:**
+
+  ```bash
+  rails generate better_translate:install
+  ```
+
+- **Trigger Translation Process:**
+
+  ```bash
+  rails generate better_translate:translate
+  ```
+
+  The `better_translate:translate` generator will trigger the translation process (via `BetterTranslate.magic`) and display progress in the terminal.
+
+### Translation Helpers
+
+BetterTranslate provides helper methods to simplify translation tasks.
+
+#### Single Text Translation
+
+The `translate_text_to_languages` helper allows you to translate a single text into multiple target languages in one call.
+
+**Example Usage:**
+
+```ruby
+text = "Hello world!"
+target_languages = [
+  { short_name: "it", name: "Italian" },
+  { short_name: "fr", name: "French" }
+]
+
+translated = BetterTranslate::TranslationHelper.translate_text_to_languages(
+  text,
+  target_languages,
+  "en",       # source language code
+  :chatgpt    # provider: can be :chatgpt or :gemini
+)
+
+puts translated
+# Expected output:
+# { "it" => "Ciao mondo!", "fr" => "Bonjour le monde!" }
 ```
 
-This generator will call the translation process (via `BetterTranslate.magic`) and display the progress in the terminal.
+#### Multiple Texts Translation
 
-## Contact & Feature Requests
+The `translate_texts_to_languages` helper extends the functionality to translate an array of texts into multiple target languages. It returns a hash where each key is a target language code and the value is an array of translated texts.
 
-For suggestions, bug reports, or to request new features, please reach out via email at: **alessio.bussolari@pandev.it**.
+**Example Usage:**
+
+```ruby
+texts = ["Hello world!", "How are you?"]
+target_languages = [
+  { short_name: "it", name: "Italian" },
+  { short_name: "fr", name: "French" }
+]
+
+translated_texts = BetterTranslate::TranslationHelper.translate_texts_to_languages(
+  texts,
+  target_languages,
+  "en",       # source language code
+  :chatgpt    # provider: can be :chatgpt or :gemini
+)
+
+puts translated_texts
+# Expected output:
+# {
+#   "it" => ["Ciao mondo!", "Come stai?"],
+#   "fr" => ["Bonjour le monde!", "Comment ça va?"]
+# }
+```
 
-## Upcoming Features
+## Contact & Feature Requests
 
-- **Selective YAML Key Exclusion**: Ability to exclude specific YAML keys for translation on a per-language basis.
-- **Helper Methods**: Additional helper methods to integrate BetterTranslate as a translation system for dynamic content.
+For suggestions, bug reports, or to request new features, please reach out via email at: **alessio.bussolari@pandev.it**.
 
 ## Conclusions
 
@@ -130,10 +204,6 @@ BetterTranslate aims to simplify the translation of YAML files in Ruby projects
 
 For more details, please visit the [GitHub repository](https://github.com/alessiobussolari/better_translate).
 
-## Changelog
-
-See the [CHANGELOG](https://github.com/alessiobussolari/better_translate/blob/main/CHANGELOG.md) for a summary of changes.
-
 ## License
 
-BetterTranslate is distributed under the MIT license. See the [LICENSE](LICENSE) file for more details.
+BetterTranslate is distributed under the MIT license. See the [LICENSE](LICENSE) file for more details.

data/lib/better_translate/helper.rb

@@ -0,0 +1,75 @@
+module BetterTranslate
+  class Helper
+    class << self
+      # Translates a given text into multiple target languages.
+      #
+      # @param text [String] The text to be translated.
+      # @param target_languages [Array<Hash>] Array of target language hashes,
+      #   e.g. [{ short_name: "it", name: "Italian" }, { short_name: "fr", name: "French" }]
+      # @param source_language [String] The source language code (e.g., "en").
+      # @param provider_name [Symbol] The provider to use (e.g., :chatgpt or :gemini).
+      # @return [Hash] A hash where each key is a target language code and the value is the translated text.
+      #
+      # Example:
+      #   translated = BetterTranslate::Helpers.translate_text_to_languages(
+      #     "Hello world!",
+      #     [{ short_name: "it", name: "Italian" }, { short_name: "fr", name: "French" }],
+      #     "en",
+      #     :chatgpt
+      #   )
+      #   # => { "it" => "Ciao mondo!", "fr" => "Bonjour le monde!" }
+      def translate_text_to_languages(text, target_languages, source_language, provider_name)
+        provider_instance = case provider_name
+                            when :chatgpt
+                              Providers::ChatgptProvider.new(BetterTranslate.configuration.openai_key)
+                            when :gemini
+                              Providers::GeminiProvider.new(BetterTranslate.configuration.google_gemini_key)
+                            else
+                              raise "Provider not supported: #{provider_name}"
+                            end
+
+        result = {}
+        target_languages.each do |lang|
+          # Optionally, you could also pass the source_language if needed by your provider.
+          translated_text = provider_instance.translate(text, lang[:short_name], lang[:name])
+          result[lang[:short_name]] = translated_text
+        end
+        result
+      end
+
+      # Translates an array of texts into multiple target languages using the translate_text_to_languages helper.
+      #
+      # @param texts [Array<String>] An array of texts to translate.
+      # @param target_languages [Array<Hash>] Array of target language hashes,
+      #   e.g. [{ short_name: "it", name: "Italian" }, { short_name: "fr", name: "French" }].
+      # @param source_language [String] The source language code (e.g., "en").
+      # @param provider_name [Symbol] The provider to use (e.g., :chatgpt or :gemini).
+      # @return [Hash] A hash where each key is a target language code and the value is an array of translated texts.
+      #
+      # Example:
+      #   texts = ["Hello world!", "How are you?"]
+      #   result = BetterTranslate::TranslationHelper.translate_texts_to_languages(
+      #     texts,
+      #     [{ short_name: "it", name: "Italian" }, { short_name: "fr", name: "French" }],
+      #     "en",
+      #     :chatgpt
+      #   )
+      #   # => { "it" => ["Ciao mondo!", "Come stai?"], "fr" => ["Bonjour le monde!", "Comment ça va?"] }
+      def translate_texts_to_languages(texts, target_languages, source_language, provider_name)
+        result = {}
+        target_languages.each do |lang|
+          # For each target language, translate each text and collect translations into an array.
+          result[lang[:short_name]] = texts.map do |text|
+            translation_hash = translate_text_to_languages(text, [lang], source_language, provider_name)
+            translation_hash[lang[:short_name]]
+          end
+        end
+        result
+      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)

data/lib/better_translate/translator.rb

@@ -7,19 +7,24 @@ module BetterTranslate
         translations = read_yml_source
 
         # Rimuove le chiavi da escludere (global_exclusions) dalla struttura letta
-        filtered_translations = remove_exclusions(
+        global_filtered_translations = remove_exclusions(
           translations, BetterTranslate.configuration.global_exclusions
         )
 
         BetterTranslate.configuration.target_languages.each do |target_lang|
+
+          # Fase 2: Applica il filtro specifico per la lingua target
+          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]}"
           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
-
-        "Traduzione iniziata! #{filtered_translations.inspect}"
       end
 
       private
@@ -38,18 +43,18 @@ module BetterTranslate
         YAML.load_file(file_path)
       end
 
-      # Rimuove le chiavi specificate in exclusion_list dalla struttura dati,
+      # Rimuove le chiavi globali da escludere dalla struttura dati,
       # calcolando i percorsi a partire dal contenuto della lingua di partenza.
       #
       # Ad esempio, se il file YAML è:
-      # { "en" => { "sample" => { "valid" => "valid", "excluded" => "Excluded" } } }
-      # e exclusion_list = ["sample.excluded"],
+      #   { "en" => { "sample" => { "valid" => "valid", "excluded" => "Excluded" } } }
+      # e global_exclusions = ["sample.excluded"],
       # il risultato sarà:
-      # { "en" => { "sample" => { "valid" => "valid" } } }
+      #   { "en" => { "sample" => { "valid" => "valid" } } }
       #
       # @param data [Hash, Array, Object] La struttura dati da filtrare.
-      # @param exclusion_list [Array<String>] Lista dei percorsi (in dot notation) da escludere.
-      # @param current_path [Array] Il percorso corrente (usato in maniera ricorsiva).
+      # @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.
       def remove_exclusions(data, exclusion_list, current_path = [])
         if data.is_a?(Hash)

data/lib/better_translate/utils.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# lib/better_seeder/utils.rb
+#
+# = 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.
+
+module BetterTranslate
+  class Utils
+    class << self
+      ##
+      # Registra un messaggio usando il logger di Rails se disponibile, altrimenti lo stampa su standard output.
+      #
+      # ==== Parametri
+      # * +message+ - Il messaggio da loggare (può essere una stringa o nil).
+      #
+      # ==== Ritorno
+      # Non ritorna un valore significativo.
+      #
+      def logger(message: nil)
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.info message
+        else
+          puts message
+        end
+      end
+    end
+  end
+end

data/lib/better_translate/version.rb

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

data/lib/better_translate.rb

@@ -2,9 +2,11 @@
 require "ruby-progressbar"
 
 require "better_translate/version"
+require "better_translate/utils"
 require "better_translate/translator"
 require "better_translate/service"
 require "better_translate/writer"
+require "better_translate/helper"
 
 require 'better_translate/providers/base_provider'
 require 'better_translate/providers/chatgpt_provider'
@@ -23,7 +25,8 @@ module BetterTranslate
     # Metodo install per generare il file di configurazione (initializer)
     def install
       unless defined?(Rails) && Rails.respond_to?(:root)
-        puts "Il metodo install è disponibile solo in un'applicazione Rails."
+        message = "Il metodo install è disponibile solo in un'applicazione Rails."
+        BetterTranslate::Utils.logger(message: message)
         return
       end
 
@@ -32,19 +35,23 @@ module BetterTranslate
       destination = File.join(Rails.root, "config", "initializers", "better_translate.rb")
 
       if File.exist?(destination)
-        puts "Il file initializer esiste già: #{destination}"
+        message = "Il file initializer esiste già: #{destination}"
+        BetterTranslate::Utils.logger(message: message)
       else
         FileUtils.mkdir_p(File.dirname(destination))
         FileUtils.cp(source, destination)
-        puts "Initializer creato in: #{destination}"
+        message = "Il file initializer esiste già: #{destination}"
+        BetterTranslate::Utils.logger(message: message)
       end
     end
 
     def magic
-      puts "Metodo magic invocato: eseguirò la traduzione dei file..."
+      message = "Metodo magic invocato: eseguirò la traduzione dei file..."
+      BetterTranslate::Utils.logger(message: message)
 
       BetterTranslate::Translator.work
-      puts "Metodo magic invocato: Traduzione completata con successo!"
+      message = "Metodo magic invocato: Traduzione completata con successo!"
+      BetterTranslate::Utils.logger(message: message)
     end
 
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_translate
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - alessio_bussolari
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yaml
@@ -80,15 +80,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: "\nBetterTranslate è una gemma che consente di tradurre file YAML partendo
-  da una lingua sorgente verso una o più lingue target.\nLa gemma supporta differenti
-  provider di traduzione, attualmente ChatGPT (OpenAI) e Google Gemini, e permette
-  di scegliere\nla modalità di traduzione: \"override\" per rigenerare tutte le traduzioni
-  oppure \"incremental\" per aggiornare solo le chiavi mancanti.\n\nLa configurazione
-  della gemma è centralizzata tramite un initializer, dove è possibile definire API
-  key, lingue target, lingua sorgente,\nesclusioni di chiavi e la cartella di output.
-  BetterTranslate integra inoltre il monitoraggio del progresso della traduzione tramite
-  una progress bar.\n  "
+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  "
 email:
 - alessio.bussolari@pandev.it
 executables: []
@@ -98,11 +97,13 @@ files:
 - LICENSE.txt
 - README.md
 - lib/better_translate.rb
+- lib/better_translate/helper.rb
 - lib/better_translate/providers/base_provider.rb
 - lib/better_translate/providers/chatgpt_provider.rb
 - lib/better_translate/providers/gemini_provider.rb
 - lib/better_translate/service.rb
 - lib/better_translate/translator.rb
+- lib/better_translate/utils.rb
 - lib/better_translate/version.rb
 - lib/better_translate/writer.rb
 - lib/generators/better_translate/install_generator.rb
@@ -135,5 +136,6 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: Gemma per tradurre file YAML in più lingue tramite provider (ChatGPT e Gemini)
+summary: Gem for translating YAML files into multiple languages using providers (ChatGPT
+  and Gemini)
 test_files: []