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
@@ -0,0 +1,141 @@
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
+ # Traductions Avancées
6
+
7
+ Fonctionnalités avancées : contexte, glossaires, HTML, auto-détection, score de confiance.
8
+
9
+ ## 🎯 Contexte
10
+
11
+ Améliore la qualité en donnant des indices sur le domaine et l'usage.
12
+
13
+ ```ruby
14
+ translator = MistralTranslator::Translator.new
15
+
16
+ translator.translate(
17
+ "Batterie faible",
18
+ from: "fr",
19
+ to: "en",
20
+ context: "Smartphone notification alert"
21
+ )
22
+ # => "Battery low"
23
+
24
+ # vs sans contexte
25
+ # => "Low battery"
26
+ ```
27
+
28
+ **Contextes utiles :**
29
+
30
+ - `"Medical documentation"`
31
+ - `"E-commerce product page"`
32
+ - `"Technical documentation"`
33
+ - `"Marketing email"`
34
+
35
+ ## 📚 Glossaires
36
+
37
+ Garantit la cohérence terminologique.
38
+
39
+ ```ruby
40
+ tech_glossary = {
41
+ "IA" => "AI",
42
+ "apprentissage automatique" => "machine learning",
43
+ "données" => "data"
44
+ }
45
+
46
+ translator.translate(
47
+ "L'IA utilise l'apprentissage automatique",
48
+ from: "fr",
49
+ to: "en",
50
+ glossary: tech_glossary
51
+ )
52
+ # => "AI uses machine learning"
53
+ ```
54
+
55
+ ## 🎨 Préservation HTML
56
+
57
+ Traduit le contenu en gardant la structure HTML.
58
+
59
+ ```ruby
60
+ html = "<h1>Bienvenue</h1><p>Découvrez nos <strong>services</strong></p>"
61
+
62
+ translator.translate(
63
+ html,
64
+ from: "fr",
65
+ to: "en",
66
+ preserve_html: true
67
+ )
68
+ # => "<h1>Welcome</h1><p>Discover our <strong>services</strong></p>"
69
+ ```
70
+
71
+ ## 🔍 Auto-détection
72
+
73
+ Détecte automatiquement la langue source.
74
+
75
+ ```ruby
76
+ MistralTranslator.translate_auto("Guten Tag", to: "fr")
77
+ # => "Bonjour"
78
+
79
+ MistralTranslator.translate_auto("¿Cómo estás?", to: "en")
80
+ # => "How are you?"
81
+ ```
82
+
83
+ ## 📊 Score de Confiance
84
+
85
+ Évalue la qualité de la traduction.
86
+
87
+ ```ruby
88
+ result = MistralTranslator.translate_with_confidence(
89
+ "Le chat mange",
90
+ from: "fr",
91
+ to: "en"
92
+ )
93
+
94
+ puts result[:translation] # => "The cat eats"
95
+ puts result[:confidence] # => 0.92
96
+ ```
97
+
98
+ **Seuils recommandés :**
99
+
100
+ - `> 0.9` : Excellente qualité
101
+ - `0.7-0.9` : Bonne qualité
102
+ - `< 0.7` : Révision recommandée
103
+
104
+ ## 🌍 Multi-langues
105
+
106
+ Traduit vers plusieurs langues simultanément.
107
+
108
+ ```ruby
109
+ translator = MistralTranslator::Translator.new
110
+
111
+ results = translator.translate_to_multiple(
112
+ "Bienvenue",
113
+ from: "fr",
114
+ to: ["en", "es", "de"],
115
+ use_batch: true # Optimisation
116
+ )
117
+
118
+ # => { "en" => "Welcome", "es" => "Bienvenido", "de" => "Willkommen" }
119
+ ```
120
+
121
+ ## 🎛️ Combinaisons Avancées
122
+
123
+ ```ruby
124
+ # Contexte + Glossaire + HTML
125
+ translator = MistralTranslator::Translator.new
126
+
127
+ translator.translate(
128
+ "<p>Notre <strong>IA</strong> révolutionne le secteur</p>",
129
+ from: "fr",
130
+ to: "en",
131
+ context: "Technology marketing",
132
+ glossary: { "IA" => "AI" },
133
+ preserve_html: true
134
+ )
135
+ # => "<p>Our <strong>AI</strong> revolutionizes the industry</p>"
136
+ ```
137
+
138
+ ---
139
+
140
+ **Advanced Usage Navigation:**
141
+ [← 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) →
@@ -0,0 +1,231 @@
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
+ # Référence des Callbacks API
6
+
7
+ ## Callbacks Disponibles
8
+
9
+ ### `on_translation_start`
10
+
11
+ **Déclenchement:** Avant chaque traduction
12
+
13
+ **Paramètres:** `from_locale, to_locale, text_length, timestamp`
14
+
15
+ ```ruby
16
+ MistralTranslator.configure do |config|
17
+ config.on_translation_start = ->(from, to, length, timestamp) {
18
+ Rails.logger.info "🚀 #{from}→#{to} (#{length} chars)"
19
+ }
20
+ end
21
+ ```
22
+
23
+ ### `on_translation_complete`
24
+
25
+ **Déclenchement:** Après chaque traduction réussie
26
+
27
+ **Paramètres:** `from_locale, to_locale, original_length, translated_length, duration`
28
+
29
+ ```ruby
30
+ config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
31
+ Rails.logger.info "✅ #{from}→#{to} in #{duration.round(2)}s"
32
+
33
+ # Métriques custom
34
+ StatsTracker.record(:translation, {
35
+ languages: "#{from}_to_#{to}",
36
+ duration: duration,
37
+ efficiency: trans_len.to_f / orig_len
38
+ })
39
+ }
40
+ ```
41
+
42
+ ### `on_translation_error`
43
+
44
+ **Déclenchement:** Lors d'erreurs de traduction
45
+
46
+ **Paramètres:** `from_locale, to_locale, error, attempt, timestamp`
47
+
48
+ ```ruby
49
+ config.on_translation_error = ->(from, to, error, attempt, timestamp) {
50
+ Rails.logger.error "❌ #{from}→#{to} attempt #{attempt}: #{error.message}"
51
+
52
+ # Notification externe
53
+ Sentry.capture_exception(error, extra: { from: from, to: to, attempt: attempt })
54
+ }
55
+ ```
56
+
57
+ ### `on_rate_limit`
58
+
59
+ **Déclenchement:** Lors de rate limiting
60
+
61
+ **Paramètres:** `from_locale, to_locale, wait_time, attempt, timestamp`
62
+
63
+ ```ruby
64
+ config.on_rate_limit = ->(from, to, wait_time, attempt, timestamp) {
65
+ Rails.logger.warn "⏳ Rate limit #{from}→#{to}, waiting #{wait_time}s (attempt #{attempt})"
66
+
67
+ # Slack notification pour rate limits fréquents
68
+ SlackNotifier.warn("Translation rate limit hit") if attempt > 3
69
+ }
70
+ ```
71
+
72
+ ### `on_batch_complete`
73
+
74
+ **Déclenchement:** Après completion d'un batch
75
+
76
+ **Paramètres:** `batch_size, total_duration, success_count, error_count`
77
+
78
+ ```ruby
79
+ config.on_batch_complete = ->(size, duration, success, errors) {
80
+ Rails.logger.info "📦 Batch: #{success}/#{size} success in #{duration.round(2)}s"
81
+
82
+ # Alertes si trop d'erreurs
83
+ if errors > size * 0.1 # Plus de 10% d'erreurs
84
+ AlertService.notify("High batch error rate: #{errors}/#{size}")
85
+ end
86
+ }
87
+ ```
88
+
89
+ ## Configuration Rapide
90
+
91
+ ### Setup Rails Automatique
92
+
93
+ ```ruby
94
+ MistralTranslator.configure do |config|
95
+ config.api_key = ENV['MISTRAL_API_KEY']
96
+ config.enable_metrics = true
97
+ config.setup_rails_logging # Configure tous les callbacks Rails
98
+ end
99
+ ```
100
+
101
+ ### Setup Custom Complet
102
+
103
+ ```ruby
104
+ MistralTranslator.configure do |config|
105
+ # Métriques
106
+ config.enable_metrics = true
107
+
108
+ # Callbacks essentiels
109
+ config.on_translation_start = ->(from, to, length, ts) {
110
+ Rails.cache.increment("translations_started")
111
+ }
112
+
113
+ config.on_translation_complete = ->(from, to, orig, trans, dur) {
114
+ # Cache performance data
115
+ Rails.cache.write("last_translation_time", dur)
116
+ Rails.cache.increment("translations_completed")
117
+ }
118
+
119
+ config.on_translation_error = ->(from, to, error, attempt, ts) {
120
+ # Structured logging
121
+ Rails.logger.error({
122
+ event: "translation_error",
123
+ from: from, to: to,
124
+ error: error.class.name,
125
+ attempt: attempt,
126
+ timestamp: ts
127
+ }.to_json)
128
+ }
129
+ end
130
+ ```
131
+
132
+ ## Patterns Utiles
133
+
134
+ ### Circuit Breaker avec Callbacks
135
+
136
+ ```ruby
137
+ class TranslationCircuitBreaker
138
+ def self.setup!
139
+ @failure_count = 0
140
+ @last_reset = Time.now
141
+
142
+ MistralTranslator.configure do |config|
143
+ config.on_translation_error = method(:on_error)
144
+ config.on_translation_complete = method(:on_success)
145
+ end
146
+ end
147
+
148
+ def self.on_error(from, to, error, attempt, timestamp)
149
+ @failure_count += 1
150
+ if @failure_count > 5 && Time.now - @last_reset < 300 # 5 min
151
+ Rails.cache.write("translation_circuit_open", true, expires_in: 10.minutes)
152
+ end
153
+ end
154
+
155
+ def self.on_success(from, to, orig, trans, duration)
156
+ @failure_count = 0 if @failure_count > 0
157
+ end
158
+ end
159
+ ```
160
+
161
+ ### Adaptive Rate Limiting
162
+
163
+ ```ruby
164
+ class AdaptiveRateManager
165
+ def self.setup!
166
+ @success_rate = 1.0
167
+
168
+ MistralTranslator.configure do |config|
169
+ config.on_rate_limit = method(:on_rate_limit)
170
+ config.on_translation_complete = method(:on_success)
171
+ end
172
+ end
173
+
174
+ def self.on_rate_limit(from, to, wait_time, attempt, timestamp)
175
+ # Réduire la fréquence des futures requêtes
176
+ @success_rate *= 0.8
177
+ Rails.cache.write("translation_delay", 2.0 / @success_rate)
178
+ end
179
+
180
+ def self.on_success(from, to, orig, trans, duration)
181
+ # Gradually increase rate
182
+ @success_rate = [@success_rate * 1.1, 1.0].min
183
+ end
184
+ end
185
+ ```
186
+
187
+ ### Monitoring Dashboard Data
188
+
189
+ ```ruby
190
+ class TranslationMetrics
191
+ def self.setup_callbacks!
192
+ MistralTranslator.configure do |config|
193
+ config.on_translation_complete = method(:track_success)
194
+ config.on_translation_error = method(:track_error)
195
+ config.on_batch_complete = method(:track_batch)
196
+ end
197
+ end
198
+
199
+ def self.track_success(from, to, orig_len, trans_len, duration)
200
+ Redis.current.multi do |r|
201
+ r.incr("translations:#{Date.current}:success")
202
+ r.incr("translations:#{from}_to_#{to}:count")
203
+ r.lpush("translations:durations", duration)
204
+ r.ltrim("translations:durations", 0, 999) # Keep last 1000
205
+ end
206
+ end
207
+
208
+ def self.track_error(from, to, error, attempt, timestamp)
209
+ Redis.current.multi do |r|
210
+ r.incr("translations:#{Date.current}:errors")
211
+ r.incr("translations:#{error.class.name}:count")
212
+ end
213
+ end
214
+
215
+ def self.get_dashboard_data
216
+ {
217
+ today_success: Redis.current.get("translations:#{Date.current}:success").to_i,
218
+ today_errors: Redis.current.get("translations:#{Date.current}:errors").to_i,
219
+ avg_duration: Redis.current.lrange("translations:durations", 0, -1)
220
+ .map(&:to_f).sum / 1000.0,
221
+ language_pairs: Redis.current.keys("translations:*_to_*:count")
222
+ .map { |k| [k.split(':')[1], Redis.current.get(k).to_i] }
223
+ }
224
+ end
225
+ end
226
+ ```
227
+
228
+ ---
229
+
230
+ **API-Reference Navigation:**
231
+ [← Methods](api-reference/methods.md) | [Errors](api-reference/errors.md) | [Callbacks](api-reference/callbacks.md) | [Configuration](api-reference/configuration.md) →
@@ -0,0 +1,74 @@
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
+ # Configuration API
6
+
7
+ Référence complète des options de configuration.
8
+
9
+ ## Options Principales
10
+
11
+ ```ruby
12
+ MistralTranslator.configure do |config|
13
+ config.api_key = ENV['MISTRAL_API_KEY'] # Obligatoire
14
+ config.model = "mistral-small" # Défaut
15
+ config.api_url = "https://api.mistral.ai" # URL API
16
+ config.default_max_tokens = 4000 # Limite tokens
17
+ config.default_temperature = 0.3 # Créativité (0-1)
18
+ config.retry_delays = [2, 4, 8, 16, 32] # Délais retry (secondes)
19
+ config.enable_metrics = false # Suivi des stats
20
+ end
21
+ ```
22
+
23
+ ## Callbacks
24
+
25
+ ```ruby
26
+ config.on_translation_start = ->(from, to, length, timestamp) { }
27
+ config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) { }
28
+ config.on_translation_error = ->(from, to, error, attempt, timestamp) { }
29
+ config.on_rate_limit = ->(from, to, wait_time, attempt, timestamp) { }
30
+ config.on_batch_complete = ->(batch_size, duration, success, errors) { }
31
+ ```
32
+
33
+ ## Métriques
34
+
35
+ ```ruby
36
+ # Activer
37
+ config.enable_metrics = true
38
+
39
+ # Consulter
40
+ MistralTranslator.metrics
41
+ # => {
42
+ # total_translations: 42,
43
+ # average_translation_time: 1.2,
44
+ # error_rate: 2.1,
45
+ # translations_by_language: {...}
46
+ # }
47
+
48
+ # Réinitialiser
49
+ MistralTranslator.reset_metrics!
50
+ ```
51
+
52
+ ## Helper Rails
53
+
54
+ ```ruby
55
+ # Configuration Rails automatique
56
+ config.setup_rails_logging # Active les logs Rails standard
57
+ ```
58
+
59
+ ## Validation
60
+
61
+ ```ruby
62
+ # Test de configuration
63
+ MistralTranslator.health_check
64
+ # => { status: :ok, message: "API connection successful" }
65
+
66
+ # Langues supportées
67
+ MistralTranslator.supported_locales
68
+ # => ["fr", "en", "es", "pt", "de", "it", "nl", "ru", "mg", "ja", "ko", "zh", "ar"]
69
+ ```
70
+
71
+ ---
72
+
73
+ **API-Reference Navigation:**
74
+ [← Methods](api-reference/methods.md) | [Errors](api-reference/errors.md) | [Callbacks](api-reference/callbacks.md) | [Configuration](api-reference/configuration.md) →