better_translate 1.1.0 → 1.1.1

data/sig/better_translate/analyzer/key_scanner.rbs

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Scans YAML translation files and extracts all keys in flatten format
+    class KeyScanner
+      # Path to the YAML file
+      attr_reader file_path: String
+
+      # Flatten keys extracted from YAML
+      attr_reader keys: Hash[String, untyped]
+
+      # Initialize scanner with YAML file path
+      #
+      # @param file_path Path to YAML file
+      def initialize: (String file_path) -> void
+
+      # Scan YAML file and extract all flatten keys
+      #
+      # @return Flatten keys with their values
+      def scan: () -> Hash[String, untyped]
+
+      # Get total count of keys
+      #
+      # @return Number of keys
+      def key_count: () -> Integer
+
+      private
+
+      # Validate that file exists
+      def validate_file!: () -> void
+
+      # Flatten nested hash into dot-notation keys
+      #
+      # @param hash Nested hash to flatten
+      # @param prefix Prefix for current level
+      def flatten_keys: (Hash[untyped, untyped] hash, ?String? prefix) -> void
+    end
+  end
+end

data/sig/better_translate/analyzer/orphan_detector.rbs

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Detects orphan i18n keys (keys defined but never used in code)
+    class OrphanDetector
+      # All translation keys with their values
+      attr_reader all_keys: Hash[String, untyped]
+
+      # Keys that are used in code
+      attr_reader used_keys: Set[String]
+
+      # Orphan keys (not used in code)
+      attr_reader orphans: Array[String]
+
+      # Initialize detector
+      #
+      # @param all_keys All translation keys from YAML files
+      # @param used_keys Keys found in code
+      def initialize: (Hash[String, untyped] all_keys, Set[String] used_keys) -> void
+
+      # Detect orphan keys
+      #
+      # @return List of orphan key names
+      def detect: () -> Array[String]
+
+      # Get count of orphan keys
+      #
+      # @return Number of orphan keys
+      def orphan_count: () -> Integer
+
+      # Get details of orphan keys with their values
+      #
+      # @return Hash of orphan keys and their translation values
+      def orphan_details: () -> Hash[String, untyped]
+
+      # Calculate usage percentage
+      #
+      # @return Percentage of keys that are used (0.0 to 100.0)
+      def usage_percentage: () -> Float
+    end
+  end
+end

data/sig/better_translate/analyzer/reporter.rbs

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Generates reports for orphan key analysis
+    class Reporter
+      # List of orphan keys
+      attr_reader orphans: Array[String]
+
+      # Orphan keys with their values
+      attr_reader orphan_details: Hash[String, untyped]
+
+      # Total number of keys
+      attr_reader total_keys: Integer
+
+      # Number of used keys
+      attr_reader used_keys: Integer
+
+      # Usage percentage
+      attr_reader usage_percentage: Float
+
+      # Output format (:text, :json, :csv)
+      attr_reader format: Symbol
+
+      # Initialize reporter
+      #
+      # @param orphans List of orphan keys
+      # @param orphan_details Orphan keys with values
+      # @param total_keys Total number of keys
+      # @param used_keys Number of used keys
+      # @param usage_percentage Usage percentage
+      # @param format Output format (:text, :json, :csv)
+      def initialize: (
+        orphans: Array[String],
+        orphan_details: Hash[String, untyped],
+        total_keys: Integer,
+        used_keys: Integer,
+        usage_percentage: Float,
+        ?format: Symbol
+      ) -> void
+
+      # Generate report in specified format
+      #
+      # @return Generated report
+      def generate: () -> String
+
+      # Save report to file
+      #
+      # @param file_path Output file path
+      def save_to_file: (String file_path) -> void
+
+      private
+
+      # Generate text format report
+      #
+      # @return Text report
+      def generate_text: () -> String
+
+      # Generate JSON format report
+      #
+      # @return JSON report
+      def generate_json: () -> String
+
+      # Generate CSV format report
+      #
+      # @return CSV report
+      def generate_csv: () -> String
+    end
+  end
+end

data/sig/better_translate/cli.rbs

@@ -20,5 +20,7 @@ module BetterTranslate
     def run_generate: () -> void
 
     def run_direct: () -> void
+
+    def run_analyze: () -> void
   end
 end

data/sig/better_translate/json_handler.rbs

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  # Handles JSON file operations
+  class JsonHandler
+    # Configuration object
+    attr_reader config: Configuration
+
+    # Initialize JSON handler
+    #
+    # @param config Configuration object
+    def initialize: (Configuration config) -> void
+
+    # Read and parse JSON file
+    #
+    # @param file_path Path to JSON file
+    # @return Parsed JSON content
+    def read_json: (String file_path) -> Hash[untyped, untyped]
+
+    # Write hash to JSON file
+    #
+    # @param file_path Output file path
+    # @param data Data to write
+    # @param diff_preview Optional diff preview instance
+    # @return Summary hash if dry_run, nil otherwise
+    def write_json: (String file_path, Hash[untyped, untyped] data, ?diff_preview: untyped) -> (Hash[Symbol, untyped] | nil)
+
+    # Get translatable strings from source JSON
+    #
+    # @return Flattened hash of translatable strings
+    def get_source_strings: () -> Hash[String, untyped]
+
+    # Filter out excluded keys for a specific language
+    #
+    # @param strings Flattened strings
+    # @param target_lang_code Target language code
+    # @return Filtered strings
+    def filter_exclusions: (Hash[String, untyped] strings, String target_lang_code) -> Hash[String, untyped]
+
+    # Merge translated strings with existing file (incremental mode)
+    #
+    # @param file_path Existing file path
+    # @param new_translations New translations (flattened)
+    # @return Merged translations (nested)
+    def merge_translations: (String file_path, Hash[String, untyped] new_translations) -> Hash[String, untyped]
+
+    # Build output file path for target language
+    #
+    # @param target_lang_code Target language code
+    # @return Output file path
+    def build_output_path: (String target_lang_code) -> String
+
+    private
+
+    # Create backup file with rotation support
+    #
+    # @param file_path Path to file to backup
+    def create_backup_file: (String file_path) -> void
+
+    # Rotate backup files, keeping only max_backups
+    #
+    # @param file_path Base file path
+    def rotate_backups: (String file_path) -> void
+  end
+end

data/sig/better_translate/progress_tracker.rbs

@@ -14,7 +14,7 @@ module BetterTranslate
 
     def complete: (String language, Integer total_strings) -> void
 
-    def error: (String language, StandardError error) -> void
+    def error: (String language, Exception error) -> void
 
     def reset: () -> void
 

data/sig/better_translate.rbs

@@ -5,6 +5,10 @@
 module BetterTranslate
   type translation_results = { success_count: Integer, failure_count: Integer, errors: Array[Hash[Symbol, untyped]] }
 
+  # Analyzer module for translation file analysis
+  module Analyzer
+  end
+
   # Module-level instance variable (for singleton methods)
   self.@configuration: Configuration?
 

data/sig/csv.rbs

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# CSV library type signatures
+class CSV
+  # Generate CSV string
+  #
+  # @yield CSV instance for writing rows
+  # @return CSV string
+  def self.generate: () { (CSV) -> void } -> String
+
+  # Add row to CSV
+  #
+  # @param row Array of values
+  # @return CSV instance
+  def <<: (Array[untyped]) -> CSV
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: better_translate
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-22 00:00:00.000000000 Z
+date: 2025-10-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -41,11 +55,15 @@ files:
 - CHANGELOG.md
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
 - RELEASE_NOTES_v1.0.0.md
 - Rakefile
+- SECURITY.md
 - Steepfile
+- brakeman.yml
+- codecov.yml
 - docs/implementation/00-overview.md
 - docs/implementation/01-setup_dependencies.md
 - docs/implementation/02-error_handling.md
@@ -99,13 +117,17 @@ files:
 - lib/generators/better_translate/translate/USAGE
 - lib/generators/better_translate/translate/translate_generator.rb
 - lib/tasks/better_translate.rake
-- regenerate_vcr.rb
 - sig/better_translate.rbs
+- sig/better_translate/analyzer/code_scanner.rbs
+- sig/better_translate/analyzer/key_scanner.rbs
+- sig/better_translate/analyzer/orphan_detector.rbs
+- sig/better_translate/analyzer/reporter.rbs
 - sig/better_translate/cache.rbs
 - sig/better_translate/cli.rbs
 - sig/better_translate/configuration.rbs
 - sig/better_translate/direct_translator.rbs
 - sig/better_translate/errors.rbs
+- sig/better_translate/json_handler.rbs
 - sig/better_translate/progress_tracker.rbs
 - sig/better_translate/provider_factory.rbs
 - sig/better_translate/providers/anthropic_provider.rbs
@@ -124,6 +146,7 @@ files:
 - sig/better_translate/variable_extractor.rbs
 - sig/better_translate/version.rbs
 - sig/better_translate/yaml_handler.rbs
+- sig/csv.rbs
 - sig/faraday.rbs
 - sig/generators/better_translate/analyze/analyze_generator.rbs
 - sig/generators/better_translate/install/install_generator.rbs

data/regenerate_vcr.rb

@@ -1,47 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "dotenv/load"
-require "vcr"
-require "webmock/rspec"
-require_relative "lib/better_translate"
-require "tmpdir"
-
-# Setup VCR
-VCR.configure do |config|
-  config.cassette_library_dir = "spec/vcr_cassettes"
-  config.hook_into :webmock
-  config.filter_sensitive_data("<GEMINI_API_KEY>") { ENV["GEMINI_API_KEY"] }
-  config.default_cassette_options = { record: :all }
-end
-
-test_dir = Dir.mktmpdir("gemini_test")
-puts "Test output dir: #{test_dir}"
-
-VCR.use_cassette("rails/dummy_app_gemini_translation", record: :all) do
-  config = BetterTranslate::Configuration.new
-  config.provider = :gemini
-  config.gemini_key = ENV["GEMINI_API_KEY"]
-  config.source_language = "en"
-  config.target_languages = [{ short_name: "fr", name: "French" }]
-  config.input_file = "spec/dummy/config/locales/en.yml"
-  config.output_folder = test_dir
-  config.cache_enabled = false
-  config.verbose = true
-  config.validate!
-
-  puts "Starting translation..."
-  translator = BetterTranslate::Translator.new(config)
-  results = translator.translate_all
-
-  puts "\nResults: #{results.inspect}"
-  puts "\nFiles created:"
-  Dir.entries(test_dir).each { |f| puts "  - #{f}" unless f.start_with?(".") }
-
-  if results[:success_count].positive?
-    puts "\n✓ Successfully regenerated VCR cassette!"
-  else
-    puts "\n✗ Translation failed"
-  end
-end