mistral_translator 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +21 -0
  3. data/README.md +189 -121
  4. data/README_TESTING.md +33 -0
  5. data/SECURITY.md +157 -0
  6. data/docs/.nojekyll +2 -0
  7. data/docs/404.html +30 -0
  8. data/docs/README.md +153 -0
  9. data/docs/advanced-usage/batch-processing.md +158 -0
  10. data/docs/advanced-usage/error-handling.md +106 -0
  11. data/docs/advanced-usage/monitoring.md +133 -0
  12. data/docs/advanced-usage/summarization.md +86 -0
  13. data/docs/advanced-usage/translations.md +141 -0
  14. data/docs/api-reference/callbacks.md +231 -0
  15. data/docs/api-reference/configuration.md +74 -0
  16. data/docs/api-reference/errors.md +673 -0
  17. data/docs/api-reference/methods.md +539 -0
  18. data/docs/getting-started.md +179 -0
  19. data/docs/index.html +27 -0
  20. data/docs/installation.md +142 -0
  21. data/docs/migration-0.1.0-to-0.2.0.md +61 -0
  22. data/docs/rails-integration/adapters.md +84 -0
  23. data/docs/rails-integration/controllers.md +107 -0
  24. data/docs/rails-integration/jobs.md +97 -0
  25. data/docs/rails-integration/setup.md +339 -0
  26. data/examples/basic_usage.rb +129 -102
  27. data/examples/batch-job.rb +511 -0
  28. data/examples/monitoring-setup.rb +499 -0
  29. data/examples/rails-model.rb +399 -0
  30. data/lib/mistral_translator/adapters.rb +261 -0
  31. data/lib/mistral_translator/client.rb +103 -100
  32. data/lib/mistral_translator/client_helpers.rb +161 -0
  33. data/lib/mistral_translator/configuration.rb +171 -1
  34. data/lib/mistral_translator/errors.rb +16 -0
  35. data/lib/mistral_translator/helpers.rb +292 -0
  36. data/lib/mistral_translator/helpers_extensions.rb +150 -0
  37. data/lib/mistral_translator/levenshtein_helpers.rb +40 -0
  38. data/lib/mistral_translator/logger.rb +28 -4
  39. data/lib/mistral_translator/prompt_builder.rb +93 -41
  40. data/lib/mistral_translator/prompt_helpers.rb +83 -0
  41. data/lib/mistral_translator/prompt_metadata_helpers.rb +42 -0
  42. data/lib/mistral_translator/response_parser.rb +194 -23
  43. data/lib/mistral_translator/security.rb +72 -0
  44. data/lib/mistral_translator/summarizer.rb +41 -2
  45. data/lib/mistral_translator/translator.rb +174 -98
  46. data/lib/mistral_translator/translator_helpers.rb +268 -0
  47. data/lib/mistral_translator/version.rb +1 -1
  48. data/lib/mistral_translator.rb +51 -25
  49. metadata +39 -3
data/docs/index.html ADDED
@@ -0,0 +1,27 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <title>MistralTranslator Docs</title>
6
+ <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
7
+ <meta name="description" content="MistralTranslator documentation" />
8
+ <meta
9
+ name="viewport"
10
+ content="width=device-width, initial-scale=1.0, minimum-scale=1.0"
11
+ />
12
+ <link
13
+ rel="stylesheet"
14
+ href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css"
15
+ />
16
+ </head>
17
+ <body>
18
+ <div id="app"></div>
19
+ <script>
20
+ window.$docsify = {
21
+ name: "MistralTranslator",
22
+ repo: "peyochanchan/mistral_translator",
23
+ };
24
+ </script>
25
+ <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
26
+ </body>
27
+ </html>
data/docs/installation.md ADDED
@@ -0,0 +1,142 @@
1
+ > **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
2
+
3
+ ---
4
+
5
+ # Installation et Configuration
6
+
7
+ Installation et configuration de base de MistralTranslator.
8
+
9
+ ## 📦 Installation
10
+
11
+ ```ruby
12
+ # Gemfile
13
+ gem 'mistral_translator'
14
+ ```
15
+
16
+ ```bash
17
+ bundle install
18
+ ```
19
+
20
+ ## 🔑 Configuration de Base
21
+
22
+ ### 1. Clé API Mistral
23
+
24
+ 1. Créez un compte sur [console.mistral.ai](https://console.mistral.ai)
25
+ 2. Générez une clé API
26
+ 3. Stockez-la en variable d'environnement :
27
+
28
+ ```bash
29
+ # .env
30
+ MISTRAL_API_KEY=your_api_key_here
31
+ ```
32
+
33
+ ### 2. Configuration Minimale
34
+
35
+ ```ruby
36
+ MistralTranslator.configure do |config|
37
+ config.api_key = ENV['MISTRAL_API_KEY']
38
+ end
39
+ ```
40
+
41
+ ### 3. Test
42
+
43
+ ```ruby
44
+ # Test rapide
45
+ result = MistralTranslator.translate("Hello", from: "en", to: "fr")
46
+ puts result
47
+ # => "Bonjour"
48
+ ```
49
+
50
+ ## ⚙️ Configuration Rails
51
+
52
+ ```ruby
53
+ # config/initializers/mistral_translator.rb
54
+ MistralTranslator.configure do |config|
55
+ config.api_key = ENV['MISTRAL_API_KEY']
56
+ config.enable_metrics = Rails.env.production?
57
+
58
+ case Rails.env
59
+ when 'development'
60
+ config.setup_rails_logging
61
+ config.retry_delays = [1, 2, 4]
62
+
63
+ when 'production'
64
+ config.retry_delays = [2, 4, 8, 16, 32]
65
+
66
+ # Intégration Sentry (optionnel)
67
+ config.on_translation_error = ->(from, to, error, attempt, timestamp) {
68
+ Sentry.capture_exception(error) if defined?(Sentry) && attempt > 2
69
+ }
70
+ end
71
+ end
72
+ ```
73
+
74
+ ## 🔧 Options Principales
75
+
76
+ ```ruby
77
+ MistralTranslator.configure do |config|
78
+ config.api_key = ENV['MISTRAL_API_KEY']
79
+ config.model = "mistral-small" # Modèle par défaut
80
+ config.retry_delays = [2, 4, 8, 16] # Délais retry
81
+ config.enable_metrics = true # Suivi des stats
82
+ config.default_max_tokens = 4000 # Limite tokens
83
+ config.default_temperature = 0.3 # Créativité
84
+ end
85
+ ```
86
+
87
+ ## 🧪 Script de Validation
88
+
89
+ ```ruby
90
+ # test_installation.rb
91
+ require 'mistral_translator'
92
+
93
+ MistralTranslator.configure do |config|
94
+ config.api_key = ENV['MISTRAL_API_KEY']
95
+ end
96
+
97
+ tests = [
98
+ -> { MistralTranslator.translate("Hello", from: "en", to: "fr") },
99
+ -> { MistralTranslator::LocaleHelper.locale_supported?("fr") },
100
+ -> { MistralTranslator.metrics.is_a?(Hash) }
101
+ ]
102
+
103
+ tests.each_with_index do |test, i|
104
+ begin
105
+ test.call
106
+ puts "✅ Test #{i + 1}: PASS"
107
+ rescue => e
108
+ puts "❌ Test #{i + 1}: #{e.message}"
109
+ end
110
+ end
111
+ ```
112
+
113
+ ## 🚨 Problèmes Courants
114
+
115
+ **Clé API manquante :**
116
+
117
+ ```ruby
118
+ # Vérifiez
119
+ puts ENV['MISTRAL_API_KEY'] # Ne doit pas être nil
120
+ ```
121
+
122
+ **Authentification échouée :**
123
+
124
+ - Vérifiez la clé sur console.mistral.ai
125
+ - Régénérez si nécessaire
126
+
127
+ **Timeout réseau :**
128
+
129
+ ```ruby
130
+ config.retry_delays = [3, 6, 12, 24] # Délais plus longs
131
+ ```
132
+
133
+ ## 📚 Prochaines Étapes
134
+
135
+ - **Débutant ?** → [Guide de Démarrage](getting-started.md)
136
+ - **Rails ?** → [Rails Integration](rails-integration/setup.md)
137
+ - **Avancé ?** → [Traductions Avancées](advanced-usage/translations.md)
138
+
139
+ ---
140
+
141
+ **Documentation Navigation:**
142
+ [← Installation](installation.md) | [Getting Started](getting-started.md) | [Migration Guide](migration-0.1.0-to-0.2.0.md) →
data/docs/migration-0.1.0-to-0.2.0.md ADDED
@@ -0,0 +1,61 @@
1
+ > **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
2
+
3
+ ---
4
+
5
+ # Migration 0.1.0 → 0.2.0
6
+
7
+ ## Résumé
8
+
9
+ - `context` et `glossary` ne passent plus via l’API publique `MistralTranslator.translate`.
10
+ - Utilisez `MistralTranslator::Translator#translate` pour ces options.
11
+ - Ajouts notables: rate limiting client, validation d’entrées, nouvelles erreurs, métriques.
12
+
13
+ ## Ce qui change
14
+
15
+ - Avant (0.1.0) — non supporté par l’API publique:
16
+
17
+ ```ruby
18
+ # Peut lever ArgumentError en 0.1.0
19
+ MistralTranslator.translate("Batterie faible", from: "fr", to: "en", context: "Smartphone")
20
+ ```
21
+
22
+ - Après (0.2.0) — via une instance `Translator`:
23
+
24
+ ```ruby
25
+ translator = MistralTranslator::Translator.new
26
+ translator.translate("Batterie faible", from: "fr", to: "en", context: "Smartphone")
27
+ translator.translate("L'IA...", from: "fr", to: "en", glossary: { "IA" => "AI" })
28
+ ```
29
+
30
+ ## Migration rapide
31
+
32
+ 1. Rechercher les usages de `MistralTranslator.translate(..., context:/glossary:)`.
33
+ 2. Remplacer par:
34
+
35
+ ```ruby
36
+ translator = MistralTranslator::Translator.new
37
+ translator.translate(text, from: from, to: to, context: ctx, glossary: glos)
38
+ ```
39
+
40
+ 3. Rails (helpers/controllers/services): instancier `translator` avant l’appel.
41
+
42
+ ## Nouvelles protections
43
+
44
+ - Rate limiting côté client (50 req/min par défaut)
45
+ - Validation des entrées (max 50k chars, batch ≤ 20)
46
+ - Nouvelles erreurs: `SecurityError`, `RateLimitExceededError`
47
+
48
+ ## Tests & VCR
49
+
50
+ - Filtrage de la clé API dans les cassettes
51
+ - Options VCR par défaut mises à jour
52
+
53
+ ## Références
54
+
55
+ - Guides mis à jour: Getting Started, Traductions Avancées, Intégration Rails
56
+ - Exemple: `examples/basic_usage.rb`
57
+
58
+ ---
59
+
60
+ **Documentation Navigation:**
61
+ [← Installation](installation.md) | [Getting Started](getting-started.md) | [Migration Guide](migration-0.1.0-to-0.2.0.md) →
data/docs/rails-integration/adapters.md ADDED
@@ -0,0 +1,84 @@
1
+ > **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
2
+
3
+ ---
4
+
5
+ # Adaptateurs Rails
6
+
7
+ Intégration automatique avec les gems d'i18n Rails.
8
+
9
+ ## Mobility
10
+
11
+ ```ruby
12
+ class Article < ApplicationRecord
13
+ extend Mobility
14
+ translates :title, :content
15
+ end
16
+
17
+ # Traduction automatique
18
+ MistralTranslator::RecordTranslation.translate_mobility_record(
19
+ article, [:title, :content], source_locale: :fr
20
+ )
21
+ ```
22
+
23
+ ## Globalize
24
+
25
+ ```ruby
26
+ class Product < ApplicationRecord
27
+ translates :name, :description
28
+ end
29
+
30
+ # Traduction automatique
31
+ MistralTranslator::RecordTranslation.translate_globalize_record(
32
+ product, [:name, :description], source_locale: :fr
33
+ )
34
+ ```
35
+
36
+ ## Attributs I18n (title_fr, title_en...)
37
+
38
+ ```ruby
39
+ # Colonnes: title_fr, title_en, content_fr, content_en
40
+ MistralTranslator::RecordTranslation.translate_record(
41
+ page, [:title, :content], source_locale: :fr
42
+ )
43
+ ```
44
+
45
+ ## Adaptateur Personnalisé
46
+
47
+ ```ruby
48
+ class CustomModel < ApplicationRecord
49
+ def get_translation(field, locale)
50
+ translations[locale.to_s]&.[](field.to_s)
51
+ end
52
+
53
+ def set_translation(field, locale, value)
54
+ # Votre logique de stockage
55
+ end
56
+ end
57
+
58
+ # Usage
59
+ MistralTranslator::RecordTranslation.translate_custom_record(
60
+ model, [:title],
61
+ get_method: :get_translation,
62
+ set_method: :set_translation
63
+ )
64
+ ```
65
+
66
+ ## Détection Automatique
67
+
68
+ ```ruby
69
+ # Détecte automatiquement Mobility, Globalize ou I18n
70
+ adapter = MistralTranslator::Adapters::AdapterFactory.build_for(record)
71
+ service = MistralTranslator::Adapters::RecordTranslationService.new(
72
+ record, [:title, :content], adapter: adapter
73
+ )
74
+ service.translate_to_all_locales
75
+ ```
76
+
77
+ ## ActionText Support
78
+
79
+ ActionText est automatiquement détecté et le HTML est préservé lors de la traduction.
80
+
81
+ ---
82
+
83
+ **Rails Integration Navigation:**
84
+ [← Setup](rails-integration/setup.md) | [Adapters](rails-integration/adapters.md) | [Jobs](rails-integration/jobs.md) | [Controllers](rails-integration/controllers.md) →
data/docs/rails-integration/controllers.md ADDED
@@ -0,0 +1,107 @@
1
+ > **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
2
+
3
+ ---
4
+
5
+ # Controllers et API
6
+
7
+ Endpoints pour traduction et interface d'administration.
8
+
9
+ ## API Endpoint
10
+
11
+ ```ruby
12
+ class Api::TranslationsController < ApplicationController
13
+ def create
14
+ translator = MistralTranslator::Translator.new
15
+ result = translator.translate(
16
+ params[:text],
17
+ from: params[:from],
18
+ to: params[:to],
19
+ context: params[:context]
20
+ )
21
+
22
+ render json: { translation: result }
23
+ rescue MistralTranslator::Error => e
24
+ render json: { error: e.message }, status: 422
25
+ end
26
+ end
27
+ ```
28
+
29
+ ## Traduction de Modèles
30
+
31
+ ```ruby
32
+ class Admin::TranslationsController < ApplicationController
33
+ def translate_record
34
+ model = params[:model].constantize.find(params[:id])
35
+
36
+ TranslateRecordJob.perform_later(
37
+ params[:model],
38
+ params[:id],
39
+ params[:fields]
40
+ )
41
+
42
+ redirect_back fallback_location: root_path,
43
+ notice: "Traduction en cours..."
44
+ end
45
+ end
46
+ ```
47
+
48
+ ## Dashboard Métriques
49
+
50
+ ```ruby
51
+ class Admin::MetricsController < ApplicationController
52
+ def show
53
+ @metrics = MistralTranslator.metrics
54
+ @recent_activity = translation_activity_summary
55
+ end
56
+
57
+ private
58
+
59
+ def translation_activity_summary
60
+ # Vos métriques business selon vos besoins
61
+ end
62
+ end
63
+ ```
64
+
65
+ ## Sélecteur de Langue
66
+
67
+ ```ruby
68
+ class ApplicationController < ActionController::Base
69
+ around_action :switch_locale
70
+
71
+ private
72
+
73
+ def switch_locale(&block)
74
+ locale = params[:locale] || I18n.default_locale
75
+ I18n.with_locale(locale, &block)
76
+ end
77
+
78
+ def default_url_options
79
+ { locale: I18n.locale }
80
+ end
81
+ end
82
+ ```
83
+
84
+ ## Patterns Recommandés
85
+
86
+ **API Endpoints :**
87
+
88
+ - Rate limiting pour éviter l'abus
89
+ - Cache des traductions fréquentes
90
+ - Validation des paramètres d'entrée
91
+
92
+ **Admin Interface :**
93
+
94
+ - Actions en lot pour traduction de modèles
95
+ - Queue status et progression
96
+ - Métriques d'usage et coûts
97
+
98
+ **Frontend :**
99
+
100
+ - Traduction en temps réel via AJAX
101
+ - Fallback sur texte original si échec
102
+ - Indicateurs de loading/progression
103
+
104
+ ---
105
+
106
+ **Rails Integration Navigation:**
107
+ [← Setup](rails-integration/setup.md) | [Adapters](rails-integration/adapters.md) | [Jobs](rails-integration/jobs.md) | [Controllers](rails-integration/controllers.md) →
data/docs/rails-integration/jobs.md ADDED
@@ -0,0 +1,97 @@
1
+ > **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
2
+
3
+ ---
4
+
5
+ # Jobs Asynchrones
6
+
7
+ Traitement des traductions en arrière-plan avec ActiveJob/Sidekiq.
8
+
9
+ ## Job de Base
10
+
11
+ ```ruby
12
+ class TranslateRecordJob < ApplicationJob
13
+ def perform(model_class, record_id, fields, source_locale = nil)
14
+ record = model_class.constantize.find(record_id)
15
+ MistralTranslator::RecordTranslation.translate_record(
16
+ record, fields, source_locale: source_locale
17
+ )
18
+ end
19
+ end
20
+
21
+ # Usage
22
+ TranslateRecordJob.perform_later("Article", article.id, [:title, :content])
23
+ ```
24
+
25
+ ## Job avec Retry
26
+
27
+ ```ruby
28
+ class TranslateRecordJob < ApplicationJob
29
+ queue_as :translations
30
+ retry_on MistralTranslator::RateLimitError, wait: 30.seconds, attempts: 5
31
+ discard_on MistralTranslator::AuthenticationError
32
+
33
+ def perform(model_class, record_id, fields, source_locale = nil)
34
+ # Logique de traduction
35
+ end
36
+ end
37
+ ```
38
+
39
+ ## Déclenchement Automatique
40
+
41
+ ```ruby
42
+ # Dans vos modèles
43
+ class Article < ApplicationRecord
44
+ after_save :schedule_translation, if: :should_translate?
45
+
46
+ private
47
+
48
+ def schedule_translation
49
+ TranslateRecordJob.perform_later(
50
+ self.class.name, id, translatable_fields
51
+ )
52
+ end
53
+
54
+ def should_translate?
55
+ saved_changes.keys.any? { |field| field.end_with?("_#{I18n.locale}") }
56
+ end
57
+ end
58
+ ```
59
+
60
+ ## Job par Batch
61
+
62
+ ```ruby
63
+ class BatchTranslateJob < ApplicationJob
64
+ def perform(records_data)
65
+ records_data.each do |data|
66
+ model = data[:model].constantize.find(data[:id])
67
+ # Traduction avec délai anti-rate limit
68
+ sleep(2)
69
+ end
70
+ end
71
+ end
72
+ ```
73
+
74
+ ## Patterns Recommandés
75
+
76
+ **Déclenchement :**
77
+
78
+ - `after_save` callbacks pour traduction automatique
79
+ - Jobs programmés pour traduction différée
80
+ - Webhooks pour traduction sur événements
81
+
82
+ **Files :**
83
+
84
+ - Queue dédiée `translations`
85
+ - Priorité basse pour éviter de bloquer l'app
86
+ - Retry intelligent selon le type d'erreur
87
+
88
+ **Optimisations :**
89
+
90
+ - Batch des traductions par langue cible
91
+ - Cache des traductions fréquentes
92
+ - Rate limiting avec `sleep()` entre requêtes
93
+
94
+ ---
95
+
96
+ **Rails Integration Navigation:**
97
+ [← Setup](rails-integration/setup.md) | [Adapters](rails-integration/adapters.md) | [Jobs](rails-integration/jobs.md) | [Controllers](rails-integration/controllers.md) →