mistral_translator 0.1.0 → 0.2.1

data/docs/rails-integration/setup.md

@@ -0,0 +1,339 @@
+> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
+
+---
+
+# Configuration Rails
+
+Intégration complète de MistralTranslator avec Ruby on Rails.
+
+## Initializer Rails
+
+```ruby
+# config/initializers/mistral_translator.rb
+MistralTranslator.configure do |config|
+  config.api_key = ENV['MISTRAL_API_KEY']
+  config.enable_metrics = Rails.env.production?
+
+  case Rails.env
+  when 'development'
+    config.setup_rails_logging
+    config.retry_delays = [1, 2, 4]
+
+  when 'production'
+    config.retry_delays = [2, 4, 8, 16, 32]
+
+    # Callbacks production
+    config.on_translation_error = ->(from, to, error, attempt, timestamp) {
+      if defined?(Sentry) && attempt > 2
+        Sentry.capture_exception(error, extra: {
+          translation: { from: from, to: to, attempt: attempt }
+        })
+      end
+    }
+
+    config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
+      if defined?(StatsD)
+        StatsD.timing('mistral.translation.duration', duration * 1000)
+        StatsD.increment('mistral.translation.success')
+      end
+    }
+  end
+end
+```
+
+## Helper Global
+
+```ruby
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  def safe_translate(text, to:, context: nil)
+    return text if text.blank?
+    return text if I18n.locale.to_s == to.to_s
+
+    translator = MistralTranslator::Translator.new
+    translator.translate(
+      text,
+      from: I18n.locale.to_s,
+      to: to.to_s,
+      context: context
+    )
+  rescue MistralTranslator::Error => e
+    Rails.logger.error "Translation failed: #{e.message}"
+    text
+  end
+
+  def translate_with_cache(text, to:, **options)
+    cache_key = "translation:#{Digest::MD5.hexdigest(text)}:#{I18n.locale}:#{to}"
+
+    Rails.cache.fetch(cache_key, expires_in: 24.hours) do
+      safe_translate(text, to: to, **options)
+    end
+  end
+end
+```
+
+## Service de Traduction
+
+```ruby
+# app/services/translation_service.rb
+class TranslationService
+  def self.translate_model(record, fields, target_locales = nil)
+    target_locales ||= I18n.available_locales - [I18n.locale]
+
+    success_count = 0
+    error_count = 0
+
+    target_locales.each do |locale|
+      begin
+        translate_fields_for_locale(record, fields, locale)
+        success_count += 1
+      rescue MistralTranslator::Error => e
+        Rails.logger.error "Translation failed for #{locale}: #{e.message}"
+        error_count += 1
+      end
+    end
+
+    { success: success_count, errors: error_count }
+  end
+
+  private
+
+  def self.translate_fields_for_locale(record, fields, locale)
+    Array(fields).each do |field|
+      source_value = record.send("#{field}_#{I18n.locale}")
+      next if source_value.blank?
+
+      translator = MistralTranslator::Translator.new
+      translated = translator.translate(
+        source_value,
+        from: I18n.locale.to_s,
+        to: locale.to_s,
+        context: "#{record.class.name} #{field}"
+      )
+
+      record.send("#{field}_#{locale}=", translated)
+    end
+
+    record.save!
+  end
+end
+```
+
+## Concern pour Modèles
+
+```ruby
+# app/models/concerns/translatable.rb
+module Translatable
+  extend ActiveSupport::Concern
+
+  included do
+    after_save :auto_translate, if: :should_auto_translate?
+  end
+
+  class_methods do
+    def translatable_fields(*fields)
+      @translatable_fields = fields
+    end
+
+    def get_translatable_fields
+      @translatable_fields || []
+    end
+  end
+
+  def translate_to_all_locales
+    return false if self.class.get_translatable_fields.empty?
+
+    result = TranslationService.translate_model(
+      self,
+      self.class.get_translatable_fields
+    )
+
+    Rails.logger.info "Translated #{result[:success]} locales, #{result[:errors]} errors"
+    result[:errors] == 0
+  end
+
+  private
+
+  def should_auto_translate?
+    Rails.env.production? &&
+    self.class.get_translatable_fields.any? { |field| saved_change_to_attribute?("#{field}_#{I18n.locale}") }
+  end
+
+  def auto_translate
+    TranslateModelJob.perform_later(self.class.name, id)
+  end
+end
+```
+
+## Exemple d'Usage
+
+```ruby
+# app/models/article.rb
+class Article < ApplicationRecord
+  include Translatable
+
+  translatable_fields :title, :content, :summary
+
+  # Méthode manuelle
+  def translate_title_to(locale)
+    translator = MistralTranslator::Translator.new
+    translator.translate(
+      title,
+      from: I18n.locale.to_s,
+      to: locale.to_s,
+      context: "Blog article title"
+    )
+  rescue MistralTranslator::Error
+    title
+  end
+end
+
+# Usage
+article = Article.create!(title: "Mon article", content: "Contenu...")
+article.translate_to_all_locales
+```
+
+## Job Asynchrone
+
+```ruby
+# app/jobs/translate_model_job.rb
+class TranslateModelJob < ApplicationJob
+  queue_as :translations
+
+  def perform(model_class, record_id)
+    model = model_class.constantize
+    record = model.find(record_id)
+
+    result = TranslationService.translate_model(record, model.get_translatable_fields)
+
+    Rails.logger.info "Translation job completed: #{result[:success]} success, #{result[:errors]} errors"
+  rescue ActiveRecord::RecordNotFound
+    Rails.logger.error "Record not found: #{model_class}##{record_id}"
+  rescue => e
+    Rails.logger.error "Translation job failed: #{e.message}"
+    raise e
+  end
+end
+```
+
+## Variables d'Environnement
+
+```ruby
+# .env.development
+MISTRAL_API_KEY=your_dev_key_here
+
+# .env.production
+MISTRAL_API_KEY=your_prod_key_here
+
+# config/application.yml (Figaro)
+development:
+  MISTRAL_API_KEY: your_dev_key
+
+production:
+  MISTRAL_API_KEY: your_prod_key
+```
+
+## Vues et Formulaires
+
+```erb
+<!-- app/views/articles/show.html.erb -->
+<div class="article">
+  <h1><%= @article.title %></h1>
+
+  <!-- Sélecteur de langue -->
+  <div class="language-selector">
+    <% I18n.available_locales.each do |locale| %>
+      <%= link_to locale.upcase,
+          article_path(@article, locale: locale),
+          class: ("active" if I18n.locale == locale) %>
+    <% end %>
+  </div>
+
+  <!-- Traduction à la demande -->
+  <% if I18n.locale != I18n.default_locale %>
+    <div class="translation-info">
+      <%= translate_with_cache(@article.content, to: I18n.locale,
+                              context: "Blog article content") %>
+    </div>
+  <% else %>
+    <div class="content">
+      <%= @article.content %>
+    </div>
+  <% end %>
+</div>
+```
+
+## Configuration Avancée
+
+```ruby
+# config/initializers/mistral_translator.rb
+MistralTranslator.configure do |config|
+  config.api_key = ENV['MISTRAL_API_KEY']
+
+  # Optimisation Rails
+  config.enable_metrics = true
+  config.default_max_tokens = 4000
+
+  # Cache intelligent des traductions
+  config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
+    # Statistiques dans le cache Rails
+    Rails.cache.increment("translation_count_#{Date.current}", 1, expires_in: 1.day)
+
+    # Log des traductions coûteuses
+    if orig_len > 1000
+      Rails.logger.info "Large translation: #{orig_len} chars in #{duration.round(2)}s"
+    end
+  }
+
+  # Intégration avec ActiveSupport::Notifications
+  config.on_translation_start = ->(from, to, length, timestamp) {
+    ActiveSupport::Notifications.instrument("translation.mistral", {
+      from: from, to: to, length: length
+    })
+  }
+end
+
+# Écouter les notifications
+ActiveSupport::Notifications.subscribe "translation.mistral" do |name, start, finish, id, payload|
+  Rails.logger.info "Translation notification: #{payload}"
+end
+```
+
+## Tests Rails
+
+```ruby
+# spec/support/mistral_translator.rb
+RSpec.configure do |config|
+  config.before(:suite) do
+    MistralTranslator.configure do |c|
+      c.api_key = 'test-key'
+      c.enable_metrics = false
+    end
+  end
+end
+
+# spec/models/article_spec.rb
+require 'rails_helper'
+
+RSpec.describe Article do
+  before do
+    allow(MistralTranslator).to receive(:translate).and_return("Mocked translation")
+  end
+
+  describe '#translate_to_all_locales' do
+    it 'translates all fields to available locales' do
+      article = create(:article, title: "Test", content: "Content")
+
+      expect(MistralTranslator).to receive(:translate).twice
+      result = article.translate_to_all_locales
+
+      expect(result).to be true
+    end
+  end
+end
+```
+
+---
+
+**Rails Integration Navigation:**
+[← Setup](rails-integration/setup.md) | [Adapters](rails-integration/adapters.md) | [Jobs](rails-integration/jobs.md) | [Controllers](rails-integration/controllers.md) →

data/examples/basic_usage.rb

@@ -1,135 +1,162 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Exemple d'utilisation de base de la gem MistralTranslator
+# Exemple d'usage de base de MistralTranslator
+# Usage: ruby examples/basic_usage.rb
+
+# Préférer la version locale de la gem (pour tester la version du repo)
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "mistral_translator"
 
-# Configuration
+# Configuration minimale
 MistralTranslator.configure do |config|
   config.api_key = ENV["MISTRAL_API_KEY"] || "your_api_key_here"
-  # config.api_url = 'https://api.mistral.ai'  # optionnel
-  # config.model = 'mistral-small'             # optionnel
 end
 
 puts "=== MistralTranslator Examples ==="
-puts "Version: #{MistralTranslator.version}"
-puts
-
-# Vérification de la santé de l'API
-puts "🔍 Health Check:"
-health = MistralTranslator.health_check
-puts "Status: #{health[:status]} - #{health[:message]}"
 puts
 
-# Exemple 1: Traduction simple
-puts "📝 Traduction simple:"
+# Vérification de base
 begin
-  result = MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
-  puts "FR → EN: 'Bonjour le monde' → '#{result}'"
-rescue MistralTranslator::Error => e
-  puts "Erreur: #{e.message}"
+  # Test simple pour vérifier que l'API fonctionne
+  test = MistralTranslator.translate("Hello", from: "en", to: "fr")
+  puts "Configuration OK - Test: #{test}"
+rescue MistralTranslator::AuthenticationError
+  puts "ERREUR: Clé API invalide. Définissez MISTRAL_API_KEY"
+  exit 1
+rescue MistralTranslator::ConfigurationError
+  puts "ERREUR: Configuration manquante"
+  exit 1
+rescue StandardError => e
+  puts "ERREUR: #{e.message}"
+  exit 1
 end
 puts
 
-# Exemple 2: Traduction vers plusieurs langues
-puts "🌍 Traduction vers plusieurs langues:"
-begin
-  results = MistralTranslator.translate_to_multiple(
-    "Hello world",
-    from: "en",
-    to: %w[fr es de]
-  )
-
-  results.each do |locale, translation|
-    puts "EN → #{locale.upcase}: '#{translation}'"
-  end
-rescue MistralTranslator::Error => e
-  puts "Erreur: #{e.message}"
-end
+# 1. Traduction de base
+puts "1. Traduction simple"
+puts "-" * 20
+result = MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
+puts "FR → EN: #{result}"
 puts
 
-# Exemple 3: Traduction en lot
-puts "📦 Traduction en lot:"
-begin
-  texts = ["Good morning", "Good afternoon", "Good evening"]
-  results = MistralTranslator.translate_batch(texts, from: "en", to: "fr")
-
-  results.each do |index, translation|
-    puts "#{index}: '#{texts[index]}' → '#{translation}'"
-  end
-rescue MistralTranslator::Error => e
-  puts "Erreur: #{e.message}"
-end
+translator = MistralTranslator::Translator.new
+
+# Détection de la prise en charge de `context` et `glossary` (>= 0.2.0)
+supports_context_glossary = Gem::Version.new(MistralTranslator::VERSION) >= Gem::Version.new("0.2.0")
+
+# 2. Traduction avec contexte
+puts "2. Traduction avec contexte"
+puts "-" * 27
+result = if supports_context_glossary
+           translator.translate(
+             "Batterie faible",
+             from: "fr",
+             to: "en",
+             context: "Smartphone notification"
+           )
+         else
+           translator.translate(
+             "Batterie faible",
+             from: "fr",
+             to: "en"
+           )
+         end
+puts "Avec contexte: #{result}"
 puts
 
-# Exemple 4: Auto-détection de langue
-puts "🔍 Auto-détection de langue:"
-begin
-  result = MistralTranslator.translate_auto("¡Hola mundo!", to: "en")
-  puts "Auto-détection → EN: '#{result}'"
-rescue MistralTranslator::Error => e
-  puts "Erreur: #{e.message}"
+# 3. Traduction avec glossaire
+puts "3. Traduction avec glossaire"
+puts "-" * 28
+result = if supports_context_glossary
+           translator.translate(
+             "L'IA révolutionne le secteur",
+             from: "fr",
+             to: "en",
+             glossary: { "IA" => "AI" }
+           )
+         else
+           translator.translate(
+             "L'IA révolutionne le secteur",
+             from: "fr",
+             to: "en"
+           )
+         end
+puts "Avec glossaire: #{result}"
+puts
+
+# 4. Auto-détection
+puts "4. Auto-détection de langue"
+puts "-" * 27
+texts = ["¡Hola mundo!", "Guten Tag", "Ciao mondo"]
+texts.each do |text|
+  result = MistralTranslator.translate_auto(text, to: "fr")
+  puts "#{text} → #{result}"
 end
 puts
 
-# Exemple 5: Résumé de texte
-puts "📄 Résumé de texte:"
-long_text = <<~TEXT
-  Ruby on Rails est un framework de développement web écrit en Ruby qui suit le paradigme#{" "}
-  Modèle-Vue-Contrôleur (MVC). Il privilégie la convention plutôt que la configuration,#{" "}
-  ce qui permet aux développeurs de créer rapidement des applications web robustes.#{" "}
-  Rails comprend de nombreux outils intégrés comme Active Record pour l'ORM,#{" "}
-  Action View pour les templates, Action Controller pour la logique métier,#{" "}
-  et bien d'autres composants. Le framework a été créé par David Heinemeier Hansson#{" "}
-  en 2004 et continue d'évoluer avec une communauté active de développeurs.
+# 5. Traduction vers plusieurs langues
+puts "5. Multi-langues"
+puts "-" * 14
+results = translator.translate_to_multiple(
+  "Bienvenue",
+  from: "fr",
+  to: %w[en es de]
+)
+results.each { |lang, text| puts "#{lang.upcase}: #{text}" }
+puts
+
+# 6. Traduction par lot
+puts "6. Traduction par lot"
+puts "-" * 19
+texts = ["Bonjour", "Merci", "Au revoir"]
+results = MistralTranslator.translate_batch(texts, from: "fr", to: "en")
+results.each { |i, translation| puts "#{texts[i]} → #{translation}" }
+puts
+
+# 7. Résumé simple
+puts "7. Résumé de texte"
+puts "-" * 17
+article = <<~TEXT.strip
+  Ruby on Rails est un framework web MVC écrit en Ruby qui privilégie la
+  convention sur la configuration. Il inclut Active Record pour l'ORM, Action
+  View pour les vues, et Action Controller pour la logique métier.
 TEXT
 
-begin
-  summary = MistralTranslator.summarize(long_text, language: "fr", max_words: 50)
-  puts "Texte original: #{long_text.length} caractères"
-  puts "Résumé (50 mots max): #{summary}"
-rescue MistralTranslator::Error => e
-  puts "Erreur: #{e.message}"
-end
+summary = MistralTranslator.summarize(article, language: "fr", max_words: 25)
+puts "Résumé: #{summary}"
 puts
 
-# Exemple 6: Résumé avec traduction
-puts "🔄 Résumé + Traduction:"
-begin
-  result = MistralTranslator.summarize_and_translate(
-    long_text,
-    from: "fr",
-    to: "en",
-    max_words: 75
-  )
-  puts "Résumé traduit EN (75 mots max): #{result}"
-rescue MistralTranslator::Error => e
-  puts "Erreur: #{e.message}"
-end
+# 8. Résumé avec traduction
+puts "8. Résumé + traduction"
+puts "-" * 22
+result = MistralTranslator.summarize_and_translate(
+  article,
+  from: "fr",
+  to: "en",
+  max_words: 30
+)
+puts "EN: #{result}"
 puts
 
-# Exemple 7: Résumés par niveaux
-puts "📊 Résumés par niveaux:"
-begin
-  tiered = MistralTranslator.summarize_tiered(
-    long_text,
-    language: "fr",
-    short: 25,
-    medium: 75,
-    long: 150
-  )
-
-  puts "Court (25 mots): #{tiered[:short]}"
-  puts "Moyen (75 mots): #{tiered[:medium]}"
-  puts "Long (150 mots): #{tiered[:long]}"
-rescue MistralTranslator::Error => e
-  puts "Erreur: #{e.message}"
-end
+# 9. Résumés multi-niveaux
+puts "9. Résumés par niveaux"
+puts "-" * 22
+tiered = MistralTranslator.summarize_tiered(
+  article,
+  language: "fr",
+  short: 15,
+  medium: 30,
+  long: 50
+)
+puts "Court: #{tiered[:short]}"
+puts "Moyen: #{tiered[:medium]}"
 puts
 
-# Informations sur les langues supportées
-puts "🌐 Langues supportées:"
-puts MistralTranslator.supported_languages
+# 10. Informations sur la gem
+puts "10. Informations"
+puts "-" * 15
+puts "Langues: #{MistralTranslator.supported_locales.join(", ")}"
 puts
 
-puts "✅ Exemples terminés!"
+puts "Tous les exemples terminés !"