better_translate 0.4.2 → 1.0.0

data/README.md

@@ -1,271 +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 and Google Gemini 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
-  - 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.4.2'
+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
+```
+
+Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys).
+
+#### Google Gemini
+
+```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.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
 ```
 
-## Usage
+Get your API key from [Anthropic Console](https://console.anthropic.com/).
+
+### Language Configuration
+
+```ruby
+config.source_language = "en"  # ISO 639-1 code (2 letters)
 
-### Translating YAML Files
+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" }
+]
+```
 
-To start the translation process, simply call the `magic` method:
+### File Paths
 
 ```ruby
-BetterTranslate.magic
+config.input_file = "config/locales/en.yml"       # Source file
+config.output_folder = "config/locales"            # Output directory
 ```
 
-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.
+## 🎨 Features in Detail
 
-### Using Rails Generators
+### Translation Modes
 
-The gem includes generators to simplify tasks:
+#### Override Mode (Default)
 
-- **Generate Initializer:**
+Replaces the entire target file with fresh translations:
 
-  ```bash
-  rails generate better_translate:install
-  ```
+```ruby
+config.translation_mode = :override  # default
+```
 
-- **Trigger Translation Process:**
+**Use when:** Starting fresh or regenerating all translations.
 
-  ```bash
-  rails generate better_translate:translate
-  ```
+#### Incremental Mode
 
-  The `better_translate:translate` generator will trigger the translation process (via `BetterTranslate.magic`) and display progress in the terminal.
+Merges with existing translations, only translating missing keys:
 
-- **Analyze Translations:**
+```ruby
+config.translation_mode = :incremental
+```
 
-  ```bash
-  rails generate better_translate:analyze
-  ```
+**Use when:** Preserving manual corrections or adding new keys to existing 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
+### Caching System
 
-### Translation Helpers
+The LRU (Least Recently Used) cache stores translations to reduce API costs:
+
+```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)
+```
 
-BetterTranslate provides helper methods to simplify translation tasks.
+**Cache key format:** `"#{text}:#{target_lang_code}"`
 
-#### Single Text Translation
+**Benefits:**
+- Reduces API costs for repeated translations
+- Speeds up re-runs during development
+- Thread-safe with Mutex protection
 
-The `translate_text_to_languages` helper allows you to translate a single text into multiple target languages in one call.
+### Rate Limiting
 
-**Example Usage:**
+Prevent API overload with built-in rate limiting:
 
 ```ruby
-text = "Hello world!"
-target_languages = [
-  { short_name: "it", name: "Italian" },
-  { short_name: "fr", name: "French" }
+config.max_concurrent_requests = 3  # default: 3
+```
+
+The rate limiter enforces a 0.5-second delay between requests by default. This is handled automatically by the `BaseHttpProvider`.
+
+### Exclusion System
+
+#### Global Exclusions
+
+Keys excluded from translation in **all** target languages (useful for brand names, product codes, etc.):
+
+```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
+
+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"
+```
+
+This context is included in the AI system prompt, helping with specialized terminology in fields like:
+
+- 🏥 **Medical/Healthcare**: "patient", "diagnosis", "treatment"
+- ⚖️ **Legal**: "plaintiff", "defendant", "liability"
+- 💰 **Financial**: "dividend", "amortization", "escrow"
+- 🛒 **E-commerce**: "checkout", "cart", "inventory"
+- 🔧 **Technical**: "API", "endpoint", "authentication"
+
+### Translation Strategies
+
+BetterTranslate automatically selects the optimal strategy based on content size:
+
+#### Deep Translation (< 50 strings)
+- Translates each string individually
+- Detailed progress tracking
+- Best for small to medium files
+
+#### Batch Translation (≥ 50 strings)
+- Processes in batches of 10 strings
+- Faster for large files
+- Reduced API overhead
+
+**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.
 
-translated = BetterTranslate::TranslationHelper.translate_text_to_languages(
-  text,
-  target_languages,
-  "en",       # source language code
-  :chatgpt    # provider: can be :chatgpt or :gemini
-)
+### 3. Analyze Generator
 
-puts translated
-# Expected output:
-# { "it" => "Ciao mondo!", "fr" => "Bonjour le monde!" }
+Analyze translation similarities using Levenshtein distance:
+
+```bash
+rails generate better_translate:analyze
 ```
 
-#### Multiple Texts Translation
+**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
 
-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.
+### Programmatic Translation
 
-**Example Usage:**
+#### Translate Multiple Texts to Multiple Languages
 
 ```ruby
-texts = ["Hello world!", "How are you?"]
-target_languages = [
+texts = ["Hello", "Goodbye", "Thank you"]
+target_langs = [
   { short_name: "it", name: "Italian" },
   { short_name: "fr", name: "French" }
 ]
 
-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_texts_to_languages(texts, target_langs)
 
-puts translated_texts
-# Expected output:
+# Results structure:
 # {
-#   "it" => ["Ciao mondo!", "Come stai?"],
-#   "fr" => ["Bonjour le monde!", "Comment ça va?"]
+#   "it" => ["Ciao", "Arrivederci", "Grazie"],
+#   "fr" => ["Bonjour", "Au revoir", "Merci"]
 # }
 ```
 
-## Testing 🧪
+#### Translate Single Text to Multiple Languages
+
+```ruby
+text = "Welcome to our application"
+target_langs = [
+  { short_name: "it", name: "Italian" },
+  { short_name: "es", name: "Spanish" }
+]
+
+results = BetterTranslate::TranslationHelper.translate_text_to_languages(text, target_langs)
+
+# Results:
+# {
+#   "it" => "Benvenuto nella nostra applicazione",
+#   "es" => "Bienvenido a nuestra aplicación"
+# }
+```
+
+### 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
+
+Enable detailed logging for debugging:
+
+```ruby
+config.verbose = true
+```
+
+## 🧪 Development & Testing
 
-BetterTranslate comes with a comprehensive test suite using RSpec. To run the tests:
+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
+```
+
+### 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
+
+### 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
 ```
 
-The test suite covers:
-- Core translation functionality
-- Cache implementation (LRU)
-- Provider selection and initialization
-- Error handling
-- Configuration management
+## 🤝 Contributing
 
-## 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>