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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +21 -0
- data/README.md +189 -121
- data/README_TESTING.md +33 -0
- data/SECURITY.md +157 -0
- data/docs/.nojekyll +2 -0
- data/docs/404.html +30 -0
- data/docs/README.md +153 -0
- data/docs/advanced-usage/batch-processing.md +158 -0
- data/docs/advanced-usage/error-handling.md +106 -0
- data/docs/advanced-usage/monitoring.md +133 -0
- data/docs/advanced-usage/summarization.md +86 -0
- data/docs/advanced-usage/translations.md +141 -0
- data/docs/api-reference/callbacks.md +231 -0
- data/docs/api-reference/configuration.md +74 -0
- data/docs/api-reference/errors.md +673 -0
- data/docs/api-reference/methods.md +539 -0
- data/docs/getting-started.md +179 -0
- data/docs/index.html +27 -0
- data/docs/installation.md +142 -0
- data/docs/migration-0.1.0-to-0.2.0.md +61 -0
- data/docs/rails-integration/adapters.md +84 -0
- data/docs/rails-integration/controllers.md +107 -0
- data/docs/rails-integration/jobs.md +97 -0
- data/docs/rails-integration/setup.md +339 -0
- data/examples/basic_usage.rb +129 -102
- data/examples/batch-job.rb +511 -0
- data/examples/monitoring-setup.rb +499 -0
- data/examples/rails-model.rb +399 -0
- data/lib/mistral_translator/adapters.rb +261 -0
- data/lib/mistral_translator/client.rb +103 -100
- data/lib/mistral_translator/client_helpers.rb +161 -0
- data/lib/mistral_translator/configuration.rb +171 -1
- data/lib/mistral_translator/errors.rb +16 -0
- data/lib/mistral_translator/helpers.rb +292 -0
- data/lib/mistral_translator/helpers_extensions.rb +150 -0
- data/lib/mistral_translator/levenshtein_helpers.rb +40 -0
- data/lib/mistral_translator/logger.rb +28 -4
- data/lib/mistral_translator/prompt_builder.rb +93 -41
- data/lib/mistral_translator/prompt_helpers.rb +83 -0
- data/lib/mistral_translator/prompt_metadata_helpers.rb +42 -0
- data/lib/mistral_translator/response_parser.rb +194 -23
- data/lib/mistral_translator/security.rb +72 -0
- data/lib/mistral_translator/summarizer.rb +41 -2
- data/lib/mistral_translator/translator.rb +174 -98
- data/lib/mistral_translator/translator_helpers.rb +268 -0
- data/lib/mistral_translator/version.rb +1 -1
- data/lib/mistral_translator.rb +51 -25
- 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) →
|