better_translate 0.5.0 → 1.0.0

data/README.md

@@ -1,348 +1,733 @@
-# BetterTranslate 🌍
-
-[![Gem Version](https://badge.fury.io/rb/better_translate.svg)](https://badge.fury.io/rb/better_translate)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
-
-> 🚀 A powerful Ruby gem for seamless YAML file translations using AI providers like ChatGPT and Google Gemini
-
-BetterTranslate simplifies the translation of YAML files in your Ruby/Rails applications by leveraging advanced AI models. With support for both ChatGPT (OpenAI) and Google Gemini, it offers:
-
-✨ **Key Features**
-- 🔄 Smart translation modes (Override/Incremental)
-- 🎯 Precise key exclusion control
-- 📊 Real-time progress tracking
-- 🧪 Comprehensive test coverage
-- ⚡️ LRU caching for performance
-- 🔍 Translation similarity analysis
-- 📚 Extensive YARD documentation
-
-## Why BetterTranslate? 🤔
-
-- 🌐 **AI-Powered Translation**: Leverage ChatGPT, Google Gemini, and custom providers for high-quality translations
-- 🔄 **Smart Translation Modes**:
-  - `Override`: Full file rewrite
-  - `Incremental`: Update only new/modified keys
-- 🎯 **Precise Control**:
-  - Global key exclusions
-  - Language-specific exclusions
-  - Dot notation support
-- 🛠 **Developer-Friendly**:
-  - Rails generators included
-  - Custom provider support
-  - Comprehensive test suite
-  - LRU caching for performance
-  - Progress tracking
-  - Detailed YARD documentation
-- 🔍 **Translation Analysis**:
-  - Similarity detection
-  - Detailed reports
-  - Optimization suggestions
-- 🔧 **Flexible Helpers**:
-  - Single text translation
-  - Bulk text translation
-  - Multiple target languages support
-
-## Installation
-
-Add the gem to your Gemfile:
+# 🌍 BetterTranslate
+
+> AI-powered YAML locale file translator for Rails and Ruby projects
+
+[![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)
+
+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.
+
+**🎯 Why BetterTranslate?**
+- ✅ **Production-Ready**: Tested with real APIs via VCR cassettes (18 cassettes, 260KB)
+- ✅ **Interactive Demo**: Try it in 2 minutes with `ruby spec/dummy/demo_translation.rb`
+- ✅ **Variable Preservation**: `%{name}` placeholders maintained in translations
+- ✅ **Nested YAML Support**: Complex structures preserved perfectly
+- ✅ **Multiple Providers**: Choose ChatGPT, Gemini, or Claude
+
+| Provider | Model | Speed | Quality | Cost |
+|----------|-------|-------|---------|------|
+| **ChatGPT** | GPT-5-nano | ⚡⚡⚡ Fast | ⭐⭐⭐⭐⭐ Excellent | 💰💰 Medium |
+| **Gemini** | gemini-2.0-flash-exp | ⚡⚡⚡⚡ Very Fast | ⭐⭐⭐⭐ Very Good | 💰 Low |
+| **Claude** | Claude 3.5 | ⚡⚡ Medium | ⭐⭐⭐⭐⭐ Excellent | 💰💰💰 High |
+
+## ✨ Features
+
+### Core Translation Features
+- 🤖 **Multiple AI Providers**: Support for ChatGPT (GPT-5-nano), Google Gemini (gemini-2.0-flash-exp), and Anthropic Claude
+- ⚡ **Intelligent Caching**: LRU cache with optional TTL reduces API costs and speeds up repeated translations
+- 🔄 **Translation Modes**: Choose between override (replace entire files) or incremental (merge with existing translations)
+- 🎯 **Smart Strategies**: Automatic selection between deep translation (< 50 strings) and batch translation (≥ 50 strings)
+- 🚫 **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
+
+### Development & Quality
+- 🧪 **Comprehensive Testing**: Unit tests + integration tests with VCR cassettes (18 cassettes, 260KB)
+- 🎬 **Rails Dummy App**: Interactive demo with real translations (`ruby spec/dummy/demo_translation.rb`)
+- 🔒 **VCR Integration**: Record real API responses, test without API keys, CI/CD friendly
+- 🛡️ **Type-Safe Configuration**: Comprehensive validation with detailed error messages
+- 📚 **YARD Documentation**: Complete API documentation with examples
+- 🔁 **Retry Logic**: Exponential backoff for failed API calls (3 attempts, configurable)
+- 🚦 **Rate Limiting**: Thread-safe rate limiter prevents API overload
+
+## 🚀 Quick Start
+
+### Try It Now (Interactive Demo)
+
+Clone the repo and run the demo to see BetterTranslate in action:
+
+```bash
+git clone https://github.com/alessiobussolari/better_translate.git
+cd better_translate
+bundle install
+
+# Set your OpenAI API key
+export OPENAI_API_KEY=your_key_here
+
+# Run the demo!
+ruby spec/dummy/demo_translation.rb
+```
+
+**What happens:**
+- ✅ Reads `en.yml` with 16 translation keys
+- ✅ Translates to Italian and French using ChatGPT
+- ✅ Generates `it.yml` and `fr.yml` files
+- ✅ Shows progress, results, and sample translations
+- ✅ Takes ~2 minutes (real API calls)
+
+**Sample Output:**
+```yaml
+# en.yml (input)
+en:
+  hello: "Hello"
+  users:
+    greeting: "Hello %{name}"
+
+# it.yml (generated) ✅
+it:
+  hello: "Ciao"
+  users:
+    greeting: "Ciao %{name}"  # Variable preserved!
+
+# fr.yml (generated) ✅
+fr:
+  hello: "Bonjour"
+  users:
+    greeting: "Bonjour %{name}"  # Variable preserved!
+```
+
+See [`spec/dummy/USAGE_GUIDE.md`](spec/dummy/USAGE_GUIDE.md) for more examples.
+
+### Rails Integration
+
+```ruby
+# 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" },
+    { short_name: "es", name: "Spanish" }
+  ]
+
+  config.input_file = "config/locales/en.yml"
+  config.output_folder = "config/locales"
+
+  # Optional: Provide context for better translations
+  config.translation_context = "E-commerce application with product catalog"
+end
+
+# Translate all files
+BetterTranslate.translate_all
+```
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
 
 ```ruby
-gem 'better_translate', '~> 0.5.0'
+gem "better_translate"
 ```
 
-Then run:
+And then execute:
 
 ```bash
 bundle install
 ```
 
-Or install the gem manually:
+Or install it yourself as:
 
 ```bash
 gem install better_translate
 ```
 
-## Configuration
+### Rails Integration
 
-In a Rails application, generate the initializer by running:
+For Rails applications, generate the initializer:
 
 ```bash
 rails generate better_translate:install
 ```
 
-This command creates the file `config/initializers/better_translate.rb` with a default configuration. An example configuration is:
+This creates `config/initializers/better_translate.rb` with example configuration for all supported providers.
+
+## ⚙️ Configuration
+
+### Provider Setup
+
+#### ChatGPT (OpenAI)
 
 ```ruby
 BetterTranslate.configure do |config|
-  # Choose the provider to use: :chatgpt or :gemini
   config.provider = :chatgpt
-  
-  # API key for ChatGPT (OpenAI)
-  config.openai_key = ENV.fetch("OPENAI_API_KEY") { "YOUR_OPENAI_API_KEY" }
-  
-  # API key for Google Gemini
-  config.google_gemini_key = ENV.fetch("GOOGLE_GEMINI_KEY") { "YOUR_GOOGLE_GEMINI_KEY" }
-  
-  # Source language (e.g., "en" if the source file is in English)
-  config.source_language = "en"
-  
-  # Output folder where the translated files will be saved
-  config.output_folder = Rails.root.join("config", "locales", "translated").to_s
-  
-  # List of target languages (short_name and name)
-  config.target_languages = [
-    # Example:
-    { short_name: "it", name: "italian" }
-  ]
-  
-  # Global exclusions (keys in dot notation) to exclude from translation
-  config.global_exclusions = [
-    "key.child_key"
-  ]
-  
-  # Language-specific exclusions: keys to exclude only for specific target languages
-  config.exclusions_per_language = {
-    "es" => [],
-    "it" => ["sample.valid"],
-    "fr" => [],
-    "de" => [],
-    "pt" => [],
-    "ru" => []
-  }
-  
-  # Path to the input file (e.g., en.yml)
-  config.input_file = Rails.root.join("config", "locales", "en.yml").to_s
-  
-  # Translation mode: :override or :incremental
-  config.translation_mode = :override
+  config.openai_key = ENV["OPENAI_API_KEY"]
+
+  # Optional: customize model settings (defaults shown)
+  config.request_timeout = 30      # seconds
+  config.max_retries = 3
+  config.retry_delay = 2.0         # seconds
 end
 ```
 
-## Usage
+Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys).
 
-### Translating YAML Files
+#### Google Gemini
 
-To start the translation process, simply call the `magic` method:
+```ruby
+BetterTranslate.configure do |config|
+  config.provider = :gemini
+  config.google_gemini_key = ENV["GOOGLE_GEMINI_API_KEY"]
+
+  # Same optional settings as ChatGPT
+  config.request_timeout = 30
+  config.max_retries = 3
+end
+```
+
+Get your API key from [Google AI Studio](https://makersuite.google.com/app/apikey).
+
+#### Anthropic Claude
 
 ```ruby
-BetterTranslate.magic
+BetterTranslate.configure do |config|
+  config.provider = :anthropic
+  config.anthropic_key = ENV["ANTHROPIC_API_KEY"]
+
+  # Same optional settings
+  config.request_timeout = 30
+  config.max_retries = 3
+end
 ```
 
-This will execute the process that:
-1. Reads the input YAML file.
-2. Applies the global exclusion filtering.
-3. Applies additional language-specific exclusion filtering for each target language.
-4. Translates the strings from the source language into the configured target languages.
-5. Writes the translated files to the output folder, either in **override** or **incremental** mode based on the configuration.
+Get your API key from [Anthropic Console](https://console.anthropic.com/).
 
-### Using Rails Generators
+### Language Configuration
 
-The gem includes generators to simplify tasks:
+```ruby
+config.source_language = "en"  # ISO 639-1 code (2 letters)
 
-- **Generate Initializer:**
+config.target_languages = [
+  { short_name: "it", name: "Italian" },
+  { short_name: "fr", name: "French" },
+  { short_name: "de", name: "German" },
+  { short_name: "es", name: "Spanish" },
+  { short_name: "pt", name: "Portuguese" },
+  { short_name: "ja", name: "Japanese" },
+  { short_name: "zh", name: "Chinese" }
+]
+```
 
-  ```bash
-  rails generate better_translate:install
-  ```
+### File Paths
 
-- **Trigger Translation Process:**
+```ruby
+config.input_file = "config/locales/en.yml"       # Source file
+config.output_folder = "config/locales"            # Output directory
+```
 
-  ```bash
-  rails generate better_translate:translate
-  ```
+## 🎨 Features in Detail
 
-  The `better_translate:translate` generator will trigger the translation process (via `BetterTranslate.magic`) and display progress in the terminal.
+### Translation Modes
 
-- **Analyze Translations:**
+#### Override Mode (Default)
 
-  ```bash
-  rails generate better_translate:analyze
-  ```
+Replaces the entire target file with fresh translations:
 
-- **Create Custom Provider:**
+```ruby
+config.translation_mode = :override  # default
+```
 
-  ```bash
-  rails generate better_translate:provider YourProviderName
-  ```
+**Use when:** Starting fresh or regenerating all translations.
 
-  The `better_translate:analyze` generator will:
-  - Scan all YAML files in your locales directory
-  - Find similar translations using Levenshtein distance
-  - Generate two reports:
-    - `translation_similarities.json`: Detailed JSON report
-    - `translation_similarities_summary.txt`: Human-readable summary
-  
-  This helps you:
-  - Identify potentially redundant translations
-  - Maintain consistency across your translations
-  - Optimize your translation files
-  - Reduce translation costs
+#### Incremental Mode
 
-### Custom Translation Providers
+Merges with existing translations, only translating missing keys:
 
-BetterTranslate allows you to create and use custom translation providers, enabling integration with any translation API or service. This feature is particularly useful if you want to use a translation service not natively supported by BetterTranslate, such as DeepL, Microsoft Translator, Amazon Translate, or any other API-based translation service.
+```ruby
+config.translation_mode = :incremental
+```
 
-1. **Generate a custom provider template:**
+**Use when:** Preserving manual corrections or adding new keys to existing translations.
 
-   ```bash
-   rails generate better_translate:provider DeepL
-   ```
+### Caching System
 
-   This creates a new provider class in `app/providers/deep_l_provider.rb` and a README with implementation instructions.
+The LRU (Least Recently Used) cache stores translations to reduce API costs:
 
-2. **Implement the translation logic:**
+```ruby
+config.cache_enabled = true      # default: true
+config.cache_size = 1000         # default: 1000 items
+config.cache_ttl = 3600          # optional: 1 hour in seconds (nil = no expiration)
+```
 
-   Edit the generated provider file to implement the `translate_text` method with your API-specific code:
+**Cache key format:** `"#{text}:#{target_lang_code}"`
 
-   ```ruby
-   # app/providers/deep_l_provider.rb
-   module Providers
-     class DeepLProvider < BetterTranslate::Providers::BaseProvider
-       def initialize(api_key)
-         @api_key = api_key
-       end
+**Benefits:**
+- Reduces API costs for repeated translations
+- Speeds up re-runs during development
+- Thread-safe with Mutex protection
 
-       def translate_text(text, target_lang_code, target_lang_name)
-         # Implement your API call to DeepL here
-         # Return the translated text as a string
-       end
-     end
-   end
-   ```
+### Rate Limiting
 
-3. **Register your provider:**
+Prevent API overload with built-in rate limiting:
 
-   Create an initializer to register your custom provider:
+```ruby
+config.max_concurrent_requests = 3  # default: 3
+```
 
-   ```ruby
-   # config/initializers/better_translate_providers.rb
-   # Require the provider file to ensure it's loaded
-   require Rails.root.join('app', 'providers', 'deep_l_provider')
-   
-   BetterTranslate::Service.register_provider(
-     :deepl,
-     ->(api_key) { Providers::DeepLProvider.new(api_key) }
-   )
-   ```
-   
-   Note: The `require` statement is important to ensure the provider class is loaded before it's used.
+The rate limiter enforces a 0.5-second delay between requests by default. This is handled automatically by the `BaseHttpProvider`.
 
-4. **Update your configuration:**
+### Exclusion System
 
-   Add your API key to the BetterTranslate configuration:
+#### Global Exclusions
 
-   ```ruby
-   # config/initializers/better_translate.rb
-   BetterTranslate.configure do |config|
-     config.provider = :deepl
-     config.deepl_key = ENV['DEEPL_API_KEY']
-     # ... other configuration
-   end
-   ```
+Keys excluded from translation in **all** target languages (useful for brand names, product codes, etc.):
 
-5. **Use your custom provider:**
+```ruby
+config.global_exclusions = [
+  "app.name",              # "MyApp" should never be translated
+  "app.company",           # "ACME Inc." stays the same
+  "product.sku"            # "SKU-12345" is language-agnostic
+]
+```
+
+#### Language-Specific Exclusions
 
-   Your custom provider will now be used when you call `BetterTranslate.magic` or any other translation method.
+Keys excluded only for **specific** languages (useful for manually translated legal text, locale-specific content, etc.):
+
+```ruby
+config.exclusions_per_language = {
+  "it" => ["legal.terms", "legal.privacy"],  # Italian legal text manually reviewed
+  "de" => ["legal.terms", "legal.privacy"],  # German legal text manually reviewed
+  "fr" => ["marketing.slogan"]               # French slogan crafted by marketing team
+}
+```
+
+**Example:**
+- `legal.terms` is translated for Spanish, Portuguese, etc.
+- But excluded for Italian and German (already manually translated)
+
+### Translation Context
+
+Provide domain-specific context to improve translation accuracy:
+
+```ruby
+config.translation_context = "Medical terminology for healthcare applications"
+```
 
-6. **Troubleshooting:**
+This context is included in the AI system prompt, helping with specialized terminology in fields like:
 
-   If you encounter a `NameError` related to the `Providers` module, make sure the provider file is properly required in your initializer as shown in step 3. The `require` statement ensures that the provider class is loaded before it's used.
+- 🏥 **Medical/Healthcare**: "patient", "diagnosis", "treatment"
+- ⚖️ **Legal**: "plaintiff", "defendant", "liability"
+- 💰 **Financial**: "dividend", "amortization", "escrow"
+- 🛒 **E-commerce**: "checkout", "cart", "inventory"
+- 🔧 **Technical**: "API", "endpoint", "authentication"
 
-### Translation Helpers
+### Translation Strategies
 
-BetterTranslate provides helper methods to simplify translation tasks.
+BetterTranslate automatically selects the optimal strategy based on content size:
 
-#### Single Text Translation
+#### Deep Translation (< 50 strings)
+- Translates each string individually
+- Detailed progress tracking
+- Best for small to medium files
 
-The `translate_text_to_languages` helper allows you to translate a single text into multiple target languages in one call.
+#### Batch Translation (≥ 50 strings)
+- Processes in batches of 10 strings
+- Faster for large files
+- Reduced API overhead
 
-**Example Usage:**
+**You don't need to configure this** - it's automatic! 🎯
+
+## 🔧 Rails Integration
+
+BetterTranslate provides three Rails generators:
+
+### 1. Install Generator
+
+Generate the initializer with example configuration:
+
+```bash
+rails generate better_translate:install
+```
+
+Creates: `config/initializers/better_translate.rb`
+
+### 2. Translate Generator
+
+Run the translation process:
+
+```bash
+rails generate better_translate:translate
+```
+
+This triggers the translation based on your configuration and displays progress messages.
+
+### 3. Analyze Generator
+
+Analyze translation similarities using Levenshtein distance:
+
+```bash
+rails generate better_translate:analyze
+```
+
+**Output:**
+- Console summary with similar translation pairs
+- Detailed JSON report: `tmp/translation_similarity_report.json`
+- Human-readable summary: `tmp/translation_similarity_summary.txt`
+
+**Use cases:**
+- Identify potential translation inconsistencies
+- Find duplicate or near-duplicate translations
+- Quality assurance for translation output
+
+## 📝 Advanced Usage
+
+### Programmatic Translation
+
+#### Translate Multiple Texts to Multiple Languages
 
 ```ruby
-text = "Hello world!"
-target_languages = [
+texts = ["Hello", "Goodbye", "Thank you"]
+target_langs = [
   { short_name: "it", name: "Italian" },
   { short_name: "fr", name: "French" }
 ]
 
-translated = BetterTranslate::TranslationHelper.translate_text_to_languages(
-  text,
-  target_languages,
-  "en",       # source language code
-  :chatgpt    # provider: can be :chatgpt or :gemini
-)
+results = BetterTranslate::TranslationHelper.translate_texts_to_languages(texts, target_langs)
 
-puts translated
-# Expected output:
-# { "it" => "Ciao mondo!", "fr" => "Bonjour le monde!" }
+# Results structure:
+# {
+#   "it" => ["Ciao", "Arrivederci", "Grazie"],
+#   "fr" => ["Bonjour", "Au revoir", "Merci"]
+# }
 ```
 
-#### Multiple Texts Translation
-
-The `translate_texts_to_languages` helper extends the functionality to translate an array of texts into multiple target languages. It returns a hash where each key is a target language code and the value is an array of translated texts.
-
-**Example Usage:**
+#### Translate Single Text to Multiple Languages
 
 ```ruby
-texts = ["Hello world!", "How are you?"]
-target_languages = [
+text = "Welcome to our application"
+target_langs = [
   { short_name: "it", name: "Italian" },
-  { short_name: "fr", name: "French" }
+  { short_name: "es", name: "Spanish" }
 ]
 
-translated_texts = BetterTranslate::TranslationHelper.translate_texts_to_languages(
-  texts,
-  target_languages,
-  "en",       # source language code
-  :chatgpt    # provider: can be :chatgpt or :gemini
-)
+results = BetterTranslate::TranslationHelper.translate_text_to_languages(text, target_langs)
 
-puts translated_texts
-# Expected output:
+# Results:
 # {
-#   "it" => ["Ciao mondo!", "Come stai?"],
-#   "fr" => ["Bonjour le monde!", "Comment ça va?"]
+#   "it" => "Benvenuto nella nostra applicazione",
+#   "es" => "Bienvenido a nuestra aplicación"
 # }
 ```
 
-## Testing 🧪
+### Custom Configuration for Specific Tasks
+
+```ruby
+# Separate configuration for different domains
+medical_config = BetterTranslate::Configuration.new
+medical_config.provider = :chatgpt
+medical_config.openai_key = ENV["OPENAI_API_KEY"]
+medical_config.translation_context = "Medical terminology for patient records"
+medical_config.validate!
+
+# Use the custom config...
+```
+
+### Dry Run Mode
+
+Test your configuration without writing files:
+
+```ruby
+config.dry_run = true
+```
+
+This validates everything and simulates the translation process without creating output files.
+
+### Verbose Logging
 
-BetterTranslate comes with a comprehensive test suite using RSpec. To run the tests:
+Enable detailed logging for debugging:
+
+```ruby
+config.verbose = true
+```
+
+## 🧪 Development & Testing
+
+BetterTranslate includes comprehensive testing infrastructure with **unit tests**, **integration tests**, and a **Rails dummy app** for realistic testing.
+
+### Test Structure
+
+```
+spec/
+├── better_translate/           # Unit tests (fast, no API calls)
+│   ├── cache_spec.rb
+│   ├── configuration_spec.rb
+│   ├── providers/
+│   │   ├── chatgpt_provider_spec.rb
+│   │   └── gemini_provider_spec.rb
+│   └── ...
+│
+├── integration/                # Integration tests (real API via VCR)
+│   ├── chatgpt_integration_spec.rb
+│   ├── gemini_integration_spec.rb
+│   ├── rails_dummy_app_spec.rb
+│   └── README.md
+│
+├── dummy/                      # Rails dummy app for testing
+│   ├── config/
+│   │   └── locales/
+│   │       ├── en.yml         # Source file
+│   │       ├── it.yml         # Generated translations
+│   │       └── fr.yml
+│   ├── demo_translation.rb    # Interactive demo script
+│   └── USAGE_GUIDE.md
+│
+└── vcr_cassettes/              # Recorded API responses (18 cassettes, 260KB)
+    ├── chatgpt/ (7)
+    ├── gemini/ (7)
+    └── rails/ (4)
+```
+
+### Running Tests
 
 ```bash
+# Run all tests (unit + integration)
+bundle exec rake spec
+# or
 bundle exec rspec
+
+# Run only unit tests (fast, no API calls)
+bundle exec rspec spec/better_translate/
+
+# Run only integration tests (uses VCR cassettes)
+bundle exec rspec spec/integration/
+
+# Run specific test file
+bundle exec rspec spec/better_translate/configuration_spec.rb
+
+# Run tests with coverage
+bundle exec rspec --format documentation
+```
+
+### VCR Cassettes & API Testing
+
+BetterTranslate uses **VCR** (Video Cassette Recorder) to record real API interactions for integration tests. This allows:
+
+✅ **Realistic testing** with actual provider responses
+✅ **No API keys needed** after initial recording
+✅ **Fast test execution** (no real API calls)
+✅ **CI/CD friendly** (cassettes committed to repo)
+✅ **API keys anonymized** (safe to commit)
+
+#### Setup API Keys for Recording
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit .env and add your API keys
+OPENAI_API_KEY=sk-...
+GEMINI_API_KEY=...
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+#### Re-record Cassettes
+
+```bash
+# Delete and re-record all cassettes
+rm -rf spec/vcr_cassettes/
+bundle exec rspec spec/integration/
+
+# Re-record specific provider
+rm -rf spec/vcr_cassettes/chatgpt/
+bundle exec rspec spec/integration/chatgpt_integration_spec.rb
+```
+
+**Note**: The `.env` file is gitignored. API keys in cassettes are automatically replaced with `<OPENAI_API_KEY>`, `<GEMINI_API_KEY>`, etc.
+
+### Rails Dummy App Demo
+
+Test BetterTranslate with a realistic Rails app:
+
+```bash
+# Run interactive demo
+ruby spec/dummy/demo_translation.rb
+```
+
+**Output:**
+```
+🚀 Starting translation...
+[BetterTranslate] Italian | hello | 6.3%
+[BetterTranslate] Italian | world | 12.5%
+...
+✅ Success: 2 language(s)
+✓ it.yml generated (519 bytes)
+✓ fr.yml generated (511 bytes)
+```
+
+**Generated files:**
+- `spec/dummy/config/locales/it.yml` - Italian translation
+- `spec/dummy/config/locales/fr.yml` - French translation
+
+See [`spec/dummy/USAGE_GUIDE.md`](spec/dummy/USAGE_GUIDE.md) for more examples.
+
+### Code Quality
+
+```bash
+# Run RuboCop linter
+bundle exec rubocop
+
+# Auto-fix violations
+bundle exec rubocop -a
+
+# Run both tests and linter
+bundle exec rake
+```
+
+### Documentation
+
+```bash
+# Generate YARD documentation
+bundle exec yard doc
+
+# Start documentation server (http://localhost:8808)
+bundle exec yard server
+
+# Check documentation coverage
+bundle exec yard stats
 ```
 
-The test suite covers:
-- Core translation functionality
-- Cache implementation (LRU)
-- Provider selection and initialization
-- Error handling
-- Configuration management
+### Interactive Console
+
+```bash
+# Load the gem in an interactive console
+bin/console
+```
+
+### Security Audit
+
+```bash
+# Check for security vulnerabilities
+bundle exec bundler-audit check --update
+```
+
+## 🏗️ Architecture
+
+### Provider Architecture
+
+All providers inherit from `BaseHttpProvider`:
+
+```
+BaseHttpProvider (abstract)
+├── ChatGPTProvider
+├── GeminiProvider
+└── AnthropicProvider
+```
+
+**BaseHttpProvider responsibilities:**
+- HTTP communication via Faraday
+- Retry logic with exponential backoff
+- Rate limiting
+- Timeout handling
+- Error wrapping
+
+### Core Components
+
+- **Configuration**: Type-safe config with validation
+- **Cache**: LRU cache with optional TTL
+- **RateLimiter**: Thread-safe request throttling
+- **Validator**: Input validation (language codes, text, paths, keys)
+- **HashFlattener**: Converts nested YAML ↔ flat structure
 
-## Contributing 🤝
+### Error Hierarchy
+
+All errors inherit from `BetterTranslate::Error`:
+
+```
+BetterTranslate::Error
+├── ConfigurationError
+├── ValidationError
+├── TranslationError
+├── ProviderError
+├── ApiError
+├── RateLimitError
+├── FileError
+├── YamlError
+└── ProviderNotFoundError
+```
+
+## 📖 Documentation
+
+- **[USAGE_GUIDE.md](spec/dummy/USAGE_GUIDE.md)** - Complete guide to dummy app and demos
+- **[VCR Testing Guide](spec/integration/README.md)** - How to test with VCR cassettes
+- **[CLAUDE.md](CLAUDE.md)** - Developer guide for AI assistants (Claude Code)
+- **[YARD Docs](https://rubydoc.info/gems/better_translate)** - Complete API documentation
+
+### Key Documentation Files
+
+```
+better_translate/
+├── README.md                          # This file (main documentation)
+├── CLAUDE.md                          # Development guide (commands, architecture)
+├── spec/
+│   ├── dummy/
+│   │   ├── USAGE_GUIDE.md            # 📖 Interactive demo guide
+│   │   └── demo_translation.rb       # 🚀 Runnable demo script
+│   └── integration/
+│       └── README.md                  # 🧪 VCR testing guide
+└── docs/
+    └── implementation/                # Design docs
+```
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alessiobussolari/better_translate.
+
+### Development Guidelines
+
+1. **TDD (Test-Driven Development)**: Always write tests before implementing features
+2. **YARD Documentation**: Document all public methods with `@param`, `@return`, `@raise`, and `@example`
+3. **RuboCop Compliance**: Ensure code passes `bundle exec rubocop` before committing
+4. **Frozen String Literals**: Include `# frozen_string_literal: true` at the top of all files
+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
+
+```bash
+# 1. Clone and setup
+git clone https://github.com/alessiobussolari/better_translate.git
+cd better_translate
+bundle install
+
+# 2. Create a feature branch
+git checkout -b my-feature
+
+# 3. Write tests first (TDD)
+# Edit spec/better_translate/my_feature_spec.rb
+
+# 4. Implement the feature
+# Edit lib/better_translate/my_feature.rb
+
+# 5. Ensure tests pass and code is clean
+bundle exec rspec
+bundle exec rubocop
+
+# 6. Commit and push
+git add .
+git commit -m "Add my feature"
+git push origin my-feature
+
+# 7. Create a Pull Request
+```
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+## 📄 License
 
-## Contact & Support 📬
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-- **Email**: alessio.bussolari@pandev.it
-- **Issues**: [GitHub Issues](https://github.com/alessiobussolari/better_translate/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/alessiobussolari/better_translate/discussions)
+## 📜 Code of Conduct
 
-## License 📄
+Everyone interacting in the BetterTranslate project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
 
-This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
+---
 
-BetterTranslate aims to simplify the translation of YAML files in Ruby projects by providing a flexible, configurable, and extensible system. Whether you need a complete file rewrite or an incremental update, BetterTranslate streamlines the translation process using advanced providers like ChatGPT and Google Gemini. Contributions, feedback, and feature requests are highly encouraged to help improve the gem further.
+<div align="center">
 
-For more details, please visit the [GitHub repository](https://github.com/alessiobussolari/better_translate).
+**Made with ❤️ by [Alessio Bussolari](https://github.com/alessiobussolari)**
 
-## License
+[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)
 
-BetterTranslate is distributed under the MIT license. See the [LICENSE](LICENSE) file for more details.
+</div>