mistral_translator 0.1.0 → 0.3.0

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>

data/docs/README.md

@@ -0,0 +1,153 @@
+> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
+
+---
+
+# Documentation MistralTranslator
+
+Bienvenue dans la documentation complète de **MistralTranslator**, une gem Ruby puissante pour la traduction et la synthèse de texte utilisant l'API Mistral AI.
+
+## 🚀 Démarrage Rapide
+
+```ruby
+# Installation
+gem 'mistral_translator'
+
+# Configuration
+MistralTranslator.configure { |c| c.api_key = ENV['MISTRAL_API_KEY'] }
+
+# Usage
+result = MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
+# => "Hello world"
+```
+
+## 📚 Guide de Documentation
+
+### 🎯 Pour Commencer
+
+| Fichier                                                | Description                                     | Niveau   |
+| ------------------------------------------------------ | ----------------------------------------------- | -------- |
+| [Installation](installation.md)                        | Installation de la gem et configuration de base | Débutant |
+| [Guide de Démarrage](getting-started.md)               | Premiers pas avec exemples simples              | Débutant |
+| [Exemples de Base](../examples/basic_usage.rb)         | Code commenté pour débuter                      | Débutant |
+| [Migration 0.1.0 → 0.2.0](migration-0.1.0-to-0.2.0.md) | Changements clés et guide de migration          | Tous     |
+
+### ⚡ Fonctionnalités Avancées
+
+| Fichier                                                  | Description                                    | Contenu Principal                                 |
+| -------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
+| [Traductions Avancées](advanced-usage/translations.md)   | Contexte, glossaires, HTML, auto-détection     | `translate_with_confidence()`, `translate_auto()` |
+| [Traitement par Lot](advanced-usage/batch-processing.md) | Optimisation batch, multi-langues, progression | `translate_batch()`, `translate_to_multiple()`    |
+| [Résumés Intelligents](advanced-usage/summarization.md)  | Multi-niveaux, multi-langues, Rails            | `summarize()`, `summarize_tiered()`               |
+| [Gestion des Erreurs](advanced-usage/error-handling.md)  | Retry, circuit breaker, fallback strategies    | Patterns de robustesse                            |
+| [Monitoring](advanced-usage/monitoring.md)               | Métriques, dashboard, alertes                  | Analytics et observabilité                        |
+
+### 🛤️ Intégration Rails
+
+| Fichier                                                 | Description                             | Gems Supportées           |
+| ------------------------------------------------------- | --------------------------------------- | ------------------------- |
+| [Configuration Rails](rails-integration/setup.md)       | Initializers, environnements, callbacks | Rails 7+                  |
+| [Adaptateurs de Modèles](rails-integration/adapters.md) | Intégration transparente avec gems I18n | Mobility, Globalize, I18n |
+| [Jobs Asynchrones](rails-integration/jobs.md)           | Traduction en arrière-plan              | Sidekiq, ActiveJob        |
+| [Controllers & API](rails-integration/controllers.md)   | Endpoints, dashboard admin              | REST API, Admin UI        |
+
+### 📖 Référence API
+
+| Fichier                                         | Description                         | Usage                         |
+| ----------------------------------------------- | ----------------------------------- | ----------------------------- |
+| [Configuration](api-reference/configuration.md) | Toutes les options de configuration | `MistralTranslator.configure` |
+| [Méthodes](api-reference/methods.md)            | Documentation complète des méthodes | API publique                  |
+| [Erreurs](api-reference/errors.md)              | Types d'erreurs et codes de gestion | `rescue` patterns             |
+| [Callbacks](api-reference/callbacks.md)         | Événements et hooks personnalisés   | Monitoring custom             |
+
+### 💻 Exemples Pratiques
+
+| Fichier                                             | Description                       | Cas d'Usage     |
+| --------------------------------------------------- | --------------------------------- | --------------- |
+| [Usage de Base](../examples/basic_usage.rb)         | Script simple avec commentaires   | Premier projet  |
+| [Modèle Rails](../examples/rails-model.rb)          | Modèle complet avec traductions   | App Rails       |
+| [Job de Traitement](../examples/batch-job.rb)       | Job Sidekiq pour batch            | Production      |
+| [Setup Monitoring](../examples/monitoring-setup.rb) | Configuration complète monitoring | Ops & Analytics |
+
+---
+
+## 🎯 Cas d'Usage Principaux
+
+### 🌐 **Applications Multilingues**
+
+- E-commerce international
+- Sites web multilingues
+- Applications SaaS globales
+- Documentation technique
+
+### 📝 **Traitement de Contenu**
+
+- Résumés automatiques d'articles
+- Synthèse de rapports
+- Newsletter multilingues
+- Support client automatisé
+
+### 🔧 **Intégration Système**
+
+- CMS multilingues
+- APIs de traduction
+- Workflows de contenu
+- Automation marketing
+
+---
+
+## 🏃‍♂️ Parcours Recommandés
+
+### **👶 Débutant - Premiers Pas**
+
+1. [Installation](installation.md) - Installer et configurer
+2. [Guide de Démarrage](getting-started.md) - Premiers exemples
+3. [Exemples de Base](../examples/basic_usage.rb) - Code pratique
+
+### **⚡ Développeur Rails**
+
+1. [Configuration Rails](rails-integration/setup.md) - Setup Rails
+2. [Adaptateurs](rails-integration/adapters.md) - Mobility/Globalize
+3. [Modèle Rails](../examples/rails-model.rb) - Exemple complet
+
+### **🚀 Usage Production**
+
+1. [Gestion des Erreurs](advanced-usage/error-handling.md) - Robustesse
+2. [Monitoring](advanced-usage/monitoring.md) - Observabilité
+3. [Jobs Asynchrones](rails-integration/jobs.md) - Scalabilité
+
+### **📊 Analytics & Ops**
+
+1. [Monitoring](advanced-usage/monitoring.md) - Métriques
+2. [Setup Monitoring](../examples/monitoring-setup.rb) - Configuration
+3. [API Référence](api-reference/configuration.md) - Tuning avancé
+
+---
+
+## 🆘 Aide et Support
+
+- **🐛 Problème ?** → Consultez [Gestion des Erreurs](advanced-usage/error-handling.md)
+- **⚙️ Configuration ?** → Voir [API Configuration](api-reference/configuration.md)
+- **🛤️ Rails ?** → Section [Intégration Rails](rails-integration/setup.md)
+- **📈 Performance ?** → Guide [Monitoring](advanced-usage/monitoring.md)
+
+## 🎯 Navigation Rapide
+
+**Recherche par fonctionnalité :**
+
+- **Traduction simple** → [Getting Started](getting-started.md#traduction-simple)
+- **Traduction HTML** → [Traductions Avancées](advanced-usage/translations.md#html-preservation)
+- **Résumés** → [Résumés Intelligents](advanced-usage/summarization.md)
+- **Batch processing** → [Traitement par Lot](advanced-usage/batch-processing.md)
+- **Intégration Mobility** → [Adaptateurs](rails-integration/adapters.md#mobility)
+- **Jobs Sidekiq** → [Jobs Asynchrones](rails-integration/jobs.md#sidekiq)
+- **Dashboard admin** → [Controllers](rails-integration/controllers.md#dashboard)
+
+**Par niveau de complexité :**
+
+- 🟢 **Facile** : Installation, Getting Started, Exemples
+- 🟡 **Moyen** : Traductions Avancées, Rails Setup, Jobs
+- 🔴 **Avancé** : Error Handling, Monitoring, API Référence
+
+---
+
+_📝 Cette documentation est maintenue et mise à jour régulièrement. Pour des suggestions d'amélioration, n'hésitez pas à contribuer !_

data/docs/advanced-usage/batch-processing.md

@@ -0,0 +1,158 @@
+> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
+
+---
+
+# Traitement par Lot (Batch)
+
+Optimisez vos traductions avec le traitement par lot et les traductions multiples.
+
+## 📦 Batch Basique
+
+```ruby
+texts = ["Bonjour", "Comment ça va ?", "Au revoir"]
+
+translator = MistralTranslator::Translator.new
+results = translator.translate_batch(texts, from: "fr", to: "en")
+
+results.each { |index, translation| puts "#{index}: #{translation}" }
+# => 0: Hello
+# => 1: How are you?
+# => 2: Goodbye
+```
+
+## 🌍 Multi-langues
+
+```ruby
+# Vers plusieurs langues simultanément
+results = translator.translate_to_multiple(
+  "Bienvenue",
+  from: "fr",
+  to: ["en", "es", "de", "it"],
+  use_batch: true  # Optimisation
+)
+# => {"en" => "Welcome", "es" => "Bienvenido", ...}
+```
+
+## ⚡ Avec Gestion d'Erreurs
+
+```ruby
+# Fallback automatique en cas d'échec
+results = MistralTranslator::Helpers.translate_batch_with_fallback(
+  texts,
+  from: "fr",
+  to: "en",
+  fallback_strategy: :individual  # Retry individuellement
+)
+
+results.each do |index, result|
+  if result.is_a?(Hash) && result[:error]
+    puts "❌ Erreur #{index}: #{result[:error]}"
+  else
+    puts "✅ #{index}: #{result}"
+  end
+end
+```
+
+## 📊 Avec Progression
+
+```ruby
+# Pour gros volumes
+MistralTranslator::Helpers.translate_with_progress(
+  large_texts.each_with_index.to_h,
+  from: "fr",
+  to: "en"
+) do |current, total, key, result|
+  progress = (current.to_f / total * 100).round(1)
+  puts "📈 [#{progress}%] #{key}"
+end
+```
+
+## 🚦 Rate Limiting
+
+```ruby
+# Délai intelligent entre batches
+def process_large_batch(texts, batch_size: 10)
+  texts.each_slice(batch_size).with_index do |batch, i|
+    results = translator.translate_batch(batch, from: "fr", to: "en")
+
+    # Pause entre batches (sauf le dernier)
+    sleep(2) unless i == (texts.size / batch_size.to_f).ceil - 1
+  end
+end
+```
+
+## 💾 Avec Cache
+
+```ruby
+def cached_batch_translate(texts, from:, to:)
+  results = []
+  to_translate = []
+
+  # Vérifier le cache
+  texts.each_with_index do |text, index|
+    cache_key = "translation:#{Digest::MD5.hexdigest(text)}:#{from}:#{to}"
+    cached = Rails.cache.read(cache_key)
+
+    if cached
+      results[index] = cached
+    else
+      to_translate << { text: text, index: index, cache_key: cache_key }
+    end
+  end
+
+  # Traduire seulement ce qui n'est pas en cache
+  unless to_translate.empty?
+    fresh_results = translator.translate_batch(
+      to_translate.map { |item| item[:text] },
+      from: from, to: to
+    )
+
+    # Sauver en cache
+    fresh_results.each do |batch_index, translation|
+      original_index = to_translate[batch_index][:index]
+      cache_key = to_translate[batch_index][:cache_key]
+
+      Rails.cache.write(cache_key, translation, expires_in: 24.hours)
+      results[original_index] = translation
+    end
+  end
+
+  results
+end
+```
+
+## 📈 Configuration Batch
+
+```ruby
+MistralTranslator.configure do |config|
+  config.retry_delays = [1, 3, 6]  # Plus rapide pour batch
+
+  config.on_batch_complete = ->(size, duration, success, errors) {
+    rate = (success.to_f / size * 100).round(1)
+    puts "📊 Batch: #{success}/#{size} (#{rate}%) en #{duration.round(2)}s"
+  }
+end
+```
+
+## 🎯 Patterns Recommandés
+
+**Petits volumes (< 50 textes) :**
+
+- Batch simple sans optimisation
+
+**Moyens volumes (50-500 textes) :**
+
+- Batch avec cache + rate limiting
+
+**Gros volumes (> 500 textes) :**
+
+- Jobs asynchrones + progression + cache
+
+**Multi-langues :**
+
+- `use_batch: true` pour optimisation API
+
+---
+
+**Advanced Usage Navigation:**
+[← Translations](advanced-usage/translations.md) | [Batch Processing](advanced-usage/batch-processing.md) | [Error Handling](advanced-usage/error-handling.md) | [Monitoring](advanced-usage/monitoring.md) | [Summarization](advanced-usage/summarization.md) →