better_translate 0.5.0 → 1.0.0

data/sig/better_translate/errors.rbs

@@ -0,0 +1,46 @@
+module BetterTranslate
+  # Base error class for all BetterTranslate errors
+  class Error < StandardError
+    @context: Hash[Symbol, untyped]
+
+    attr_reader context: Hash[Symbol, untyped]
+
+    def initialize: (?String? message, ?context: Hash[Symbol, untyped]) -> void
+  end
+
+  # Raised when configuration is invalid or incomplete
+  class ConfigurationError < Error
+  end
+
+  # Raised when input validation fails
+  class ValidationError < Error
+  end
+
+  # Raised when translation fails
+  class TranslationError < Error
+  end
+
+  # Raised when a provider encounters an error
+  class ProviderError < Error
+  end
+
+  # Raised when an API call fails
+  class ApiError < Error
+  end
+
+  # Raised when rate limit is exceeded
+  class RateLimitError < ApiError
+  end
+
+  # Raised when file operations fail
+  class FileError < Error
+  end
+
+  # Raised when YAML parsing fails
+  class YamlError < Error
+  end
+
+  # Raised when a provider is not found
+  class ProviderNotFoundError < Error
+  end
+end

data/sig/better_translate/progress_tracker.rbs

@@ -0,0 +1,29 @@
+module BetterTranslate
+  # Tracks and displays translation progress
+  #
+  # Shows real-time progress updates with colored console output.
+  class ProgressTracker
+    @enabled: bool
+    @start_time: Time
+
+    attr_reader enabled: bool
+
+    def initialize: (?enabled: bool) -> void
+
+    def update: (language: String, current_key: String, progress: Float) -> void
+
+    def complete: (String language, Integer total_strings) -> void
+
+    def error: (String language, StandardError error) -> void
+
+    def reset: () -> void
+
+    private
+
+    def format_time: (Float seconds) -> String
+
+    def truncate: (String text, Integer max_length) -> String
+
+    def colorize: (String text, Symbol color) -> String
+  end
+end

data/sig/better_translate/provider_factory.rbs

@@ -0,0 +1,8 @@
+module BetterTranslate
+  # Factory for creating translation providers
+  #
+  # Creates the appropriate provider instance based on configuration.
+  class ProviderFactory
+    def self.create: (Symbol provider_name, Configuration config) -> Providers::BaseHttpProvider
+  end
+end

data/sig/better_translate/providers/anthropic_provider.rbs

@@ -0,0 +1,27 @@
+module BetterTranslate
+  module Providers
+    # Anthropic Claude translation provider
+    #
+    # Uses claude-3-5-sonnet-20241022 model for high-quality translations.
+    class AnthropicProvider < BaseHttpProvider
+      API_URL: String
+      MODEL: String
+      API_VERSION: String
+
+      type message_data = { system: String, messages: Array[Hash[Symbol, String]] }
+
+      def translate_text: (String text, String target_lang_code, String target_lang_name) -> String
+
+      def translate_batch: (Array[String] texts, String target_lang_code, String target_lang_name) -> Array[String]
+
+      # Private methods
+      def build_messages: (String text, String target_lang_name) -> message_data
+
+      def build_system_message: (String target_lang_name) -> String
+
+      def make_messages_request: (message_data message_data) -> Faraday::Response
+
+      def extract_translation: (Faraday::Response response) -> String
+    end
+  end
+end

data/sig/better_translate/providers/base_http_provider.rbs

@@ -0,0 +1,44 @@
+module BetterTranslate
+  # Translation provider implementations
+  module Providers
+    # Base class for HTTP-based translation providers
+    #
+    # Implements common functionality:
+    # - Faraday HTTP client with retry logic
+    # - Exponential backoff with jitter
+    # - Rate limiting
+    # - Caching
+    # - Error handling
+    class BaseHttpProvider
+      @config: Configuration
+      @cache: Cache
+      @rate_limiter: RateLimiter
+      @http_client: Faraday::Connection?
+
+      attr_reader config: Configuration
+      attr_reader cache: Cache
+      attr_reader rate_limiter: RateLimiter
+
+      def initialize: (Configuration config) -> void
+
+      def translate_text: (String text, String target_lang_code, String target_lang_name) -> String
+
+      def translate_batch: (Array[String] texts, String target_lang_code, String target_lang_name) -> Array[String]
+
+      # Protected methods (used by subclasses)
+      def make_request: (Symbol method, String url, ?body: Hash[untyped, untyped]?, ?headers: Hash[String, String]) -> Faraday::Response
+
+      def handle_response: (Faraday::Response response) -> void
+
+      def calculate_backoff: (Integer attempt) -> Float
+
+      def log_retry: (Integer attempt, Float delay, StandardError error) -> void
+
+      def http_client: () -> Faraday::Connection
+
+      def with_cache: [T] (String cache_key) { () -> T } -> T
+
+      def build_cache_key: (String text, String target_lang_code) -> String
+    end
+  end
+end

data/sig/better_translate/providers/chatgpt_provider.rbs

@@ -0,0 +1,25 @@
+module BetterTranslate
+  module Providers
+    # OpenAI ChatGPT translation provider
+    #
+    # Uses GPT-5-nano model with temperature=1.0 for natural translations.
+    class ChatGPTProvider < BaseHttpProvider
+      API_URL: String
+      MODEL: String
+      TEMPERATURE: Float
+
+      def translate_text: (String text, String target_lang_code, String target_lang_name) -> String
+
+      def translate_batch: (Array[String] texts, String target_lang_code, String target_lang_name) -> Array[String]
+
+      # Private methods
+      def build_messages: (String text, String target_lang_name) -> Array[Hash[Symbol, String]]
+
+      def build_system_message: (String target_lang_name) -> String
+
+      def make_chat_completion_request: (Array[Hash[Symbol, String]] messages) -> Faraday::Response
+
+      def extract_translation: (Faraday::Response response) -> String
+    end
+  end
+end

data/sig/better_translate/providers/gemini_provider.rbs

@@ -0,0 +1,22 @@
+module BetterTranslate
+  module Providers
+    # Google Gemini translation provider
+    #
+    # Uses gemini-2.0-flash-exp model for fast, high-quality translations.
+    class GeminiProvider < BaseHttpProvider
+      API_URL: String
+      MODEL: String
+
+      def translate_text: (String text, String target_lang_code, String target_lang_name) -> String
+
+      def translate_batch: (Array[String] texts, String target_lang_code, String target_lang_name) -> Array[String]
+
+      # Private methods
+      def build_prompt: (String text, String target_lang_name) -> String
+
+      def make_generation_request: (String prompt) -> Faraday::Response
+
+      def extract_translation: (Faraday::Response response) -> String
+    end
+  end
+end

data/sig/better_translate/railtie.rbs

@@ -0,0 +1,7 @@
+module BetterTranslate
+  # Rails integration
+  #
+  # Automatically loads Rake tasks when used in a Rails application.
+  class Railtie < Rails::Railtie
+  end
+end

data/sig/better_translate/rate_limiter.rbs

@@ -0,0 +1,20 @@
+module BetterTranslate
+  # Thread-safe rate limiter
+  #
+  # Ensures requests are spaced out by a minimum delay.
+  class RateLimiter
+    @delay: Float
+    @last_request_time: Time?
+    @mutex: Thread::Mutex
+
+    attr_reader delay: Float
+
+    def initialize: (?delay: Float) -> void
+
+    def wait: () -> void
+
+    def record_request: () -> void
+
+    def reset: () -> void
+  end
+end

data/sig/better_translate/strategies/base_strategy.rbs

@@ -0,0 +1,19 @@
+module BetterTranslate
+  # Translation strategy implementations
+  module Strategies
+    # Base class for translation strategies
+    class BaseStrategy
+      @config: Configuration
+      @provider: Providers::BaseHttpProvider
+      @progress_tracker: ProgressTracker
+
+      attr_reader config: Configuration
+      attr_reader provider: Providers::BaseHttpProvider
+      attr_reader progress_tracker: ProgressTracker
+
+      def initialize: (Configuration config, Providers::BaseHttpProvider provider, ProgressTracker progress_tracker) -> void
+
+      def translate: (Hash[String, String] strings, String target_lang_code, String target_lang_name) -> Hash[String, String]
+    end
+  end
+end

data/sig/better_translate/strategies/batch_strategy.rbs

@@ -0,0 +1,13 @@
+module BetterTranslate
+  module Strategies
+    # Batch translation strategy
+    #
+    # Translates strings in batches for improved performance.
+    # Used for larger files (>= 50 strings).
+    class BatchStrategy < BaseStrategy
+      BATCH_SIZE: Integer
+
+      def translate: (Hash[String, String] strings, String target_lang_code, String target_lang_name) -> Hash[String, String]
+    end
+  end
+end

data/sig/better_translate/strategies/deep_strategy.rbs

@@ -0,0 +1,11 @@
+module BetterTranslate
+  module Strategies
+    # Deep translation strategy
+    #
+    # Translates each string individually with detailed progress tracking.
+    # Used for smaller files (< 50 strings) to provide more granular progress.
+    class DeepStrategy < BaseStrategy
+      def translate: (Hash[String, String] strings, String target_lang_code, String target_lang_name) -> Hash[String, String]
+    end
+  end
+end

data/sig/better_translate/strategies/strategy_selector.rbs

@@ -0,0 +1,10 @@
+module BetterTranslate
+  module Strategies
+    # Selects the appropriate translation strategy based on content size
+    class StrategySelector
+      DEEP_STRATEGY_THRESHOLD: Integer
+
+      def self.select: (Integer strings_count, Configuration config, Providers::BaseHttpProvider provider, ProgressTracker progress_tracker) -> BaseStrategy
+    end
+  end
+end

data/sig/better_translate/translator.rbs

@@ -0,0 +1,24 @@
+module BetterTranslate
+  # Main translator class
+  #
+  # Coordinates the translation process using configuration, providers,
+  # strategies, and YAML handling.
+  class Translator
+    type translation_results = { success_count: Integer, failure_count: Integer, errors: Array[Hash[Symbol, untyped]] }
+
+    @config: Configuration
+    @provider: Providers::BaseHttpProvider
+    @yaml_handler: YAMLHandler
+    @progress_tracker: ProgressTracker
+
+    attr_reader config: Configuration
+
+    def initialize: (Configuration config) -> void
+
+    def translate_all: () -> translation_results
+
+    private
+
+    def translate_language: (Hash[String, untyped] source_strings, Hash[Symbol, String] lang) -> void
+  end
+end

data/sig/better_translate/utils/hash_flattener.rbs

@@ -0,0 +1,14 @@
+module BetterTranslate
+  # Utility classes and helpers
+  module Utils
+    # Utilities for flattening and unflattening nested hashes
+    #
+    # Used to convert nested YAML structures to flat key-value pairs
+    # and back again.
+    class HashFlattener
+      def self.flatten: (Hash[untyped, untyped] hash, ?String parent_key, ?String separator) -> Hash[String, untyped]
+
+      def self.unflatten: (Hash[String, untyped] hash, ?String separator) -> Hash[String, untyped]
+    end
+  end
+end

data/sig/better_translate/validator.rbs

@@ -0,0 +1,14 @@
+module BetterTranslate
+  # Input validation utilities
+  #
+  # Validates language codes, text, paths, and other inputs.
+  class Validator
+    def self.validate_language_code!: (String? code) -> true
+
+    def self.validate_text!: (String? text) -> true
+
+    def self.validate_file_exists!: (String? path) -> true
+
+    def self.validate_api_key!: (String? key, provider: Symbol) -> true
+  end
+end

data/sig/better_translate/variable_extractor.rbs

@@ -0,0 +1,40 @@
+module BetterTranslate
+  # Extracts and preserves interpolation variables during translation
+  #
+  # Supports multiple variable formats:
+  # - Rails I18n: %{name}, %{count}
+  # - I18n.js: {{user}}, {{email}}
+  # - ES6 templates: ${var}
+  # - Simple braces: {name}
+  class VariableExtractor
+    VARIABLE_PATTERNS: Hash[Symbol, Regexp]
+    COMBINED_PATTERN: Regexp
+    PLACEHOLDER_PREFIX: String
+    PLACEHOLDER_SUFFIX: String
+
+    @original_text: String
+    @variables: Array[String]
+    @placeholder_map: Hash[String, String]
+    @reverse_map: Hash[String, String]
+
+    attr_reader original_text: String
+    attr_reader variables: Array[String]
+    attr_reader placeholder_map: Hash[String, String]
+
+    def initialize: (String text) -> void
+
+    def extract: () -> String
+
+    def restore: (String translated_text, ?strict: bool) -> String
+
+    def variables?: () -> bool
+
+    def variable_count: () -> Integer
+
+    def validate_variables!: (String text) -> true
+
+    def self.find_variables: (String? text) -> Array[String]
+
+    def self.contains_variables?: (String? text) -> bool
+  end
+end

data/sig/better_translate/version.rbs

@@ -0,0 +1,4 @@
+module BetterTranslate
+  # Current version of BetterTranslate gem
+  VERSION: String
+end

data/sig/better_translate/yaml_handler.rbs

@@ -0,0 +1,29 @@
+module BetterTranslate
+  # Handles YAML file operations
+  #
+  # Provides methods for:
+  # - Reading and parsing YAML files
+  # - Writing YAML files with proper formatting
+  # - Merging translations (incremental mode)
+  # - Handling exclusions
+  # - Flattening/unflattening nested structures
+  class YAMLHandler
+    @config: Configuration
+
+    attr_reader config: Configuration
+
+    def initialize: (Configuration config) -> void
+
+    def read_yaml: (String file_path) -> Hash[untyped, untyped]
+
+    def write_yaml: (String file_path, Hash[untyped, untyped] data, ?diff_preview: untyped) -> (Hash[untyped, untyped] | nil)
+
+    def get_source_strings: () -> Hash[String, untyped]
+
+    def filter_exclusions: (Hash[String, untyped] strings, String target_lang_code) -> Hash[String, untyped]
+
+    def merge_translations: (String file_path, Hash[String, untyped] new_translations) -> Hash[String, untyped]
+
+    def build_output_path: (String target_lang_code) -> String
+  end
+end

data/sig/better_translate.rbs

@@ -1,4 +1,34 @@
+# BetterTranslate - AI-powered YAML locale file translator
+#
+# Automatically translate YAML locale files using AI providers (ChatGPT, Gemini, Claude).
+# Features intelligent caching, batch processing, and Rails integration.
 module BetterTranslate
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  type translation_results = { success_count: Integer, failure_count: Integer, errors: Array[Hash[Symbol, untyped]] }
+
+  @configuration: Configuration?
+
+  # Configure BetterTranslate
+  #
+  # Yields the configuration object for setting up the gem.
+  def self.configure: () { (Configuration) -> void } -> Configuration
+
+  # Get current configuration
+  #
+  # Returns the configuration instance, creating it if needed.
+  def self.configuration: () -> Configuration
+
+  # Translate files using current configuration
+  #
+  # Performs translation based on configured settings.
+  def self.translate_files: () -> translation_results
+
+  # Reset configuration
+  #
+  # Clears the current configuration.
+  def self.reset!: () -> void
+
+  # Get gem version
+  #
+  # Returns the version string.
+  def self.version: () -> String
 end

data/sig/faraday.rbs

@@ -0,0 +1,22 @@
+# Minimal Faraday type definitions for BetterTranslate
+module Faraday
+  class Response
+    def status: () -> Integer
+    def body: () -> String
+  end
+
+  class Options
+    def timeout=: (Integer value) -> Integer
+    def open_timeout=: (Integer value) -> Integer
+  end
+
+  class Connection
+    def send: (Symbol method, String url) { (untyped) -> void } -> Response
+    def options: () -> Options
+    def adapter: (untyped adapter) -> void
+  end
+
+  def self.new: () { (Connection) -> void } -> Connection
+
+  def self.default_adapter: () -> untyped
+end

data/sig/generators/better_translate/analyze/analyze_generator.rbs

@@ -0,0 +1,18 @@
+module BetterTranslate
+  module Generators
+    # Rails generator for analyzing YAML locale files
+    #
+    # Provides statistics about translation files: string count, structure, etc.
+    class AnalyzeGenerator < Rails::Generators::Base
+      attr_reader file_path: String
+
+      def analyze_file: () -> void
+
+      private
+
+      def show_structure: (Hash[untyped, untyped] hash, Integer level) -> void
+
+      def count_strings: (Hash[untyped, untyped] hash) -> Integer
+    end
+  end
+end

data/sig/generators/better_translate/install/install_generator.rbs

@@ -0,0 +1,14 @@
+module BetterTranslate
+  module Generators
+    # Rails generator for installing BetterTranslate
+    #
+    # Creates initializer and config files for Rails applications.
+    class InstallGenerator < Rails::Generators::Base
+      def create_initializer_file: () -> void
+
+      def create_config_file: () -> void
+
+      def show_readme: () -> void
+    end
+  end
+end

data/sig/generators/better_translate/translate/translate_generator.rbs

@@ -0,0 +1,10 @@
+module BetterTranslate
+  module Generators
+    # Rails generator for running translations
+    #
+    # Executes translation based on existing configuration.
+    class TranslateGenerator < Rails::Generators::Base
+      def run_translation: () -> void
+    end
+  end
+end

data/sig/optparse.rbs

@@ -0,0 +1,9 @@
+# Minimal OptionParser type definitions for BetterTranslate
+class OptionParser
+  def initialize: () { (OptionParser) -> void } -> void
+  def banner=: (String) -> String
+  def on: (String, String) { (String) -> void } -> void
+        | (String, String, String) { (String) -> void } -> void
+  def parse!: (Array[String]?) -> void
+        | () -> void
+end

data/sig/psych.rbs

@@ -0,0 +1,5 @@
+# Minimal Psych type definitions
+module Psych
+  class SyntaxError < StandardError
+  end
+end

data/sig/rails.rbs

@@ -0,0 +1,34 @@
+# Minimal Rails type definitions for BetterTranslate
+module Rails
+  class Railtie
+    # Rake tasks registration
+    def self.rake_tasks: () { () -> void } -> void
+  end
+
+  module Generators
+    class Base
+      # Class methods
+      def self.source_root: (String path) -> String
+      def self.desc: (String description) -> String
+      def self.argument: (Symbol name, ?type: Symbol, ?required: bool, ?default: untyped, ?desc: String) -> void
+      def self.class_option: (Symbol name, ?type: Symbol, ?default: untyped, ?desc: String) -> void
+
+      # Instance methods
+      def template: (String source, String destination) -> void
+      def create_file: (String path, String content) -> void
+      def readme: (String file) -> void
+      def say: (String message, ?Symbol color) -> void
+      def behavior: () -> Symbol
+      def options: () -> Hash[Symbol, untyped]
+    end
+  end
+
+  # Rails root
+  def self.root: () -> Pathname
+end
+
+# Pathname support for Rails.root
+class Pathname
+  def join: (*String | Pathname paths) -> Pathname
+  def to_s: () -> String
+end