better_translate 1.0.0 → 1.1.0

data/README.md

@@ -4,7 +4,7 @@
 
 [![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-ruby.svg)](https://www.ruby-lang.org/en/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
-[![Gem Version](https://img.shields.io/badge/version-1.0.0-green.svg)](https://rubygems.org/gems/better_translate)
+[![Gem Version](https://img.shields.io/badge/version-1.1.0-green.svg)](https://rubygems.org/gems/better_translate)
 
 BetterTranslate automatically translates your YAML locale files using cutting-edge AI providers (ChatGPT, Google Gemini, and Anthropic Claude). It's designed for Rails applications but works with any Ruby project that uses YAML-based internationalization.
 
@@ -31,6 +31,14 @@ BetterTranslate automatically translates your YAML locale files using cutting-ed
 - 🚫 **Flexible Exclusions**: Global exclusions for all languages + language-specific exclusions for fine-grained control
 - 🎨 **Translation Context**: Provide domain-specific context for medical, legal, financial, or technical terminology
 - 📊 **Similarity Analysis**: Built-in Levenshtein distance analyzer to identify similar translations
+- 🔍 **Orphan Key Analyzer**: Find unused translation keys in your codebase with comprehensive reports (text, JSON, CSV)
+
+### New in v1.1.0 🎉
+- 🎛️ **Provider-Specific Options**: Fine-tune AI behavior with `model`, `temperature`, and `max_tokens`
+- 💾 **Automatic Backups**: Configurable backup rotation before overwriting files (`.bak`, `.bak.1`, `.bak.2`)
+- 📦 **JSON Support**: Full support for JSON locale files (React, Vue, modern JS frameworks)
+- ⚡ **Parallel Translation**: Translate multiple languages concurrently with thread-based execution
+- 📁 **Multiple Files**: Translate multiple files with arrays or glob patterns (`**/*.en.yml`)
 
 ### Development & Quality
 - 🧪 **Comprehensive Testing**: Unit tests + integration tests with VCR cassettes (18 cassettes, 260KB)
@@ -160,6 +168,11 @@ BetterTranslate.configure do |config|
   config.request_timeout = 30      # seconds
   config.max_retries = 3
   config.retry_delay = 2.0         # seconds
+
+  # 🆕 v1.1.0: Provider-specific options
+  config.model = "gpt-5-nano"      # Specify model (optional)
+  config.temperature = 0.3         # Creativity (0.0-2.0, default: 0.3)
+  config.max_tokens = 2000         # Response length limit
 end
 ```
 
@@ -195,6 +208,90 @@ end
 
 Get your API key from [Anthropic Console](https://console.anthropic.com/).
 
+### New Features (v1.1.0)
+
+#### Automatic Backups
+
+Protect your translation files with automatic backup creation:
+
+```ruby
+config.create_backup = true    # Enable backups (default: true)
+config.max_backups = 5          # Keep up to 5 backup versions
+```
+
+Backup files are created with rotation:
+- First backup: `it.yml.bak`
+- Second backup: `it.yml.bak.1`
+- Third backup: `it.yml.bak.2`
+- Older backups are automatically deleted
+
+#### JSON File Support
+
+Translate JSON locale files for modern JavaScript frameworks:
+
+```ruby
+# Automatically detects JSON format from file extension
+config.input_file = "config/locales/en.json"
+config.output_folder = "config/locales"
+
+# All features work with JSON: backups, incremental mode, exclusions, etc.
+```
+
+Example JSON file:
+```json
+{
+  "en": {
+    "common": {
+      "greeting": "Hello %{name}"
+    }
+  }
+}
+```
+
+#### Parallel Translation
+
+Translate multiple languages concurrently for faster processing:
+
+```ruby
+config.target_languages = [
+  { short_name: "it", name: "Italian" },
+  { short_name: "fr", name: "French" },
+  { short_name: "es", name: "Spanish" },
+  { short_name: "de", name: "German" }
+]
+
+config.max_concurrent_requests = 4  # Translate 4 languages at once
+```
+
+**Performance improvement:** With 4 languages and `max_concurrent_requests = 4`, translation time is reduced by ~75% compared to sequential processing.
+
+#### Multiple Files Support
+
+Translate multiple files in a single run:
+
+```ruby
+# Array of specific files
+config.input_files = [
+  "config/locales/common.en.yml",
+  "config/locales/errors.en.yml",
+  "config/locales/admin.en.yml"
+]
+
+# Or use glob patterns (recommended)
+config.input_files = "config/locales/**/*.en.yml"
+
+# Or combine both approaches
+config.input_files = [
+  "config/locales/**/*.en.yml",
+  "app/javascript/translations/*.en.json"
+]
+```
+
+Output files preserve the original structure:
+- `common.en.yml` → `common.it.yml`
+- `errors.en.yml` → `errors.it.yml`
+- `admin/settings.en.yml` → `admin/settings.it.yml`
+
 ### Language Configuration
 
 ```ruby
@@ -444,6 +541,142 @@ Enable detailed logging for debugging:
 config.verbose = true
 ```
 
+## 🔍 Orphan Key Analyzer
+
+The Orphan Key Analyzer helps you find unused translation keys in your codebase. It scans your YAML locale files and compares them against your actual code usage, generating comprehensive reports.
+
+### CLI Usage
+
+Find orphan keys from the command line:
+
+```bash
+# Basic text report (default)
+better_translate analyze \
+  --source config/locales/en.yml \
+  --scan-path app/
+
+# JSON format (great for CI/CD)
+better_translate analyze \
+  --source config/locales/en.yml \
+  --scan-path app/ \
+  --format json
+
+# CSV format (easy to share with team)
+better_translate analyze \
+  --source config/locales/en.yml \
+  --scan-path app/ \
+  --format csv
+
+# Save to file
+better_translate analyze \
+  --source config/locales/en.yml \
+  --scan-path app/ \
+  --output orphan_report.txt
+```
+
+### Sample Output
+
+**Text format:**
+```
+============================================================
+Orphan Keys Analysis Report
+============================================================
+
+Statistics:
+  Total keys: 50
+  Used keys: 45
+  Orphan keys: 5
+  Usage: 90.0%
+
+Orphan Keys (5):
+------------------------------------------------------------
+
+  Key: users.old_message
+  Value: This feature was removed
+
+  Key: products.deprecated_label
+  Value: Old Label
+...
+============================================================
+```
+
+**JSON format:**
+```json
+{
+  "orphans": ["users.old_message", "products.deprecated_label"],
+  "orphan_details": {
+    "users.old_message": "This feature was removed",
+    "products.deprecated_label": "Old Label"
+  },
+  "orphan_count": 5,
+  "total_keys": 50,
+  "used_keys": 45,
+  "usage_percentage": 90.0
+}
+```
+
+### Programmatic Usage
+
+Use the analyzer in your Ruby code:
+
+```ruby
+# Scan YAML file
+key_scanner = BetterTranslate::Analyzer::KeyScanner.new("config/locales/en.yml")
+all_keys = key_scanner.scan  # Returns Hash of all keys
+
+# Scan code for used keys
+code_scanner = BetterTranslate::Analyzer::CodeScanner.new("app/")
+used_keys = code_scanner.scan  # Returns Set of used keys
+
+# Detect orphans
+detector = BetterTranslate::Analyzer::OrphanDetector.new(all_keys, used_keys)
+orphans = detector.detect
+
+# Get statistics
+puts "Orphan count: #{detector.orphan_count}"
+puts "Usage: #{detector.usage_percentage}%"
+
+# Generate report
+reporter = BetterTranslate::Analyzer::Reporter.new(
+  orphans: orphans,
+  orphan_details: detector.orphan_details,
+  total_keys: all_keys.size,
+  used_keys: used_keys.size,
+  usage_percentage: detector.usage_percentage,
+  format: :text
+)
+
+puts reporter.generate
+reporter.save_to_file("orphan_report.txt")
+```
+
+### Supported Translation Patterns
+
+The analyzer recognizes these i18n patterns:
+
+- `t('key')` - Rails short form
+- `t("key")` - Rails short form with double quotes
+- `I18n.t(:key)` - Symbol syntax
+- `I18n.t('key')` - String syntax
+- `I18n.translate('key')` - Full method name
+- `<%= t('key') %>` - ERB templates
+- `I18n.t('key', param: value)` - With parameters
+
+**Nested keys:**
+```yaml
+en:
+  users:
+    profile:
+      title: "Profile"  # Detected as: users.profile.title
+```
+
+**Use cases:**
+- Clean up unused translations before deployment
+- Identify dead code after refactoring
+- Reduce locale file size
+- Improve translation maintenance
+- Generate reports for translation teams
+
 ## 🧪 Development & Testing
 
 BetterTranslate includes comprehensive testing infrastructure with **unit tests**, **integration tests**, and a **Rails dummy app** for realistic testing.
@@ -685,7 +918,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/alessi
 5. **HTTP Client**: Use Faraday for all HTTP requests (never Net::HTTP or HTTParty)
 6. **VCR Cassettes**: Record integration tests with real API responses for CI/CD
 
-### Workflow
+### Development Workflow
 
 ```bash
 # 1. Clone and setup
@@ -714,6 +947,33 @@ git push origin my-feature
 # 7. Create a Pull Request
 ```
 
+### Release Workflow
+
+Releases are automated via GitHub Actions:
+
+```bash
+# 1. Update version
+vim lib/better_translate/version.rb  # VERSION = "1.0.1"
+
+# 2. Update CHANGELOG
+vim CHANGELOG.md
+
+# 3. Commit and tag
+git add -A
+git commit -m "chore: Release v1.0.1"
+git tag v1.0.1
+git push origin main
+git push origin v1.0.1
+
+# 4. GitHub Actions automatically:
+#    ✅ Runs tests
+#    ✅ Builds gem
+#    ✅ Publishes to RubyGems.org
+#    ✅ Creates GitHub Release
+```
+
+**Setup**: See [`.github/RUBYGEMS_SETUP.md`](.github/RUBYGEMS_SETUP.md) for configuring RubyGems trusted publishing (no API keys needed!).
+
 ## 📄 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/RELEASE_NOTES_v1.0.0.md

@@ -0,0 +1,240 @@
+# BetterTranslate v1.0.0 - Complete Release 🎉
+
+**AI-powered YAML locale file translator for Rails and Ruby projects**
+
+This is the first complete release of BetterTranslate, featuring multi-provider AI translation support, comprehensive testing infrastructure, and production-ready features.
+
+## 🚀 Quick Start
+
+```bash
+# Install the gem
+gem install better_translate
+
+# Try the interactive demo
+git clone https://github.com/alessiobussolari/better_translate.git
+cd better_translate
+bundle install
+export OPENAI_API_KEY=your_key_here
+ruby spec/dummy/demo_translation.rb
+```
+
+## ✨ Key Features
+
+### Multi-Provider AI Support
+- **ChatGPT** (GPT-5-nano) - Fast, excellent quality
+- **Google Gemini** (gemini-2.0-flash-exp) - Very fast, cost-effective
+- **Anthropic Claude** (Claude 3.5) - Excellent quality (coming soon)
+
+### Translation Features
+- 🎯 **Smart Strategies**: Automatic selection between deep (<50 strings) and batch (≥50 strings) translation
+- ⚡ **Intelligent Caching**: LRU cache with optional TTL reduces API costs
+- 🔄 **Translation Modes**: Override (replace all) or Incremental (merge with existing)
+- 🚫 **Flexible Exclusions**: Global + language-specific exclusion rules
+- 🎨 **Domain Context**: Provide context for medical, legal, financial, or technical terminology
+- 📊 **Similarity Analysis**: Built-in Levenshtein distance analyzer
+
+### Production-Ready Quality
+- 🧪 **259 Tests** passing with 90%+ coverage
+- 🎬 **VCR Integration**: 18 cassettes (260KB) with real API responses
+- 🏗️ **Rails Dummy App**: Interactive demo with real translations
+- 📚 **Complete Documentation**: README, YARD docs, usage guides
+- 🛡️ **Type-Safe**: RBS signatures with Steep type checking
+- ✅ **RuboCop Compliant**: Clean, consistent code style
+
+### Rails Integration
+```bash
+# Generate initializer
+rails generate better_translate:install
+
+# Configure in config/initializers/better_translate.rb
+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"
+end
+
+# Translate all files
+BetterTranslate.translate_all
+```
+
+## 📖 Documentation
+
+- **[README.md](README.md)** - Complete feature documentation
+- **[USAGE_GUIDE.md](spec/dummy/USAGE_GUIDE.md)** - Interactive demo guide
+- **[VCR Testing Guide](spec/integration/README.md)** - Integration testing with VCR
+- **[CLAUDE.md](CLAUDE.md)** - Developer guide for contributors
+- **[CHANGELOG.md](CHANGELOG.md)** - Detailed changelog
+
+## 🎬 Demo Output
+
+```yaml
+# en.yml (input)
+en:
+  hello: "Hello"
+  users:
+    greeting: "Hello %{name}"
+  messages:
+    success: "Operation completed successfully"
+
+# it.yml (generated by BetterTranslate)
+it:
+  hello: "Ciao"
+  users:
+    greeting: "Ciao %{name}"  # ✅ Variables preserved!
+  messages:
+    success: "Operazione completata con successo"
+
+# fr.yml (generated by BetterTranslate)
+fr:
+  hello: "Bonjour"
+  users:
+    greeting: "Bonjour %{name}"  # ✅ Variables preserved!
+  messages:
+    success: "Opération réussie"
+```
+
+## 🏗️ Architecture Highlights
+
+### Provider Architecture
+```
+BaseHttpProvider (abstract)
+├── ChatGPTProvider (GPT-5-nano, temp=1.0)
+├── GeminiProvider (gemini-2.0-flash-exp)
+└── AnthropicProvider (coming soon)
+```
+
+**BaseHttpProvider features:**
+- Faraday-based HTTP communication
+- Retry logic with exponential backoff (3 attempts)
+- Rate limiting (0.5s between requests, thread-safe)
+- Configurable timeouts (default: 30s)
+
+### Core Components
+- **Configuration**: Type-safe config with validation
+- **Cache**: Thread-safe LRU cache with optional TTL
+- **RateLimiter**: Thread-safe request throttling
+- **Validator**: Comprehensive input validation
+- **HashFlattener**: Nested YAML ↔ flat structure conversion
+- **VariableExtractor**: Preserves `%{name}` and `%<name>s` placeholders
+- **ProgressTracker**: Real-time translation progress
+
+### Error Hierarchy
+```
+BetterTranslate::Error (base)
+├── ConfigurationError
+├── ValidationError
+├── TranslationError
+├── ProviderError
+├── ApiError
+├── RateLimitError
+├── FileError
+├── YamlError
+└── ProviderNotFoundError
+```
+
+## 🧪 Testing Infrastructure
+
+```
+spec/
+├── better_translate/           # 259 unit tests
+│   ├── cache_spec.rb
+│   ├── providers/
+│   └── ...
+├── integration/                # VCR integration tests
+│   ├── chatgpt_integration_spec.rb
+│   ├── gemini_integration_spec.rb
+│   └── rails_dummy_app_spec.rb
+├── dummy/                      # Rails dummy app
+│   ├── demo_translation.rb     # 🚀 Interactive demo
+│   └── config/locales/
+│       ├── en.yml              # Source (16 keys)
+│       ├── it.yml              # Generated (519 bytes)
+│       └── fr.yml              # Generated (511 bytes)
+└── vcr_cassettes/              # 18 cassettes (260KB)
+    ├── chatgpt/ (7)
+    ├── gemini/ (7)
+    └── rails/ (4)
+```
+
+## 📦 Package Details
+
+- **Gem Name**: `better_translate`
+- **Version**: `1.0.0`
+- **Size**: 83KB
+- **Files**: 152 files
+- **Lines of Code**: 23,654
+- **Ruby Version**: >= 3.0.0
+- **Dependencies**: Faraday ~> 2.0 (only runtime dependency)
+
+## 🔧 Configuration Examples
+
+### Medical Terminology
+```ruby
+config.translation_context = "Medical terminology for healthcare applications"
+config.target_languages = [{ short_name: "es", name: "Spanish" }]
+# "patient" → "paciente", "diagnosis" → "diagnóstico"
+```
+
+### E-commerce with Exclusions
+```ruby
+config.global_exclusions = ["brand_name", "sku"]  # Never translate
+config.exclusions_per_language = {
+  "de" => ["legal.terms"],  # German legal terms manually translated
+  "fr" => ["marketing.slogan"]  # French slogan crafted by marketing
+}
+```
+
+### Incremental Mode
+```ruby
+config.translation_mode = :incremental
+# Only translates missing keys, preserves manual corrections
+```
+
+## 🚦 Performance
+
+**Demo Results** (16 keys, 2 languages):
+- Italian: 16 strings in 1m 6s (~4s per string)
+- French: 16 strings in 1m 7s (~4s per string)
+- **Total**: 32 translations in 2m 13s
+
+**With Caching Enabled**:
+- Subsequent runs: < 1s (cache hits)
+- API costs reduced by ~90%
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see [CLAUDE.md](CLAUDE.md) for development guidelines.
+
+**Development Requirements**:
+1. TDD (Test-Driven Development) - Write tests first
+2. YARD Documentation - Document all public methods
+3. RuboCop Compliance - Clean code style
+4. VCR Cassettes - Record integration tests
+
+## 📜 License
+
+MIT License - See [LICENSE.txt](LICENSE.txt)
+
+## 🙏 Acknowledgments
+
+Built with:
+- **Faraday** - HTTP client
+- **VCR** - HTTP interaction recording
+- **RSpec** - Testing framework
+- **RuboCop** - Code linting
+- **Steep** - Type checking
+- **YARD** - Documentation
+
+---
+
+**Made with ❤️ by [Alessio Bussolari](https://github.com/alessiobussolari)**
+
+**Powered by Claude Code** 🤖
+
+[Report Bug](https://github.com/alessiobussolari/better_translate/issues) · [Request Feature](https://github.com/alessiobussolari/better_translate/issues) · [Documentation](https://github.com/alessiobussolari/better_translate)

data/Steepfile

@@ -6,8 +6,8 @@
 D = Steep::Diagnostic
 
 target :lib do
-  # Specify Ruby version
-  check "lib"
+  # Only check library files
+  check "lib/**/*.rb"
 
   # Signature files location
   signature "sig"

data/docs/implementation/00-overview.md

@@ -14,7 +14,7 @@ BetterTranslate is a powerful Ruby gem designed to automatically translate YAML
 
 ### Key Features
 
-- **Multiple AI Providers**: ChatGPT (GPT-5-nano), Google Gemini (gemini-2.0-flash-exp), Anthropic Claude (claude-3-5-sonnet-20241022)
+- **Multiple AI Providers**: ChatGPT (GPT-5-nano), Google Gemini (gemini-2.5-flash-lite), Anthropic Claude (claude-haiku-4-5)
 - **Smart Translation Strategies**: Automatic selection between Deep (< 50 strings) and Batch (≥ 50 strings) processing
 - **Intelligent Caching**: LRU cache with configurable capacity and TTL
 - **Rails Integration**: 3 generators (install, translate, analyze)

data/docs/implementation/04-provider_architecture.md

@@ -331,10 +331,10 @@ module BetterTranslate
   module Providers
     # Google Gemini translation provider
     #
-    # Uses gemini-2.0-flash-exp model
+    # Uses gemini-2.5-flash-lite model
     class GeminiProvider < BaseHttpProvider
-      API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent"
-      MODEL = "gemini-2.0-flash-exp"
+      API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent"
+      MODEL = "gemini-2.5-flash-lite"
 
       # Translate a single text
       #
@@ -431,10 +431,10 @@ module BetterTranslate
   module Providers
     # Anthropic Claude translation provider
     #
-    # Uses claude-3-5-sonnet-20241022 model
+    # Uses claude-haiku-4-5 model
     class AnthropicProvider < BaseHttpProvider
       API_URL = "https://api.anthropic.com/v1/messages"
-      MODEL = "claude-3-5-sonnet-20241022"
+      MODEL = "claude-haiku-4-5"
       API_VERSION = "2023-06-01"
 
       # Translate a single text