mistral_translator 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73a244fe12fa2b20b8541ae5fda6ad872072b39494a4df7898eeaef52463ecda
-  data.tar.gz: d2542178c4b3bea537b3d2737341809457141fea38f3a6354c7ccf6c0feb86e2
+  metadata.gz: 1736f848f5877e51c319bb4584e110e863a6e44464af7f05133d3ea2e2f96fd6
+  data.tar.gz: bd06e5e900f129e662fb2ca90b5c241e55ac86511710d7c4f0cc373fca6c4c2c
 SHA512:
-  metadata.gz: 4c307437bb32492e4a428eb1f37b868306e48f9c90229aab59565226199c322a8a142ecb41da83ce5c99d6c807c47dc85281ee4e2b09a51870cdba72405ed94e
-  data.tar.gz: aa2153e0a4f70459e2983c13c4cb529e836aff7262cc7d9411b9a43c685a105a47ba9961180188f87fe84eb6b7dd2563da6c653611ab4e843a5eeb032f738159
+  metadata.gz: 3f57b5f9652c5b8327de801d5e391eb41f3c6915a9d4551e4ee57a2a61369ead60cffe1c72a5a35ccf089f23401d41d5685480331fe97786d9af7a661c303349
+  data.tar.gz: 672f5aa7932401c2bae6c2ced94058d60ffb6dfab3fb5d6760896f61ed26e5f4eef7b2491697d6680e544b97612f774b4f6fed95b66d0127984d1863592e1509

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-09-09
+
+### Added
+
+- Contexte et glossaire via `MistralTranslator::Translator#translate`
+- Rate limiting client (50 req/min par défaut, thread-safe)
+- Validation basique des entrées (max 50k chars, batch ≤ 20)
+- Nouvelles erreurs: `SecurityError`, `RateLimitExceededError`
+- Métriques intégrées et callbacks de monitoring
+- Documentation mise à jour + guide de migration 0.1.0 → 0.2.0
+
+### Changed
+
+- Exemples et docs: utilisation d’une instance `Translator` pour `context`/`glossary`
+- Amélioration de la structure interne (client/translator/summarizer)
+
+### Fixed
+
+- Masquage renforcé des secrets dans VCR
+- Messages d’erreurs plus explicites pour les réponses invalides
+
 ## [0.1.0] - 2025-09-01
 
 - Initial release

data/README.md

@@ -1,205 +1,273 @@
 # MistralTranslator
 
-Une gem Ruby pour traduire et résumer du texte en utilisant l'API Mistral AI.
+Ruby gem for AI-powered translation and text summarization using Mistral AI API, with advanced Rails support.
 
-## Installation
+[![Gem Version](https://badge.fury.io/rb/mistral_translator.svg)](https://badge.fury.io/rb/mistral_translator)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Ajoutez cette ligne à votre Gemfile :
+## Quick Start
 
 ```ruby
+# Installation
 gem 'mistral_translator'
+
+# Configuration
+MistralTranslator.configure do |config|
+  config.api_key = ENV['MISTRAL_API_KEY']
+end
+
+# Basic usage
+MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
+# => "Hello world"
 ```
 
-Puis exécutez :
+## Key Features
 
-```bash
-bundle install
+- **Smart translation** with context and custom glossaries
+- **Native Rails integration** (Mobility, Globalize, I18n attributes)
+- **Batch processing** for high-volume translations
+- **Multi-level summarization** with translation
+- **Robust error handling** with automatic retry and fallback
+- **Complete monitoring** with metrics and callbacks
+- **Asynchronous jobs** for background processing
+- **Built-in rate limiting** and security
+
+## Supported Languages
+
+`fr` `en` `es` `pt` `de` `it` `nl` `ru` `mg` `ja` `ko` `zh` `ar`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mistral_translator'
 ```
 
-Ou installez directement :
+Then run:
 
 ```bash
-gem install mistral_translator
+bundle install
 ```
 
-## Configuration
+### API Key Setup
+
+Get your API key from [Mistral AI Console](https://console.mistral.ai/) and configure it:
 
 ```ruby
-require 'mistral_translator'
+# Environment variable (recommended)
+export MISTRAL_API_KEY="your_api_key_here"
 
+# Or in Rails config/initializers/mistral_translator.rb
 MistralTranslator.configure do |config|
-  config.api_key = 'votre_clé_api_mistral'
-  config.api_url = 'https://api.mistral.ai'  # optionnel
-  config.model = 'mistral-small'             # optionnel
+  config.api_key = ENV['MISTRAL_API_KEY']
+  config.enable_metrics = Rails.env.production?
 end
 ```
 
-### Variables d'environnement
+## Basic Usage Examples
 
-Vous pouvez aussi utiliser des variables d'environnement :
-
-```bash
-export MISTRAL_API_KEY=votre_clé_api
-export MISTRAL_API_URL=https://api.mistral.ai
-```
-
-## Utilisation
-
-### Traduction simple
+### Simple Translation
 
 ```ruby
-# Traduction de base
-result = MistralTranslator.translate("Bonjour le monde", from: 'fr', to: 'en')
-# => "Hello world"
+# Basic translation
+result = MistralTranslator.translate("Bonjour", from: "fr", to: "en")
+# => "Hello"
 
-# Vers plusieurs langues
-results = MistralTranslator.translate_to_multiple(
-  "Bonjour le monde", 
-  from: 'fr', 
-  to: ['en', 'es', 'de']
+# With context for better accuracy
+result = MistralTranslator.translate(
+  "Le produit est disponible",
+  from: "fr",
+  to: "en",
+  context: "E-commerce website"
 )
-# => { 'en' => "Hello world", 'es' => "Hola mundo", 'de' => "Hallo Welt" }
+# => "The product is available"
+
+# With custom glossary
+result = MistralTranslator.translate(
+  "Notre API est performante",
+  from: "fr",
+  to: "en",
+  glossary: { "API" => "API" }  # Preserve technical terms
+)
+# => "Our API is high-performing"
 ```
 
-### Traduction en lot
+### Auto-Detection
 
 ```ruby
-texts = ["Bonjour", "Au revoir", "Merci"]
-results = MistralTranslator.translate_batch(texts, from: 'fr', to: 'en')
-# => { 0 => "Hello", 1 => "Goodbye", 2 => "Thank you" }
+# Automatic source language detection
+MistralTranslator.translate_auto("¡Hola mundo!", to: "fr")
+# => "Salut le monde !"
 ```
 
-### Auto-détection de langue
+### Batch Processing
 
 ```ruby
-result = MistralTranslator.translate_auto("Hello world", to: 'fr')
-# => "Bonjour le monde"
+texts = ["Bonjour", "Merci", "Au revoir"]
+results = MistralTranslator.translate_batch(texts, from: "fr", to: "en")
+# => {0 => "Hello", 1 => "Thank you", 2 => "Goodbye"}
 ```
 
-### Résumés
+### Text Summarization
 
 ```ruby
-long_text = "Un très long texte à résumer..."
+long_text = "Ruby on Rails is a web framework..."
 
-# Résumé simple
-summary = MistralTranslator.summarize(long_text, language: 'fr', max_words: 100)
+# Simple summary
+summary = MistralTranslator.summarize(long_text, language: "en", max_words: 50)
 
-# Résumé avec traduction
+# Summary with translation
 summary = MistralTranslator.summarize_and_translate(
-  long_text, 
-  from: 'fr', 
-  to: 'en', 
-  max_words: 150
-)
-
-# Résumés par niveaux
-summaries = MistralTranslator.summarize_tiered(
   long_text,
-  language: 'fr',
-  short: 50,
-  medium: 150, 
-  long: 300
+  from: "en",
+  to: "fr",
+  max_words: 100
 )
-# => { short: "...", medium: "...", long: "..." }
 ```
 
-### Extensions String (optionnel)
+### Rails Integration
 
 ```ruby
-# Activer les extensions String
-ENV['MISTRAL_TRANSLATOR_EXTEND_STRING'] = 'true'
-require 'mistral_translator'
-
-"Bonjour".mistral_translate(from: 'fr', to: 'en')
-# => "Hello"
+# With Mobility
+class Article < ApplicationRecord
+  extend Mobility
+  translates :title, :content, backend: :table
+
+  def translate_to_all_languages!
+    MistralTranslator::RecordTranslation.translate_mobility_record(
+      self,
+      [:title, :content],
+      source_locale: I18n.locale
+    )
+  end
+end
 
-"Long texte...".mistral_summarize(language: 'fr', max_words: 50)
-# => "Résumé..."
+# Usage
+article = Article.create!(title_fr: "Titre français", content_fr: "Contenu...")
+article.translate_to_all_languages!
 ```
 
-## Langues supportées
-
-La gem supporte les langues suivantes :
-- Français (fr)
-- Anglais (en)
-- Espagnol (es)
-- Portugais (pt)
-- Allemand (de)
-- Italien (it)
-- Néerlandais (nl)
-- Russe (ru)
-- Japonais (ja)
-- Coréen (ko)
-- Chinois (zh)
-- Arabe (ar)
+## Configuration Options
 
 ```ruby
-# Vérifier les langues supportées
-MistralTranslator.supported_languages
-MistralTranslator.locale_supported?('fr') # => true
+MistralTranslator.configure do |config|
+  # Required
+  config.api_key = ENV['MISTRAL_API_KEY']
+
+  # Optional
+  config.model = "mistral-small"                    # AI model to use
+  config.retry_delays = [1, 2, 4, 8, 16]          # Retry delays in seconds
+  config.enable_metrics = true                     # Enable performance metrics
+
+  # Callbacks for monitoring
+  config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
+    Rails.logger.info "Translation #{from}→#{to} completed in #{duration.round(2)}s"
+  }
+
+  config.on_translation_error = ->(from, to, error, attempt, timestamp) {
+    Rails.logger.error "Translation failed: #{error.message} (attempt #{attempt})"
+  }
+end
 ```
 
-## Gestion d'erreurs
+## Error Handling
 
 ```ruby
 begin
-  result = MistralTranslator.translate("Hello", from: 'en', to: 'fr')
+  result = MistralTranslator.translate("Hello", from: "en", to: "fr")
 rescue MistralTranslator::RateLimitError
-  puts "Rate limit dépassé, réessayez plus tard"
+  # Rate limit hit - automatic retry with backoff
+  retry
 rescue MistralTranslator::AuthenticationError
-  puts "Clé API invalide"
+  # Invalid API key
+  Rails.logger.error "Check your Mistral API key"
 rescue MistralTranslator::UnsupportedLanguageError => e
-  puts "Langue non supportée: #{e.language}"
+  # Language not supported
+  Rails.logger.error "Language '#{e.language}' not supported"
+rescue MistralTranslator::Error => e
+  # General error handling
+  Rails.logger.error "Translation failed: #{e.message}"
 end
 ```
 
-## Utilisation avancée
-
-### Client personnalisé
+## Performance Monitoring
 
 ```ruby
-client = MistralTranslator::Client.new(api_key: 'autre_clé')
-translator = MistralTranslator::Translator.new(client: client)
-result = translator.translate("Hello", from: 'en', to: 'fr')
+# Enable metrics
+MistralTranslator.configure { |c| c.enable_metrics = true }
+
+# View metrics
+metrics = MistralTranslator.metrics
+puts "Total translations: #{metrics[:total_translations]}"
+puts "Average time: #{metrics[:average_translation_time]}s"
+puts "Error rate: #{metrics[:error_rate]}%"
 ```
 
-### Health check
+## 📖 Complete Documentation
 
-```ruby
-status = MistralTranslator.health_check
-# => { status: :ok, message: "API connection successful" }
-```
+**For comprehensive guides, advanced usage, and Rails integration examples:**
 
-## Développement
+### 🌐 [**Full Documentation Website**](https://peyochanchan.github.io/mistral_translator/)
 
-Après avoir cloné le repo :
+The complete documentation includes:
 
-```bash
-bundle install
-bin/setup
-```
+- **Getting Started Guide** - Step-by-step tutorials
+- **Advanced Usage** - Context, glossaries, batch processing, monitoring
+- **Rails Integration** - Mobility, Globalize, jobs, controllers
+- **API Reference** - Complete method documentation
+- **Examples** - Ready-to-use code samples
+- **Error Handling** - Comprehensive error management strategies
+
+### Quick Links
+
+- [Installation & Setup](https://peyochanchan.github.io/mistral_translator/installation)
+- [Rails Integration Guide](https://peyochanchan.github.io/mistral_translator/rails-integration/)
+- [API Methods Reference](https://peyochanchan.github.io/mistral_translator/api-reference/methods)
+- [Error Handling Guide](https://peyochanchan.github.io/mistral_translator/api-reference/errors)
+- [Monitoring Setup](https://peyochanchan.github.io/mistral_translator/advanced-usage/monitoring)
 
-Pour lancer les tests :
+## Requirements
+
+- Ruby 3.2+
+- Mistral AI API key
+- Rails 6.0+ (optional, for Rails integration features)
+
+## Testing
 
 ```bash
+# Run tests
 bundle exec rspec
-```
 
-Pour lancer RuboCop :
+# Run with coverage
+COVERAGE=true bundle exec rspec
 
-```bash
-bundle exec rubocop
+# Integration tests (requires API key)
+MISTRAL_API_KEY=your_key bundle exec rspec --tag integration
 ```
 
-## Contribution
+## Contributing
+
+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
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Support
 
-Les contributions sont les bienvenues ! Merci de :
-1. Forker le projet
-2. Créer une branche pour votre feature
-3. Commiter vos changements
-4. Pousser vers la branche
-5. Ouvrir une Pull Request
+- 📖 [Documentation](https://peyochanchan.github.io/mistral_translator/)
+- 🐛 [Issues](../../issues)
+- 💬 [Discussions](../../discussions)
+- 📧 Support: Create an issue for help
 
-## Licence
+---
 
-Cette gem est disponible sous la licence MIT.
+Built with Ruby ❤️ by [@peyochanchan](https://github.com/peyochanchan)

data/README_TESTING.md

@@ -0,0 +1,33 @@
+# Tests de la gem MistralTranslator
+
+## Types de tests
+
+### 1. Tests unitaires (par défaut)
+
+- Utilisent des mocks et stubs
+- Pas besoin de clé API
+- Rapides et fiables
+
+### 2. Tests d'intégration
+
+- Marqués avec `:integration`
+- Nécessitent `MISTRAL_TEST_API_KEY`
+- Utilisent la vraie API Mistral
+
+### 3. Tests VCR
+
+- Marqués avec `:vcr`
+- Enregistrent les réponses API
+- Rejouent les réponses sans nouvelle requête
+
+## Configuration
+
+### Variables d'environnement
+
+```bash
+# Pour les tests d'intégration (optionnel)
+export MISTRAL_TEST_API_KEY="votre_cle_de_test"
+
+# Alternative (utilise votre clé principale)
+export MISTRAL_API_KEY="votre_cle_principale"
+```

data/SECURITY.md

@@ -0,0 +1,157 @@
+# Sécurité - MistralTranslator
+
+## 🔒 Améliorations de sécurité implémentées
+
+### 1. Validation des entrées utilisateur
+
+#### Validation basique (par défaut)
+
+- **Longueur des textes** : Limite à 50 000 caractères maximum
+- **Textes vides** : Acceptés et retournés comme chaîne vide (cas d'usage légitime)
+- **Validation des batches** : Maximum 20 textes par batch
+- **Validation des paramètres** : Vérification des types et valeurs
+
+#### Protection contre les attaques courantes
+
+- **Injection de code** : Détection des patterns dangereux
+- **Scripts malveillants** : Filtrage des balises HTML/JavaScript
+- **Injection SQL** : Détection des patterns SQL malveillants
+- **Traversal de chemins** : Protection contre les accès non autorisés
+
+### 2. Rate Limiting côté client
+
+#### Fonctionnalités
+
+- **Limite par défaut** : 50 requêtes par minute
+- **Configuration flexible** : Limites personnalisables
+- **Thread-safe** : Protection contre les conditions de course
+- **Attente intelligente** : Délai automatique quand la limite est atteinte
+
+#### Configuration
+
+```ruby
+# Via variables d'environnement
+MISTRAL_RATE_LIMIT_MAX_REQUESTS=100
+MISTRAL_RATE_LIMIT_WINDOW=60
+
+# Via code
+rate_limiter = MistralTranslator::Security::BasicRateLimiter.new(
+  max_requests: 100,
+  window_seconds: 60
+)
+```
+
+### 3. Gestion sécurisée des erreurs
+
+#### Nouvelles exceptions
+
+- `SecurityError` : Violations de sécurité détectées
+- `RateLimitExceededError` : Limite de taux dépassée
+
+#### Messages d'erreur sécurisés
+
+- Aucune exposition d'informations sensibles
+- Messages d'erreur génériques pour éviter les fuites
+
+### 4. Optimisation de la taille
+
+#### Réduction significative
+
+- **Avant** : ~4000+ lignes avec validation complète
+- **Après** : 3197 lignes avec sécurité essentielle
+- **Gain** : ~20% de réduction de taille
+
+#### Architecture modulaire
+
+- Module de sécurité optionnel et léger
+- Validation basique par défaut
+- Possibilité d'extension future
+
+## 🛡️ Utilisation sécurisée
+
+### Configuration recommandée
+
+```ruby
+MistralTranslator.configure do |config|
+  config.api_key = ENV['MISTRAL_API_KEY']
+  config.enable_metrics = true
+
+  # Callbacks de sécurité
+  config.on_translation_error = lambda do |from, to, error, attempt, timestamp|
+    Rails.logger.error "[Security] Translation failed: #{error.class.name}"
+  end
+end
+```
+
+### Cas d'usage légitimes
+
+- **Textes vides** : Acceptés automatiquement (retournent une chaîne vide)
+- **Même langue source/cible** : Retourne le texte original sans appel API
+- **Validation permissive** : Focus sur la sécurité sans bloquer l'usage normal
+
+### Bonnes pratiques
+
+1. **Validation côté client** : Toujours valider les entrées avant l'envoi
+2. **Gestion des erreurs** : Capturer et logger les erreurs de sécurité
+3. **Monitoring** : Surveiller les tentatives de rate limiting
+4. **Mise à jour** : Maintenir la gem à jour pour les dernières corrections
+
+## 🔍 Tests de sécurité
+
+### Couverture des tests
+
+- Validation des entrées malveillantes
+- Tests de rate limiting
+- Vérification de la thread-safety
+- Tests d'encodage et de format
+
+### Exécution des tests
+
+```bash
+# Tests de sécurité uniquement
+bundle exec rspec spec/mistral_translator/security_spec.rb
+
+# Tests de sécurité existants
+bundle exec rspec spec/mistral_translator/security_spec.rb
+```
+
+## 📊 Métriques de sécurité
+
+### Indicateurs surveillés
+
+- Nombre de requêtes bloquées par validation
+- Fréquence des rate limits
+- Types d'erreurs de sécurité
+- Temps de réponse moyen
+
+### Accès aux métriques
+
+```ruby
+# Métriques globales
+MistralTranslator.metrics
+
+# Réinitialisation
+MistralTranslator.reset_metrics!
+```
+
+## 🚨 Signaler des vulnérabilités
+
+Si vous découvrez une vulnérabilité de sécurité :
+
+1. **Ne pas** ouvrir d'issue publique
+2. Envoyer un email à : security@mistral-translator.dev
+3. Inclure : description, étapes de reproduction, impact
+
+## 📝 Changelog de sécurité
+
+### Version 0.2.0
+
+- ✅ Validation basique des entrées
+- ✅ Rate limiting côté client
+- ✅ Nouvelles exceptions de sécurité
+- ✅ Optimisation de la taille de la gem
+- ✅ Tests de sécurité complets
+
+---
+
+_Cette documentation est mise à jour à chaque amélioration de sécurité._

data/docs/.nojekyll

@@ -0,0 +1,2 @@
+
+

data/docs/404.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>404 - MistralTranslator Docs</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta
+      name="description"
+      content="Page non trouvée - MistralTranslator documentation"
+    />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, minimum-scale=1.0"
+    />
+    <link
+      rel="stylesheet"
+      href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css"
+    />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>
+      window.$docsify = {
+        name: "MistralTranslator",
+        repo: "peyochanchan/mistral_translator",
+      };
+    </script>
+    <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  </body>
+</html>