better_translate 0.5.0 → 1.0.0

data/docs/implementation/08-rails_integration.md

@@ -0,0 +1,323 @@
+# 08 - Rails Integration
+
+[← Previous: 07-Direct Translation Helpers](./07-direct_translation_helpers.md) | [Back to Index](../../IMPLEMENTATION_PLAN.md) | [Next: 09-Testing Suite →](./09-testing_suite.md)
+
+---
+
+## Rails Integration
+
+### 7.1 `lib/generators/better_translate/install/install_generator.rb`
+
+```ruby
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterTranslate
+  module Generators
+    # Generator to install BetterTranslate in a Rails application
+    #
+    # Creates an initializer file with example configuration.
+    #
+    # @example
+    #   rails generate better_translate:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a BetterTranslate initializer file"
+
+      # Create initializer file
+      #
+      # @return [void]
+      def create_initializer_file
+        template "initializer.rb.tt", "config/initializers/better_translate.rb"
+      end
+
+      # Display post-install message
+      #
+      # @return [void]
+      def show_readme
+        readme "INSTALL" if behavior == :invoke
+      end
+
+      private
+
+      def readme(file)
+        say "\n" + "=" * 80
+        say "BetterTranslate installed successfully!"
+        say "=" * 80
+        say "\nNext steps:"
+        say "1. Edit config/initializers/better_translate.rb with your settings"
+        say "2. Set your API keys in environment variables:"
+        say "   - OPENAI_API_KEY (for ChatGPT)"
+        say "   - GEMINI_API_KEY (for Google Gemini)"
+        say "   - ANTHROPIC_API_KEY (for Anthropic Claude)"
+        say "3. Run: rails generate better_translate:translate"
+        say "\n" + "=" * 80 + "\n"
+      end
+    end
+  end
+end
+```
+
+### 7.2 `lib/generators/better_translate/install/templates/initializer.rb.tt`
+
+```ruby
+# frozen_string_literal: true
+
+# BetterTranslate Configuration
+#
+# For more information, see: https://github.com/alessiobussolari/better_translate
+
+BetterTranslate.configure do |config|
+  # ==============================
+  # REQUIRED SETTINGS
+  # ==============================
+
+  # Provider: :chatgpt, :gemini, or :anthropic
+  config.provider = :chatgpt
+
+  # API Keys (use environment variables for security)
+  config.openai_key = ENV["OPENAI_API_KEY"]           # For ChatGPT
+  # config.google_gemini_key = ENV["GEMINI_API_KEY"]  # For Gemini
+  # config.anthropic_key = ENV["ANTHROPIC_API_KEY"]   # For Anthropic
+
+  # Source language code (2 letters)
+  config.source_language = "en"
+
+  # Target languages
+  config.target_languages = [
+    { short_name: "it", name: "Italian" },
+    { short_name: "fr", name: "French" },
+    { short_name: "de", name: "German" },
+    { short_name: "es", name: "Spanish" }
+  ]
+
+  # File paths
+  config.input_file = Rails.root.join("config", "locales", "en.yml").to_s
+  config.output_folder = Rails.root.join("config", "locales").to_s
+
+  # ==============================
+  # OPTIONAL SETTINGS
+  # ==============================
+
+  # Translation mode: :override or :incremental
+  # - :override replaces entire files
+  # - :incremental only translates missing keys
+  config.translation_mode = :override
+
+  # Domain-specific context for better translations
+  # config.translation_context = "E-commerce product descriptions and checkout flow"
+
+  # Caching
+  config.cache_enabled = true
+  config.cache_size = 1000
+  # config.cache_ttl = 3600  # Seconds (nil = no expiration)
+
+  # Performance
+  config.max_concurrent_requests = 3
+  config.request_timeout = 30
+  config.max_retries = 3
+  config.retry_delay = 2.0
+
+  # Logging
+  config.verbose = true
+
+  # Dry run (don't write files, just test)
+  # config.dry_run = false
+
+  # Exclusions (keys to never translate)
+  # config.global_exclusions = ["app.name", "brand.logo_url"]
+  # config.exclusions_per_language = {
+  #   "fr" => ["legal.disclaimer"],
+  #   "de" => ["privacy.gdpr_text"]
+  # }
+end
+```
+
+### 7.3 `lib/generators/better_translate/translate/translate_generator.rb`
+
+```ruby
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterTranslate
+  module Generators
+    # Generator to run BetterTranslate translation
+    #
+    # Triggers the translation process using the current configuration.
+    #
+    # @example
+    #   rails generate better_translate:translate
+    class TranslateGenerator < Rails::Generators::Base
+      desc "Run BetterTranslate translation"
+
+      # Run translation
+      #
+      # @return [void]
+      def run_translation
+        say "Starting translation process...", :green
+
+        begin
+          results = BetterTranslate.translate_all
+
+          say "\n" + "=" * 80, :green
+          say "Translation completed!", :green
+          say "=" * 80, :green
+          say "✓ Successful: #{results[:success_count]} languages", :green
+          say "✗ Failed: #{results[:failure_count]} languages", :red if results[:failure_count] > 0
+
+          if results[:errors].any?
+            say "\nErrors:", :red
+            results[:errors].each do |error|
+              say "  - #{error[:language]}: #{error[:error]}", :red
+            end
+          end
+
+          say "=" * 80 + "\n", :green
+
+        rescue BetterTranslate::ConfigurationError => e
+          say "Configuration error: #{e.message}", :red
+          say "\nPlease check config/initializers/better_translate.rb", :yellow
+          exit 1
+        rescue StandardError => e
+          say "Unexpected error: #{e.message}", :red
+          say e.backtrace.join("\n"), :red
+          exit 1
+        end
+      end
+    end
+  end
+end
+```
+
+### 7.4 `lib/generators/better_translate/analyze/analyze_generator.rb`
+
+```ruby
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterTranslate
+  module Generators
+    # Generator to analyze translation similarities
+    #
+    # Uses Levenshtein distance to detect potential translation issues.
+    #
+    # @example
+    #   rails generate better_translate:analyze
+    class AnalyzeGenerator < Rails::Generators::Base
+      desc "Analyze translation similarities using Levenshtein distance"
+
+      # Run analysis
+      #
+      # @return [void]
+      def run_analysis
+        say "Analyzing translations...", :cyan
+
+        config = BetterTranslate.configuration
+        raise "BetterTranslate not configured" unless config
+
+        yaml_handler = YAMLHandler.new(config)
+        source_strings = yaml_handler.get_source_strings
+
+        results = []
+
+        config.target_languages.each do |lang|
+          target_path = yaml_handler.build_output_path(lang[:short_name])
+          next unless File.exist?(target_path)
+
+          target_data = yaml_handler.read_yaml(target_path)
+          target_strings = Utils::HashFlattener.flatten(target_data[lang[:short_name]] || target_data)
+
+          source_strings.each do |key, source_value|
+            target_value = target_strings[key]
+            next unless target_value
+
+            similarity = calculate_similarity(source_value, target_value)
+
+            # Flag if too similar (might indicate untranslated text)
+            if similarity > 0.8 && source_value.length > 10
+              results << {
+                language: lang[:name],
+                key: key,
+                source: source_value,
+                target: target_value,
+                similarity: (similarity * 100).round(1)
+              }
+            end
+          end
+        end
+
+        display_results(results)
+      end
+
+      private
+
+      # Calculate Levenshtein similarity (0.0 to 1.0)
+      def calculate_similarity(str1, str2)
+        return 1.0 if str1 == str2
+        return 0.0 if str1.empty? || str2.empty?
+
+        distance = levenshtein_distance(str1.downcase, str2.downcase)
+        max_length = [str1.length, str2.length].max
+
+        1.0 - (distance.to_f / max_length)
+      end
+
+      # Calculate Levenshtein distance
+      def levenshtein_distance(str1, str2)
+        matrix = Array.new(str1.length + 1) { Array.new(str2.length + 1) }
+
+        (0..str1.length).each { |i| matrix[i][0] = i }
+        (0..str2.length).each { |j| matrix[0][j] = j }
+
+        (1..str1.length).each do |i|
+          (1..str2.length).each do |j|
+            cost = str1[i - 1] == str2[j - 1] ? 0 : 1
+            matrix[i][j] = [
+              matrix[i - 1][j] + 1,      # deletion
+              matrix[i][j - 1] + 1,      # insertion
+              matrix[i - 1][j - 1] + cost # substitution
+            ].min
+          end
+        end
+
+        matrix[str1.length][str2.length]
+      end
+
+      def display_results(results)
+        if results.empty?
+          say "\n✓ No suspicious translations found!", :green
+          return
+        end
+
+        say "\n⚠ Found #{results.size} potentially untranslated strings:", :yellow
+        say "=" * 80, :yellow
+
+        results.each do |result|
+          say "\nLanguage: #{result[:language]}", :cyan
+          say "Key: #{result[:key]}", :white
+          say "Source: #{result[:source]}", :white
+          say "Target: #{result[:target]}", :white
+          say "Similarity: #{result[:similarity]}%", :yellow
+        end
+
+        say "\n" + "=" * 80, :yellow
+        say "\nNote: High similarity might indicate:", :white
+        say "  - Untranslated text (e.g., brand names that shouldn't be translated)"
+        say "  - Proper nouns or technical terms"
+        say "  - Translation errors"
+        say "\nReview these translations and add to exclusions if needed.", :white
+      end
+    end
+  end
+end
+```
+
+---
+
+---
+
+[← Previous: 07-Direct Translation Helpers](./07-direct_translation_helpers.md) | [Back to Index](../../IMPLEMENTATION_PLAN.md) | [Next: 09-Testing Suite →](./09-testing_suite.md)

data/docs/implementation/09-testing_suite.md

@@ -0,0 +1,228 @@
+# 09 - Testing Suite
+
+[← Previous: 08-Rails Integration](./08-rails_integration.md) | [Back to Index](../../IMPLEMENTATION_PLAN.md) | [Next: 10-Documentation Examples →](./10-documentation_examples.md)
+
+---
+
+## Testing Suite
+
+### 8.1 Aggiornare `spec/spec_helper.rb`
+
+```ruby
+# frozen_string_literal: true
+
+require "better_translate"
+require "webmock/rspec"
+require "vcr"
+
+# Load support files
+Dir[File.expand_path("support/**/*.rb", __dir__)].sort.each { |f| require f }
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  # Disable external HTTP requests
+  config.before(:each) do
+    WebMock.disable_net_connect!(allow_localhost: true)
+  end
+
+  # Reset BetterTranslate configuration before each test
+  config.before(:each) do
+    BetterTranslate.reset!
+  end
+end
+```
+
+### 8.2 `spec/support/vcr.rb`
+
+```ruby
+# frozen_string_literal: true
+
+require "vcr"
+
+VCR.configure do |config|
+  config.cassette_library_dir = "spec/vcr_cassettes"
+  config.hook_into :webmock
+  config.configure_rspec_metadata!
+
+  # Filter sensitive data
+  config.filter_sensitive_data("<OPENAI_API_KEY>") { ENV["OPENAI_API_KEY"] }
+  config.filter_sensitive_data("<GEMINI_API_KEY>") { ENV["GEMINI_API_KEY"] }
+  config.filter_sensitive_data("<ANTHROPIC_API_KEY>") { ENV["ANTHROPIC_API_KEY"] }
+
+  # Allow real HTTP for specific tests if needed
+  config.allow_http_connections_when_no_cassette = false
+
+  # Default cassette options
+  config.default_cassette_options = {
+    record: :once,
+    match_requests_on: [:method, :uri, :body]
+  }
+end
+```
+
+### 8.3 `spec/support/test_helpers.rb`
+
+```ruby
+# frozen_string_literal: true
+
+module TestHelpers
+  # Create a temporary YAML file for testing
+  #
+  # @param content [Hash] YAML content
+  # @return [String] Path to temporary file
+  def create_temp_yaml(content)
+    file = Tempfile.new(["test", ".yml"])
+    file.write(YAML.dump(content))
+    file.close
+    file.path
+  end
+
+  # Create a test configuration
+  #
+  # @param overrides [Hash] Configuration overrides
+  # @return [BetterTranslate::Configuration] Configuration object
+  def build_config(**overrides)
+    config = BetterTranslate::Configuration.new
+
+    # Set defaults
+    config.provider = :chatgpt
+    config.openai_key = "test-api-key"
+    config.source_language = "en"
+    config.target_languages = [{ short_name: "it", name: "Italian" }]
+    config.input_file = create_temp_yaml("en" => { "hello" => "Hello" })
+    config.output_folder = Dir.mktmpdir
+
+    # Apply overrides
+    overrides.each do |key, value|
+      config.send("#{key}=", value)
+    end
+
+    config
+  end
+end
+
+RSpec.configure do |config|
+  config.include TestHelpers
+end
+```
+
+### 8.4 `spec/fixtures/en.yml`
+
+```yaml
+en:
+  hello: "Hello"
+  goodbye: "Goodbye"
+  welcome:
+    message: "Welcome to our application"
+    subtitle: "We're glad you're here"
+  user:
+    profile:
+      name: "Name"
+      email: "Email"
+      password: "Password"
+  errors:
+    not_found: "Resource not found"
+    unauthorized: "You are not authorized"
+```
+
+### 8.5 Test Files Listing
+
+Creare questi spec files (esempio di struttura per ognuno):
+
+- `spec/better_translate/configuration_spec.rb` - Test validazione e configurazione
+- `spec/better_translate/cache_spec.rb` - Test LRU cache
+- `spec/better_translate/rate_limiter_spec.rb` - Test rate limiting
+- `spec/better_translate/validator_spec.rb` - Test validazione input
+- `spec/better_translate/yaml_handler_spec.rb` - Test YAML operations
+- `spec/better_translate/translator_spec.rb` - Test main translator
+- `spec/better_translate/progress_tracker_spec.rb` - Test progress display
+- `spec/better_translate/provider_factory_spec.rb` - Test factory pattern
+- `spec/better_translate/providers/chatgpt_provider_spec.rb` - Test ChatGPT provider
+- `spec/better_translate/providers/gemini_provider_spec.rb` - Test Gemini provider
+- `spec/better_translate/providers/anthropic_provider_spec.rb` - Test Anthropic provider
+- `spec/better_translate/strategies/deep_strategy_spec.rb` - Test deep strategy
+- `spec/better_translate/strategies/batch_strategy_spec.rb` - Test batch strategy
+- `spec/better_translate/utils/hash_flattener_spec.rb` - Test hash utilities
+- `spec/integration/translation_workflow_spec.rb` - End-to-end integration tests
+
+### 8.6 Esempio Test: `spec/better_translate/configuration_spec.rb`
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe BetterTranslate::Configuration do
+  describe "#initialize" do
+    it "sets default values" do
+      config = described_class.new
+
+      expect(config.translation_mode).to eq(:override)
+      expect(config.max_concurrent_requests).to eq(3)
+      expect(config.request_timeout).to eq(30)
+      expect(config.cache_enabled).to be true
+      expect(config.cache_size).to eq(1000)
+      expect(config.verbose).to be false
+    end
+  end
+
+  describe "#validate!" do
+    let(:config) { build_config }
+
+    it "validates successfully with all required fields" do
+      expect { config.validate! }.not_to raise_error
+    end
+
+    it "raises error when provider is nil" do
+      config.provider = nil
+      expect { config.validate! }.to raise_error(
+        BetterTranslate::ConfigurationError,
+        "Provider must be set"
+      )
+    end
+
+    it "raises error when API key is missing for ChatGPT" do
+      config.provider = :chatgpt
+      config.openai_key = nil
+      expect { config.validate! }.to raise_error(
+        BetterTranslate::ConfigurationError,
+        /OpenAI API key is required/
+      )
+    end
+
+    it "raises error when source language is empty" do
+      config.source_language = ""
+      expect { config.validate! }.to raise_error(
+        BetterTranslate::ConfigurationError,
+        "Source language must be set"
+      )
+    end
+
+    it "raises error when target languages is empty" do
+      config.target_languages = []
+      expect { config.validate! }.to raise_error(
+        BetterTranslate::ConfigurationError,
+        "At least one target language is required"
+      )
+    end
+
+    it "raises error when input file does not exist" do
+      config.input_file = "/non/existent/file.yml"
+      expect { config.validate! }.to raise_error(
+        BetterTranslate::ConfigurationError,
+        /Input file does not exist/
+      )
+    end
+  end
+end
+```
+
+---
+
+---
+
+[← Previous: 08-Rails Integration](./08-rails_integration.md) | [Back to Index](../../IMPLEMENTATION_PLAN.md) | [Next: 10-Documentation Examples →](./10-documentation_examples.md)

data/docs/implementation/10-documentation_examples.md

@@ -0,0 +1,150 @@
+# 10 - Documentation & Examples
+
+[← Previous: 09-Testing Suite](./09-testing_suite.md) | [Back to Index](../../IMPLEMENTATION_PLAN.md) | [Next: 11-Quality Security →](./11-quality_security.md)
+
+---
+
+## Documentation & Examples
+
+### 9.1 Creare `examples/basic_usage.rb`
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "better_translate"
+
+# Basic usage example
+BetterTranslate.configure do |config|
+  config.provider = :chatgpt
+  config.openai_key = ENV["OPENAI_API_KEY"]
+  config.source_language = "en"
+  config.target_languages = [
+    { short_name: "it", name: "Italian" },
+    { short_name: "fr", name: "French" }
+  ]
+  config.input_file = "config/locales/en.yml"
+  config.output_folder = "config/locales"
+  config.verbose = true
+end
+
+puts "Starting translation..."
+results = BetterTranslate.translate_all
+
+puts "\n" + "=" * 80
+puts "Translation Results:"
+puts "  ✓ Success: #{results[:success_count]} languages"
+puts "  ✗ Failed: #{results[:failure_count]} languages"
+
+if results[:errors].any?
+  puts "\nErrors:"
+  results[:errors].each do |error|
+    puts "  - #{error[:language]}: #{error[:error]}"
+  end
+end
+puts "=" * 80
+```
+
+### 9.2 Creare `examples/advanced_usage.rb`
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "better_translate"
+
+# Advanced usage with all options
+BetterTranslate.configure do |config|
+  # Provider selection
+  config.provider = :anthropic
+  config.anthropic_key = ENV["ANTHROPIC_API_KEY"]
+
+  # Languages
+  config.source_language = "en"
+  config.target_languages = [
+    { short_name: "it", name: "Italian" },
+    { short_name: "fr", name: "French" },
+    { short_name: "de", name: "German" },
+    { short_name: "es", name: "Spanish" }
+  ]
+
+  # Files
+  config.input_file = "config/locales/en.yml"
+  config.output_folder = "config/locales"
+
+  # Translation mode
+  config.translation_mode = :incremental  # Preserve existing translations
+
+  # Domain-specific context
+  config.translation_context = "Medical terminology for healthcare applications"
+
+  # Caching
+  config.cache_enabled = true
+  config.cache_size = 2000
+  config.cache_ttl = 3600  # 1 hour
+
+  # Performance tuning
+  config.max_concurrent_requests = 5
+  config.request_timeout = 60
+  config.max_retries = 5
+  config.retry_delay = 3.0
+
+  # Logging
+  config.verbose = true
+
+  # Exclusions
+  config.global_exclusions = ["app.name", "company.logo_url"]
+  config.exclusions_per_language = {
+    "fr" => ["legal.disclaimer"],  # French has custom legal text
+    "de" => ["privacy.gdpr_text"]  # German GDPR text is manually translated
+  }
+
+  # Dry run (don't actually write files)
+  # config.dry_run = true
+end
+
+puts "Advanced Translation Configuration"
+puts "=" * 80
+puts "Provider: #{BetterTranslate.configuration.provider}"
+puts "Languages: #{BetterTranslate.configuration.target_languages.map { |l| l[:name] }.join(", ")}"
+puts "Mode: #{BetterTranslate.configuration.translation_mode}"
+puts "Cache: #{BetterTranslate.configuration.cache_enabled ? "enabled" : "disabled"}"
+puts "=" * 80
+puts "\nStarting translation...\n"
+
+results = BetterTranslate.translate_all
+
+puts "\n" + "=" * 80
+puts "Translation Results:"
+puts "  ✓ Success: #{results[:success_count]} languages"
+puts "  ✗ Failed: #{results[:failure_count]} languages"
+
+if results[:errors].any?
+  puts "\nErrors:"
+  results[:errors].each do |error|
+    puts "  - #{error[:language]}: #{error[:error]}"
+    puts "    Context: #{error[:context]}" if error[:context].any?
+  end
+end
+puts "=" * 80
+```
+
+### 9.3 Aggiornare `README.md`
+
+Il README dovrebbe includere:
+- Installation instructions
+- Quick start guide
+- Configuration options
+- Usage examples
+- Rails integration
+- Supported providers
+- Contributing guidelines
+- License
+
+---
+
+---
+
+[← Previous: 09-Testing Suite](./09-testing_suite.md) | [Back to Index](../../IMPLEMENTATION_PLAN.md) | [Next: 11-Quality Security →](./11-quality_security.md)