better_translate 1.0.0.1 → 1.1.1

data/CONTRIBUTING.md

@@ -0,0 +1,432 @@
+# Contributing to BetterTranslate
+
+First off, thank you for considering contributing to BetterTranslate! 🎉
+
+It's people like you that make BetterTranslate such a great tool. We welcome contributions from everyone, whether you're fixing a typo or implementing a major feature.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Testing](#testing)
+- [Code Style](#code-style)
+- [Commit Messages](#commit-messages)
+- [Pull Requests](#pull-requests)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## Getting Started
+
+### Prerequisites
+
+- Ruby >= 3.0.0
+- Bundler
+- Git
+
+### Fork and Clone
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/better_translate.git
+   cd better_translate
+   ```
+
+3. Add the upstream repository:
+   ```bash
+   git remote add upstream https://github.com/alessiobussolari/better_translate.git
+   ```
+
+### Install Dependencies
+
+```bash
+bundle install
+```
+
+### Set Up Environment
+
+1. Copy the example environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Add your API keys (optional, only needed for integration tests):
+   ```env
+   OPENAI_API_KEY=sk-...
+   GEMINI_API_KEY=...
+   ANTHROPIC_API_KEY=sk-ant-...
+   ```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+Always create a new branch for your work:
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Make Your Changes
+
+- Write clean, readable code
+- Follow the existing code style
+- Add tests for new features
+- Update documentation as needed
+
+### 3. Run Tests
+
+Before committing, make sure all tests pass:
+
+```bash
+# Run all tests
+bundle exec rake
+
+# Or run individual checks:
+bundle exec rake spec          # Tests
+bundle exec rake rubocop       # Linting
+bundle exec rake steep         # Type checking
+bundle exec rake brakeman      # Security scan
+```
+
+### 4. Commit Your Changes
+
+```bash
+git add .
+git commit -m "feat: Add awesome feature"
+```
+
+See [Commit Messages](#commit-messages) for guidelines.
+
+### 5. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a Pull Request on GitHub.
+
+## Testing
+
+### Test Structure
+
+- **Unit Tests**: `spec/better_translate/`
+  - Fast, no API calls
+  - Use WebMock for HTTP stubs
+
+- **Integration Tests**: `spec/integration/`
+  - Real API interactions via VCR
+  - Require API keys for first run
+  - Subsequent runs use recorded cassettes
+
+### Running Tests
+
+```bash
+# All tests
+bundle exec rspec
+
+# Only unit tests (fast)
+bundle exec rspec spec/better_translate/
+
+# Only integration tests
+bundle exec rspec spec/integration/ --tag integration
+
+# Specific file
+bundle exec rspec spec/better_translate/translator_spec.rb
+
+# Specific line
+bundle exec rspec spec/better_translate/translator_spec.rb:42
+```
+
+### Writing Tests
+
+**We follow Test-Driven Development (TDD)**:
+
+1. **RED**: Write a failing test
+2. **GREEN**: Write minimum code to pass
+3. **REFACTOR**: Clean up code
+
+Example:
+
+```ruby
+RSpec.describe MyNewFeature do
+  describe "#awesome_method" do
+    it "does something awesome" do
+      feature = MyNewFeature.new
+      result = feature.awesome_method
+
+      expect(result).to eq("awesome")
+    end
+  end
+end
+```
+
+### Test Coverage
+
+We maintain **93%+ test coverage**. New code should include tests:
+
+```bash
+# Check coverage
+bundle exec rspec
+# View coverage report: open coverage/index.html
+```
+
+## Code Style
+
+### RuboCop
+
+We use RuboCop for code style enforcement:
+
+```bash
+# Check style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+### Key Guidelines
+
+- Use double quotes for strings
+- 2 spaces for indentation (no tabs)
+- Maximum line length: 120 characters
+- Frozen string literals at top of files: `# frozen_string_literal: true`
+- YARD documentation for public methods
+
+### YARD Documentation
+
+All public methods must have YARD documentation:
+
+```ruby
+# Translates text to target language
+#
+# @param text [String] The text to translate
+# @param lang [String] Target language code (e.g., "it", "fr")
+# @return [String] Translated text
+# @raise [ValidationError] If input is invalid
+#
+# @example
+#   translate("Hello", "it") #=> "Ciao"
+#
+def translate(text, lang)
+  # ...
+end
+```
+
+### Type Checking
+
+We use Steep for static type checking:
+
+```bash
+# Run type checker
+bundle exec steep check
+
+# Check specific file
+bundle exec steep check lib/better_translate/translator.rb
+```
+
+Type signatures go in `sig/` directory (RBS format).
+
+## Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, no logic change)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+### Examples
+
+```bash
+# Good commits
+git commit -m "feat: Add support for JSON locale files"
+git commit -m "fix: Handle nil values in translations"
+git commit -m "docs: Update README with new examples"
+git commit -m "test: Add coverage for edge cases"
+
+# With scope
+git commit -m "feat(cli): Add --dry-run flag"
+git commit -m "fix(cache): Fix TTL expiration bug"
+```
+
+### Multi-line Commits
+
+For complex changes:
+
+```
+feat: Add parallel translation support
+
+- Implement thread-based concurrent execution
+- Add max_concurrent_requests configuration
+- Include progress tracking for parallel operations
+
+Closes #42
+```
+
+## Pull Requests
+
+### Before Submitting
+
+- [ ] Tests pass: `bundle exec rake`
+- [ ] Code follows style guide
+- [ ] YARD documentation added for public methods
+- [ ] CHANGELOG.md updated (for notable changes)
+- [ ] README.md updated (if needed)
+
+### PR Title
+
+Use conventional commit format:
+
+```
+feat: Add awesome feature
+fix: Resolve critical bug
+docs: Improve installation guide
+```
+
+### PR Description Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+How has this been tested?
+
+## Checklist
+- [ ] Tests pass locally
+- [ ] Tests added for new features
+- [ ] Documentation updated
+- [ ] No RuboCop offenses
+- [ ] No Brakeman warnings
+```
+
+### Review Process
+
+1. Automated checks run (CI/CD)
+2. Maintainer reviews code
+3. Address feedback if needed
+4. Maintainer merges PR
+
+## Reporting Bugs
+
+### Before Submitting
+
+- Check existing issues
+- Try latest version
+- Gather reproduction steps
+
+### Bug Report Template
+
+```markdown
+**Describe the bug**
+Clear description of the bug
+
+**To Reproduce**
+Steps to reproduce:
+1. ...
+2. ...
+3. ...
+
+**Expected behavior**
+What you expected to happen
+
+**Actual behavior**
+What actually happened
+
+**Environment**
+- Ruby version: [e.g., 3.3.4]
+- BetterTranslate version: [e.g., 1.1.0]
+- OS: [e.g., macOS, Ubuntu]
+
+**Additional context**
+Any other relevant information
+```
+
+## Suggesting Features
+
+We love feature suggestions! Open an issue with:
+
+```markdown
+**Feature Description**
+Clear description of the feature
+
+**Use Case**
+Why is this feature needed?
+
+**Proposed Solution**
+How should it work?
+
+**Alternatives Considered**
+Other approaches you've thought about
+
+**Additional Context**
+Screenshots, mockups, examples, etc.
+```
+
+## Development Commands
+
+```bash
+# Run all checks
+bundle exec rake
+
+# Individual checks
+bundle exec rake spec          # Tests (541 examples)
+bundle exec rake rubocop       # Linting
+bundle exec rake steep         # Type checking
+bundle exec rake brakeman      # Security scan
+
+# Code quality
+bundle exec rubocop -a         # Auto-fix style issues
+bundle exec yard doc           # Generate documentation
+bundle exec bundler-audit      # Check dependencies
+
+# Interactive console
+bin/console
+
+# Demo app
+ruby spec/dummy/demo_translation.rb
+```
+
+## Questions?
+
+Feel free to:
+- Open an issue
+- Start a discussion
+- Email: alessio.bussolari@pandev.it
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to BetterTranslate! 🚀

data/README.md

@@ -2,9 +2,15 @@
 
 > AI-powered YAML locale file translator for Rails and Ruby projects
 
+[![CI](https://github.com/alessiobussolari/better_translate/actions/workflows/main.yml/badge.svg)](https://github.com/alessiobussolari/better_translate/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/alessiobussolari/better_translate/branch/main/graph/badge.svg)](https://codecov.io/gh/alessiobussolari/better_translate)
+[![Gem Version](https://badge.fury.io/rb/better_translate.svg)](https://badge.fury.io/rb/better_translate)
+[![Downloads](https://img.shields.io/gem/dt/better_translate)](https://rubygems.org/gems/better_translate)
 [![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)
+[![Security](https://img.shields.io/badge/security-brakeman-green)](https://brakemanscanner.org/)
+[![Type Check](https://img.shields.io/badge/types-steep-blue)](https://github.com/soutaro/steep)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/alessiobussolari/better_translate/graphs/commit-activity)
 
 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 +37,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 +174,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 +214,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 +547,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.

data/Rakefile

@@ -15,4 +15,17 @@ task :steep do
   sh "bundle exec steep check"
 end
 
-task default: %i[spec rubocop steep]
+# Security scanning with Brakeman
+desc "Run security scanning with Brakeman"
+task :brakeman do
+  require "brakeman"
+  result = Brakeman.run(
+    app_path: ".",
+    print_report: true,
+    pager: false,
+    force_scan: true
+  )
+  exit Brakeman::Warnings_Found_Exit_Code unless result.filtered_warnings.empty?
+end
+
+task default: %i[spec rubocop steep brakeman]