better_translate 0.5.0 → 1.0.0

data/lib/generators/better_translate/analyze/analyze_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterTranslate
+  module Generators
+    # Rails generator for analyzing YAML locale files
+    #
+    # Provides statistics about translation files: string count, structure, etc.
+    #
+    # @example Analyze a file
+    #   rails generate better_translate:analyze config/locales/en.yml
+    #
+    class AnalyzeGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Analyze YAML locale file structure and statistics"
+
+      argument :file_path,
+               type: :string,
+               required: false,
+               default: "config/locales/en.yml",
+               desc: "Path to YAML file to analyze"
+
+      # Analyze YAML file
+      #
+      # @return [void]
+      #
+      def analyze_file
+        full_path = Rails.root.join(file_path)
+
+        unless File.exist?(full_path)
+          say "File not found: #{full_path}", :red
+          return
+        end
+
+        say "Analyzing: #{file_path}", :green
+        say "=" * 60
+
+        begin
+          data = YAML.load_file(full_path)
+
+          # Flatten to count strings
+          flattened = BetterTranslate::Utils::HashFlattener.flatten(data)
+
+          say ""
+          say "Total strings: #{flattened.size}", :cyan
+          say ""
+
+          # Show structure
+          say "Structure:", :yellow
+          show_structure(data, 0)
+
+          say ""
+          say "=" * 60
+          say "Analysis complete", :green
+        rescue StandardError => e
+          say "Error analyzing file: #{e.message}", :red
+        end
+      end
+
+      private
+
+      # Show nested structure
+      #
+      # @param hash [Hash] Hash to show
+      # @param level [Integer] Nesting level
+      # @return [void]
+      # @api private
+      #
+      def show_structure(hash, level)
+        hash.each do |key, value|
+          indent = "  " * level
+          if value.is_a?(Hash)
+            say "#{indent}#{key}/ (#{count_strings(value)} strings)", :white
+            show_structure(value, level + 1)
+          else
+            say "#{indent}#{key}: #{value.to_s[0..50]}#{value.to_s.length > 50 ? "..." : ""}", :white
+          end
+        end
+      end
+
+      # Count strings in nested hash
+      #
+      # @param hash [Hash] Hash to count
+      # @return [Integer] String count
+      # @api private
+      #
+      def count_strings(hash)
+        BetterTranslate::Utils::HashFlattener.flatten(hash).size
+      end
+    end
+  end
+end

data/lib/generators/better_translate/install/USAGE

@@ -0,0 +1,13 @@
+Description:
+    Installs BetterTranslate configuration files for Rails application.
+
+    This will create:
+    - config/initializers/better_translate.rb (Ruby configuration)
+    - config/better_translate.yml (YAML configuration)
+
+Example:
+    bin/rails generate better_translate:install
+
+    This will create:
+        config/initializers/better_translate.rb
+        config/better_translate.yml

data/lib/generators/better_translate/install/install_generator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterTranslate
+  module Generators
+    # Rails generator for installing BetterTranslate
+    #
+    # Creates initializer and config files for Rails applications.
+    #
+    # @example Run generator
+    #   rails generate better_translate:install
+    #
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates BetterTranslate initializer and config files"
+
+      # Create initializer file
+      #
+      # @return [void]
+      #
+      def create_initializer_file
+        template "initializer.rb.tt", "config/initializers/better_translate.rb"
+      end
+
+      # Create YAML config file
+      #
+      # @return [void]
+      #
+      def create_config_file
+        sample_config = {
+          "provider" => "chatgpt",
+          "openai_key" => "YOUR_OPENAI_API_KEY",
+          "gemini_key" => "YOUR_GEMINI_API_KEY",
+          "anthropic_key" => "YOUR_ANTHROPIC_API_KEY",
+          "source_language" => "en",
+          "target_languages" => [
+            { "short_name" => "it", "name" => "Italian" },
+            { "short_name" => "es", "name" => "Spanish" },
+            { "short_name" => "fr", "name" => "French" }
+          ],
+          "input_file" => "config/locales/en.yml",
+          "output_folder" => "config/locales",
+          "verbose" => true,
+          "dry_run" => false,
+          "translation_mode" => "override",
+          "preserve_variables" => true,
+          "global_exclusions" => Array.new,
+          "exclusions_per_language" => Hash.new,
+          "model" => nil,
+          "temperature" => 0.3,
+          "max_tokens" => 2000,
+          "timeout" => 30,
+          "max_retries" => 3,
+          "rate_limit" => 10
+        }
+
+        create_file "config/better_translate.yml", sample_config.to_yaml
+      end
+
+      # Show post-install message
+      #
+      # @return [void]
+      #
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/better_translate/install/templates/README

@@ -0,0 +1,20 @@
+===============================================================================
+
+BetterTranslate has been installed!
+
+Created files:
+  • config/initializers/better_translate.rb
+  • config/better_translate.yml
+
+Next steps:
+
+1. Edit config/better_translate.yml and add your API keys
+2. Customize translation settings in config/initializers/better_translate.rb
+3. Run translation:
+
+   rake better_translate:translate
+
+For more information:
+  • https://github.com/alessiobussolari/better_translate
+
+===============================================================================

data/lib/generators/better_translate/install/templates/initializer.rb.tt

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# BetterTranslate Configuration
+#
+# For more configuration options, see config/better_translate.yml
+
+BetterTranslate.configure do |config|
+  # Provider: :chatgpt, :gemini, or :anthropic
+  config.provider = :chatgpt
+
+  # API Keys (alternatively set via ENV variables)
+  config.openai_key = ENV["OPENAI_API_KEY"]
+  config.gemini_key = ENV["GEMINI_API_KEY"]
+  config.anthropic_key = ENV["ANTHROPIC_API_KEY"]
+
+  # Source and target languages
+  config.source_language = "en"
+  config.target_languages = [
+    { short_name: "it", name: "Italian" },
+    { short_name: "es", name: "Spanish" },
+    { short_name: "fr", name: "French" }
+  ]
+
+  # File paths
+  config.input_file = Rails.root.join("config", "locales", "en.yml").to_s
+  config.output_folder = Rails.root.join("config", "locales").to_s
+
+  # Options
+  config.verbose = true
+  config.dry_run = false # Set to true for testing
+  config.translation_mode = :override # or :incremental
+  config.preserve_variables = true
+
+  # Optional: Provider-specific settings
+  # config.model = "gpt-5-nano" # ChatGPT model
+  # config.temperature = 0.3
+  # config.max_tokens = 2000
+  # config.timeout = 30
+  # config.max_retries = 3
+  # config.rate_limit = 10
+
+  # Optional: Exclusions
+  # config.global_exclusions = ["excluded_key", "another_key"]
+  # config.exclusions_per_language = {
+  #   "it" => ["italy_specific_exclusion"]
+  # }
+end

data/lib/generators/better_translate/translate/USAGE

@@ -0,0 +1,13 @@
+Description:
+    Runs BetterTranslate translation based on existing configuration.
+
+    This will translate your YAML locale files using the configuration
+    in config/better_translate.yml.
+
+Example:
+    bin/rails generate better_translate:translate
+
+    This will execute the translation task.
+
+Options:
+    --dry-run    Run in dry-run mode (no files will be written)

data/lib/generators/better_translate/translate/translate_generator.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterTranslate
+  module Generators
+    # Rails generator for running translations
+    #
+    # Executes translation based on existing configuration.
+    #
+    # @example Run generator
+    #   rails generate better_translate:translate
+    #
+    # @example Run with dry-run
+    #   rails generate better_translate:translate --dry-run
+    #
+    class TranslateGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Run BetterTranslate translation task"
+
+      class_option :dry_run,
+                   type: :boolean,
+                   default: false,
+                   desc: "Run in dry-run mode (no files written)"
+
+      # Run translation
+      #
+      # @return [void]
+      #
+      def run_translation
+        config_file = Rails.root.join("config", "better_translate.yml")
+
+        unless File.exist?(config_file)
+          say "Config file not found at #{config_file}", :red
+          say "Run 'rails generate better_translate:install' first"
+          return
+        end
+
+        # Load configuration from YAML
+        yaml_config = YAML.load_file(config_file)
+
+        # Configure BetterTranslate
+        BetterTranslate.configure do |config|
+          config.provider = yaml_config["provider"]&.to_sym
+          config.openai_key = yaml_config["openai_key"] || ENV["OPENAI_API_KEY"]
+          config.gemini_key = yaml_config["gemini_key"] || ENV["GEMINI_API_KEY"]
+          config.anthropic_key = yaml_config["anthropic_key"] || ENV["ANTHROPIC_API_KEY"]
+
+          config.source_language = yaml_config["source_language"]
+          config.target_languages = yaml_config["target_languages"]&.map do |lang|
+            if lang.is_a?(Hash)
+              { short_name: lang["short_name"], name: lang["name"] }
+            else
+              lang
+            end
+          end
+
+          config.input_file = Rails.root.join(yaml_config["input_file"]).to_s
+          config.output_folder = Rails.root.join(yaml_config["output_folder"]).to_s
+          config.verbose = yaml_config.fetch("verbose", true)
+          config.dry_run = options[:dry_run] || yaml_config.fetch("dry_run", false)
+
+          # Map "full" to :override for backward compatibility
+          translation_mode = yaml_config.fetch("translation_mode", "override")
+          translation_mode = "override" if translation_mode == "full"
+          config.translation_mode = translation_mode.to_sym
+
+          config.preserve_variables = yaml_config.fetch("preserve_variables", true)
+
+          # Exclusions
+          config.global_exclusions = yaml_config["global_exclusions"] || []
+          config.exclusions_per_language = yaml_config["exclusions_per_language"] || {}
+
+          # Provider options
+          config.model = yaml_config["model"] if yaml_config["model"]
+          config.temperature = yaml_config["temperature"] if yaml_config["temperature"]
+          config.max_tokens = yaml_config["max_tokens"] if yaml_config["max_tokens"]
+          config.timeout = yaml_config["timeout"] if yaml_config["timeout"]
+          config.max_retries = yaml_config["max_retries"] if yaml_config["max_retries"]
+          config.rate_limit = yaml_config["rate_limit"] if yaml_config["rate_limit"]
+        end
+
+        # Perform translation
+        say "Starting translation...", :green
+        say "Provider: #{BetterTranslate.configuration.provider}"
+        say "Source: #{BetterTranslate.configuration.source_language}"
+        say "Targets: #{BetterTranslate.configuration.target_languages.map { |l| l[:name] }.join(", ")}"
+
+        say "DRY RUN MODE - No files will be written", :yellow if options[:dry_run]
+
+        say ""
+
+        results = BetterTranslate.translate_files
+
+        # Report results
+        say ""
+        say "=" * 60
+        say "Translation Complete", :green
+        say "=" * 60
+        say "Success: #{results[:success_count]}", :green
+        say "Failure: #{results[:failure_count]}", results[:failure_count].zero? ? :green : :red
+
+        return unless results[:errors].any?
+
+        say ""
+        say "Errors:", :red
+        results[:errors].each do |error|
+          say "  - #{error[:language]}: #{error[:error]}", :red
+        end
+      end
+    end
+  end
+end

data/lib/tasks/better_translate.rake

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+# Define :environment task as no-op if it doesn't exist (for non-Rails usage)
+unless Rake::Task.task_defined?(:environment)
+  task :environment do
+    # No-op for standalone usage
+  end
+end
+
+namespace :better_translate do
+  desc "Translate YAML locale files using AI providers"
+  task translate: :environment do
+    config_file = Rails.root.join("config", "better_translate.yml")
+
+    unless File.exist?(config_file)
+      puts "Error: Configuration file not found at #{config_file}"
+      puts "Run 'rake better_translate:config:generate' to create one."
+      exit 1
+    end
+
+    # Load configuration from YAML
+    yaml_config = YAML.load_file(config_file)
+
+    # Configure BetterTranslate
+    BetterTranslate.configure do |config|
+      config.provider = yaml_config["provider"]&.to_sym
+      config.openai_key = yaml_config["openai_key"] || ENV["OPENAI_API_KEY"]
+      config.gemini_key = yaml_config["gemini_key"] || ENV["GEMINI_API_KEY"]
+      config.anthropic_key = yaml_config["anthropic_key"] || ENV["ANTHROPIC_API_KEY"]
+
+      config.source_language = yaml_config["source_language"]
+      config.target_languages = yaml_config["target_languages"]&.map do |lang|
+        if lang.is_a?(Hash)
+          { short_name: lang["short_name"], name: lang["name"] }
+        else
+          lang
+        end
+      end
+
+      config.input_file = yaml_config["input_file"]
+      config.output_folder = yaml_config["output_folder"]
+      config.verbose = yaml_config.fetch("verbose", true)
+      config.dry_run = yaml_config.fetch("dry_run", false)
+
+      # Map "full" to :override for backward compatibility
+      translation_mode = yaml_config.fetch("translation_mode", "override")
+      translation_mode = "override" if translation_mode == "full"
+      config.translation_mode = translation_mode.to_sym
+
+      config.preserve_variables = yaml_config.fetch("preserve_variables", true)
+
+      # Exclusions
+      config.global_exclusions = yaml_config["global_exclusions"] || []
+      config.exclusions_per_language = yaml_config["exclusions_per_language"] || {}
+
+      # Provider options
+      config.model = yaml_config["model"] if yaml_config["model"]
+      config.temperature = yaml_config["temperature"] if yaml_config["temperature"]
+      config.max_tokens = yaml_config["max_tokens"] if yaml_config["max_tokens"]
+      config.timeout = yaml_config["timeout"] if yaml_config["timeout"]
+      config.max_retries = yaml_config["max_retries"] if yaml_config["max_retries"]
+      config.rate_limit = yaml_config["rate_limit"] if yaml_config["rate_limit"]
+    end
+
+    # Perform translation
+    puts "Starting translation..."
+    puts "Provider: #{BetterTranslate.configuration.provider}"
+    puts "Source: #{BetterTranslate.configuration.source_language}"
+    puts "Targets: #{BetterTranslate.configuration.target_languages.map { |l| l[:name] }.join(", ")}"
+    puts
+
+    results = BetterTranslate.translate_files
+
+    # Report results
+    puts
+    puts "=" * 60
+    puts "Translation Complete"
+    puts "=" * 60
+    puts "Success: #{results[:success_count]}"
+    puts "Failure: #{results[:failure_count]}"
+
+    if results[:errors].any?
+      puts
+      puts "Errors:"
+      results[:errors].each do |error|
+        puts "  - #{error[:language]}: #{error[:error]}"
+      end
+    end
+  end
+
+  namespace :config do
+    desc "Generate sample configuration file"
+    task generate: :environment do
+      config_file = Rails.root.join("config", "better_translate.yml")
+
+      if File.exist?(config_file)
+        puts "Configuration file already exists at #{config_file}"
+        puts "Delete it first if you want to regenerate."
+        next
+      end
+
+      sample_config = {
+        "provider" => "chatgpt",
+        "openai_key" => "YOUR_OPENAI_API_KEY",
+        "gemini_key" => "YOUR_GEMINI_API_KEY",
+        "anthropic_key" => "YOUR_ANTHROPIC_API_KEY",
+        "source_language" => "en",
+        "target_languages" => [
+          { "short_name" => "it", "name" => "Italian" },
+          { "short_name" => "es", "name" => "Spanish" },
+          { "short_name" => "fr", "name" => "French" }
+        ],
+        "input_file" => "config/locales/en.yml",
+        "output_folder" => "config/locales",
+        "verbose" => true,
+        "dry_run" => false,
+        "translation_mode" => "full",
+        "preserve_variables" => true,
+        "global_exclusions" => [],
+        "exclusions_per_language" => {},
+        "model" => nil,
+        "temperature" => 0.3,
+        "max_tokens" => 2000,
+        "timeout" => 30,
+        "max_retries" => 3,
+        "rate_limit" => 10
+      }
+
+      File.write(config_file, sample_config.to_yaml)
+      puts "Generated configuration file at #{config_file}"
+      puts "Please edit it with your API keys and preferences."
+    end
+  end
+end

data/sig/better_translate/cache.rbs

@@ -0,0 +1,28 @@
+module BetterTranslate
+  # LRU (Least Recently Used) Cache implementation
+  #
+  # Thread-safe cache with configurable capacity and optional TTL.
+  class Cache
+    type cache_entry = { value: String, timestamp: Time }
+
+    @capacity: Integer
+    @ttl: Integer?
+    @cache: Hash[String, cache_entry]
+    @mutex: Thread::Mutex
+
+    attr_reader capacity: Integer
+    attr_reader ttl: Integer?
+
+    def initialize: (?capacity: Integer, ?ttl: Integer?) -> void
+
+    def get: (String key) -> String?
+
+    def set: (String key, String value) -> String
+
+    def clear: () -> void
+
+    def size: () -> Integer
+
+    def key?: (String key) -> bool
+  end
+end

data/sig/better_translate/cli.rbs

@@ -0,0 +1,24 @@
+module BetterTranslate
+  # Command-line interface for BetterTranslate
+  #
+  # Provides standalone CLI commands for translation without Rails.
+  class CLI
+    @args: Array[String]
+
+    attr_reader args: Array[String]
+
+    def initialize: (Array[String] args) -> void
+
+    def run: () -> void
+
+    private
+
+    def show_help: () -> void
+
+    def run_translate: () -> void
+
+    def run_generate: () -> void
+
+    def run_direct: () -> void
+  end
+end

data/sig/better_translate/configuration.rbs

@@ -0,0 +1,78 @@
+module BetterTranslate
+  # Configuration class for BetterTranslate
+  #
+  # Manages all configuration options with type safety and validation.
+  class Configuration
+    type target_language = { short_name: String, name: String }
+
+    @provider: Symbol?
+    @openai_key: String?
+    @google_gemini_key: String?
+    @anthropic_key: String?
+    @source_language: String?
+    @target_languages: Array[target_language]
+    @input_file: String?
+    @output_folder: String?
+    @translation_mode: Symbol
+    @translation_context: String?
+    @max_concurrent_requests: Integer
+    @request_timeout: Integer
+    @max_retries: Integer
+    @retry_delay: Float
+    @cache_enabled: bool
+    @cache_size: Integer
+    @cache_ttl: Integer?
+    @verbose: bool
+    @dry_run: bool
+    @global_exclusions: Array[String]
+    @exclusions_per_language: Hash[String, Array[String]]
+    @preserve_variables: bool
+
+    attr_accessor provider: (Symbol | nil)
+    attr_accessor openai_key: String?
+    attr_accessor google_gemini_key: String?
+    attr_accessor gemini_key: String?
+    attr_accessor anthropic_key: String?
+    attr_accessor source_language: String?
+    attr_accessor target_languages: Array[target_language]
+    attr_accessor input_file: String?
+    attr_accessor output_folder: String?
+    attr_accessor translation_mode: Symbol
+    attr_accessor translation_context: String?
+    attr_accessor max_concurrent_requests: Integer
+    attr_accessor request_timeout: Integer
+    attr_accessor max_retries: Integer
+    attr_accessor retry_delay: Float
+    attr_accessor cache_enabled: bool
+    attr_accessor cache_size: Integer
+    attr_accessor cache_ttl: Integer?
+    attr_accessor verbose: bool
+    attr_accessor dry_run: bool
+    attr_accessor global_exclusions: Array[String]
+    attr_accessor exclusions_per_language: Hash[String, Array[String]]
+    attr_accessor preserve_variables: bool
+
+    # Provider-specific options
+    attr_accessor model: String?
+    attr_accessor temperature: Float?
+    attr_accessor max_tokens: Integer?
+    attr_accessor timeout: Integer?
+    attr_accessor rate_limit: (Integer | Float)?
+
+    def initialize: () -> void
+
+    def validate!: () -> true
+
+    private
+
+    def validate_provider!: () -> void
+
+    def validate_api_keys!: () -> void
+
+    def validate_languages!: () -> void
+
+    def validate_files!: () -> void
+
+    def validate_optional_settings!: () -> void
+  end
+end

data/sig/better_translate/direct_translator.rbs

@@ -0,0 +1,18 @@
+module BetterTranslate
+  # Direct text translator for non-YAML workflows
+  #
+  # Provides convenience methods for translating individual strings or batches
+  # without requiring YAML files. Useful for runtime translation needs.
+  class DirectTranslator
+    @config: Configuration
+    @provider: Providers::BaseHttpProvider
+
+    attr_reader config: Configuration
+
+    def initialize: (Configuration config) -> void
+
+    def translate: (String text, to: (String | Symbol), language_name: String) -> String
+
+    def translate_batch: (Array[String] texts, to: (String | Symbol), language_name: String, ?skip_errors: bool) -> Array[String?]
+  end
+end