mistral_translator 0.4.0 → 0.6.0

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9ecf7ff10300ed8793126b3417e1b26444daf4c6778ac13d95224880175cb96c
4
- data.tar.gz: 5ade2f503013b9b539831e9dfddb830fdd68ca6e8a98762a1a0cd97f2d0d1f63
3
+ metadata.gz: b22420512964b68bed142cf6a3321456342be0e2cfb20296250786b054307642
4
+ data.tar.gz: 9c2e3ae8f96a65bd331ed3e81f47c22a064ef8141dc43327f5e76c1322d79ffa
5
5
  SHA512:
6
- metadata.gz: 23afe648e77f352c771231bee584b0a2cee50c1bf3a2c4c747bf24874a0aeca4c9304fd1f0c8e34cd732591d4551235258d0091a4624f82879235bab737708f2
7
- data.tar.gz: cd5c9ab42a3369c70ac0d9716e263f25eaf38e7541c8dc18533b1c603db14d6d96c6e628c074bc13e9471ebd2e51b034e946432e8bdca0d0ed1d511fea9bc9cf
6
+ metadata.gz: 9eeb4e98442dfb7fff7a4549794e15186387733ff7a07eb9c5bc6c3a9464de02f417433477317e305b90055e1140c537a5312cdb9c1c5c4c4525b981e7c86bc6
7
+ data.tar.gz: 761772d205f97f680c6efaf3dff60953e62f62e995394a79bc9a284a27aceaca5c522271d139744aad49ca5f75d8549b5f13b05f421211374c9bfd313cb23373
data/CHANGELOG.md CHANGED
@@ -1,4 +1,55 @@
1
- ## [Unreleased]
1
+ ## [0.6.0] - 2026-11-17
2
+
3
+ ### Added
4
+
5
+ - 437 languages that only have an ISO 639-3 code (`haw`, `yue`, `fil`…), 619 in all. The ISO 639-3 code of a two-letter language is accepted in its place (`hat` for `ht`).
6
+ - Scripts and regions: `pt-BR`, `zh-Hant-TW`, `es-419`, any combination of the scripts and regions CLDR names. The prompt names the variant, such as « portugais (Brésil) (pt-BR) ».
7
+ - `MistralTranslator::Locale`, a value object that reads a locale (`Locale.parse`, or `Locale.find`, which returns `nil` instead of raising) and gives its canonical form (`to_s`).
8
+ - Language names work wherever a locale is expected: `translate(text, from: "fr", to: "allemand")`. They only worked in locale suggestions. A name several languages share, such as "konkani", is rejected: use the code.
9
+ - `bin/generate_languages` also writes `scripts.json` and `regions.json`.
10
+
11
+ ### Changed
12
+
13
+ Only regional locales and locales with extensions are affected; two-letter codes behave as before.
14
+
15
+ - A locale keeps its region. `translate_to_multiple(text, from: "en", to: ["pt-BR"])` returns `{ "pt-BR" => … }` instead of `{ "pt" => … }`, and `validate_locale!("pt-BR")` returns `"pt-BR"` instead of `"pt"`. Before, `pt-BR` and `pt-PT` in the same call overwrote each other.
16
+ - Two variants of a language are no longer the same locale: from `fr` to `fr-CA`, the text is translated by the API instead of being returned unchanged. A Rails app with `fr` and `fr-CA` locales now gets an adapted translation, for one more request.
17
+ - Variants and extensions (`ca-ES-valencia`, `en-US-u-ca-gregory`) raise `UnsupportedLanguageError`. Their subtags used to be dropped silently, leaving the language only.
18
+ - `locale_supported?` returns `true` for language names, which `translate` now accepts.
19
+
20
+ ## [0.5.0] - 2026-10-29
21
+
22
+ ### Added
23
+
24
+ - `config.read_timeout`: how long to wait for the API's answer, in seconds. Defaults to 60, the value the gem used until now; anything but a positive number raises `ConfigurationError` when it is set.
25
+ - `config.open_timeout`: how long to wait for the connection to open (TCP, then TLS), in seconds. Defaults to 60, validated the same way.
26
+
27
+ ### Changed
28
+
29
+ No change to translation results:
30
+
31
+ - Translations and summaries share one retry policy, with the same delays and counts as before. Their retry log lines now share one format, such as `translation retry 1/3 for fr->en in 2s: …`.
32
+ - The `Summarizer` no longer prints to stdout when `MISTRAL_TRANSLATOR_TEST_OUTPUT` is set.
33
+ - A response is parsed once instead of twice.
34
+
35
+ ### Deprecated
36
+
37
+ These options still work, print a warning, and will be removed in 1.0:
38
+
39
+ - `config.ssl_timeout`, the former name of `open_timeout`, which it still sets. It is now validated like `open_timeout`, so `nil` (no limit) is rejected.
40
+ - `config.default_max_tokens` and `config.default_temperature`, which the gem never read.
41
+
42
+ ### Removed
43
+
44
+ Undocumented code that the gem never called:
45
+
46
+ - the `HelpersExtensions` copies of `translate_with_progress`, `translate_multi_style` and `find_locale_suggestions`, which `Helpers` redefines;
47
+ - `TranslatorHelpers::RetryHandler`, `TranslatorHelpers::LoggingHelper` and `InputValidator#validate_batch_inputs!`;
48
+ - `PromptBuilder.bulk_translation_prompt`, `PromptBuilder.tiered_summary_prompt`, `PromptHelpers::FormatInstructions`, `ResponseParser.parse_bulk_translation_response` and `ResponseParser::JsonParserState`.
49
+
50
+ ### Security
51
+
52
+ - When the scan for a JSON object inside text reached its limit, the error kept the `JSON::ParserError` as its `cause`, and that error quotes the response.
2
53
 
3
54
  ## [0.4.0] - 2026-10-28
4
55
 
data/README.md CHANGED
@@ -37,7 +37,16 @@ MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
37
37
 
38
38
  ## Supported Languages
39
39
 
40
- All 182 ISO 639-1 languages named by CLDR (`fr`, `en`, `es`, `de`, `ja`, `br`, `wo`, `mg`…). `MistralTranslator.supported_locales` lists them, and English or French names are accepted in place of codes (`"German"`, `"allemand"`).
40
+ Every language CLDR names, 619 in all: the 182 ISO 639-1 languages (`fr`, `en`, `ja`, `ht`, `wo`…) and the languages that only have an ISO 639-3 code (`haw`, `yue`, `fil`…). `MistralTranslator.supported_locales` lists them.
41
+
42
+ A locale can add a script and a region (`pt-BR`, `zh-Hant-TW`, `es-419`): the model is told which variant to write, and results are keyed by that locale. ISO 639-3 codes (`hat` for `ht`) and English, French or native names (`"German"`, `"allemand"`) are accepted in place of codes. Variants and extensions (`ca-ES-valencia`, `en-US-u-ca-gregory`) are not.
43
+
44
+ ```ruby
45
+ MistralTranslator.translate(text, from: "fr", to: "pt-BR")
46
+ MistralTranslator::Locale.parse("zh_hant_tw").to_s # => "zh-Hant-TW"
47
+ ```
48
+
49
+ The languages, scripts and regions come from the CLDR data of macOS 27.2, through `bin/generate_languages` (2026-11-17).
41
50
 
42
51
  Translation quality depends on the Mistral model: excellent for widely used languages, weaker for rare ones. Check the output before relying on a rare language.
43
52
 
@@ -166,6 +175,9 @@ MistralTranslator.configure do |config|
166
175
  config.enable_metrics = true # Enable performance metrics
167
176
  config.proxy = :env # HTTP proxy: nil (default), "http://host:port", or :env
168
177
  # to read HTTPS_PROXY / HTTP_PROXY and NO_PROXY
178
+ config.open_timeout = 60 # Seconds to open the connection (default 60)
179
+ config.read_timeout = 60 # Seconds to wait for the API's answer (default 60);
180
+ # raise it for long texts or summaries
169
181
 
170
182
  # Callbacks for monitoring
171
183
  config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
@@ -178,6 +190,8 @@ MistralTranslator.configure do |config|
178
190
  end
179
191
  ```
180
192
 
193
+ Configure the gem before the first call. The module-level methods (`MistralTranslator.translate`, `summarize`…) share one client, which reads `api_key`, `model`, `api_url`, `retry_delays` and the connection settings (`read_timeout`, `proxy`, SSL) on the first call. To change them afterwards, call `MistralTranslator.reset_configuration!` and configure again, or create a `MistralTranslator::Translator.new` (or `Summarizer.new`), which builds its own client from the current configuration.
194
+
181
195
  ## Error Handling
182
196
 
183
197
  ```ruby
@@ -13,14 +13,37 @@ MistralTranslator.configure do |config|
13
13
  config.api_key = ENV['MISTRAL_API_KEY'] # Obligatoire
14
14
  config.model = "mistral-small-latest" # Défaut
15
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
16
  config.retry_delays = [2, 4, 8, 16, 32] # Délais retry (secondes)
19
17
  config.enable_metrics = false # Suivi des stats
20
18
  config.proxy = nil # Proxy HTTP (désactivé par défaut)
19
+ config.open_timeout = 60 # Ouverture de la connexion (secondes)
20
+ config.read_timeout = 60 # Attente maximale de la réponse (secondes)
21
21
  end
22
22
  ```
23
23
 
24
+ Configurez la gem avant le premier appel. Les méthodes du module (`MistralTranslator.translate`, `summarize`…) partagent un client, qui lit `api_key`, `model`, `api_url`, `retry_delays` et les réglages de connexion (`read_timeout`, `proxy`, SSL) lors du premier appel. Pour les changer ensuite, appelez `MistralTranslator.reset_configuration!` puis configurez à nouveau, ou créez un `MistralTranslator::Translator.new` (ou `Summarizer.new`), qui construit son propre client avec la configuration du moment.
25
+
26
+ ## Délais
27
+
28
+ Deux délais, en secondes, 60 par défaut :
29
+
30
+ - `open_timeout` : ouverture de la connexion à l'API (TCP puis TLS) ;
31
+ - `read_timeout` : attente de la réponse. Un long texte ou un résumé détaillé peut demander plus au modèle ; augmentez-le dans ce cas.
32
+
33
+ ```ruby
34
+ config.read_timeout = 180
35
+ ```
36
+
37
+ - Seul un nombre strictement positif est accepté (entier ou décimal) ; toute autre valeur lève `ConfigurationError` dès l'affectation.
38
+ - Délai de réponse dépassé : la requête lève `ApiError` (« Request timeout »).
39
+
40
+ ## Options obsolètes
41
+
42
+ Elles fonctionnent encore, avec un avertissement, et seront retirées en 1.0 :
43
+
44
+ - `ssl_timeout` : ancien nom d'`open_timeout`, qu'il règle toujours ;
45
+ - `default_max_tokens` et `default_temperature` : jamais lues par la gem, elles n'ont aucun effet. Pour régler ces paramètres, passez `max_tokens:` et `temperature:` à `Client#chat` ou `Client#complete`.
46
+
24
47
  ## Proxy
25
48
 
26
49
  Désactivé par défaut. Trois valeurs possibles :
@@ -80,9 +103,9 @@ config.setup_rails_logging # Active les logs Rails standard
80
103
  MistralTranslator.health_check
81
104
  # => { status: :ok, message: "API connection successful" }
82
105
 
83
- # Langues supportées : les 182 codes ISO 639-1
106
+ # Langues supportées : 619 codes ISO 639-1 et ISO 639-3
84
107
  MistralTranslator.supported_locales
85
- # => ["aa", "ab", "ae", "af", ..., "zh", "zu"]
108
+ # => ["aa", "ab", "ace", "acf", ..., "zun", "zza"]
86
109
  ```
87
110
 
88
111
  ---
@@ -290,21 +290,21 @@ puts result # => "" (sans erreur)
290
290
 
291
291
  ```ruby
292
292
  MistralTranslator.supported_locales
293
- # => ["fr", "en", "es", "pt", "de", "it", "nl", "ru", "mg", "ja", "ko", "zh", "ar"]
293
+ # => ["aa", "ab", "ace", "acf", ..., "zun", "zza"] (619 langues)
294
294
  ```
295
295
 
296
296
  **Exemple:**
297
297
 
298
298
  ```ruby
299
299
  begin
300
- MistralTranslator.translate("Hello", from: "en", to: "klingon")
300
+ MistralTranslator.translate("Hello", from: "en", to: "dothraki")
301
301
  rescue MistralTranslator::UnsupportedLanguageError => e
302
302
  puts "Unsupported language: #{e.message}"
303
303
  puts "Language requested: #{e.language}"
304
- # => "klingon"
304
+ # => "dothraki"
305
305
 
306
306
  # Obtenir des suggestions :
307
- suggestions = MistralTranslator::Helpers.validate_locale_with_suggestions("klingon")
307
+ suggestions = MistralTranslator::Helpers.validate_locale_with_suggestions("dothraki")
308
308
  if suggestions[:suggestions].any?
309
309
  puts "Did you mean: #{suggestions[:suggestions].join(', ')}?"
310
310
  end
@@ -315,7 +315,7 @@ end
315
315
 
316
316
  - Utiliser `MistralTranslator.supported_locales` pour voir les langues disponibles
317
317
  - Utiliser le helper de validation avec suggestions
318
- - Normaliser les codes de langue (ex: "français" → "fr")
318
+ - Vérifier le code : `"pt-BR"`, `"zh-Hant"`, `"haw"` ou un nom comme `"allemand"` sont acceptés ; les variantes et extensions BCP 47 (`"ca-ES-valencia"`) ne le sont pas
319
319
 
320
320
  ---
321
321
 
@@ -647,7 +647,7 @@ describe "error handling" do
647
647
  it "provides fallback for unsupported languages" do
648
648
  result = translate_with_fallback(
649
649
  "Hello",
650
- from: "klingon",
650
+ from: "dothraki",
651
651
  to: "fr",
652
652
  fallback: "Hello"
653
653
  )
@@ -298,7 +298,7 @@ Remet la configuration aux valeurs par défaut.
298
298
 
299
299
  Retourne la liste des codes de langue supportés.
300
300
 
301
- **Retour:** Array<String> - Liste des 182 codes ISO 639-1 (ex: ["aa", "ab", ..., "zu"])
301
+ **Retour:** Array<String> - Les 619 codes de langue, ISO 639-1 et ISO 639-3 (ex: ["aa", "ab", "ace", ..., "zza"]). Une locale peut y ajouter une écriture et une région (`"zh-Hant-TW"`).
302
302
 
303
303
  ### `supported_languages`
304
304
 
@@ -467,7 +467,7 @@ Validation de locale avec suggestions.
467
467
  **Retour:** Hash
468
468
 
469
469
  - `valid` (Boolean) - Locale valide ou non
470
- - `locale` (String) - Locale normalisée (si valide)
470
+ - `locale` (String) - Locale canonique, région comprise (ex: `"pt-BR"`), si valide
471
471
  - `suggestions` (Array) - Suggestions (si invalide)
472
472
 
473
473
  ##### `estimate_translation_cost(text, from:, to:, rate_per_1k_chars:)`
@@ -39,19 +39,25 @@ MistralTranslator.translate_auto("Guten Tag", to: "fr")
39
39
  ## 🌍 Langues Supportées
40
40
 
41
41
  ```ruby
42
- # Les 182 langues ISO 639-1 sont disponibles
42
+ # 619 langues : codes ISO 639-1 (deux lettres) et ISO 639-3 (trois lettres)
43
43
  MistralTranslator::LocaleHelper.supported_locales
44
- # => ["aa", "ab", "ae", "af", ..., "zh", "zu"]
44
+ # => ["aa", "ab", "ace", "acf", ..., "zun", "zza"]
45
45
 
46
- # Les noms anglais et français sont acceptés à la place du code
47
- MistralTranslator::LocaleHelper.language_to_locale("allemand")
48
- # => "de"
46
+ # Une écriture et une région précisent la variante
47
+ MistralTranslator.translate("Bonjour", from: "fr", to: "pt-BR")
48
+ MistralTranslator.translate("Bonjour", from: "fr", to: "zh-Hant-TW")
49
+
50
+ # Les noms de langue et les codes ISO 639-3 sont acceptés à la place du code
51
+ MistralTranslator::Locale.parse("allemand").to_s # => "de"
52
+ MistralTranslator::Locale.parse("hat").to_s # => "ht"
49
53
 
50
54
  # Vérifier une langue spécifique
51
55
  MistralTranslator::LocaleHelper.locale_supported?("ja")
52
56
  # => true
53
57
  ```
54
58
 
59
+ Les langues, écritures et régions viennent des données CLDR de macOS 27.2, via `bin/generate_languages` (2026-11-17). Les variantes et extensions BCP 47 (`ca-ES-valencia`, `en-US-u-ca-gregory`) ne sont pas acceptées.
60
+
55
61
  La qualité de traduction dépend du modèle Mistral : excellente pour les langues les plus parlées, plus faible pour les langues rares. Vérifiez le résultat avant de vous appuyer sur une langue rare.
56
62
 
57
63
  ## 🚨 Gestion d'Erreurs Simple
data/docs/installation.md CHANGED
@@ -79,8 +79,6 @@ MistralTranslator.configure do |config|
79
79
  config.model = "mistral-small-latest" # Modèle par défaut
80
80
  config.retry_delays = [2, 4, 8, 16] # Délais retry
81
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
82
  end
85
83
  ```
86
84
 
@@ -272,7 +272,6 @@ MistralTranslator.configure do |config|
272
272
 
273
273
  # Optimisation Rails
274
274
  config.enable_metrics = true
275
- config.default_max_tokens = 4000
276
275
 
277
276
  # Cache intelligent des traductions
278
277
  config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
@@ -30,9 +30,9 @@ module MistralTranslator
30
30
  def http_pool
31
31
  @http_pool ||= begin
32
32
  pool = Net::HTTP::Persistent.new(name: "mistral_translator")
33
- pool.read_timeout = 60
33
+ pool.read_timeout = MistralTranslator.configuration.read_timeout
34
34
  pool.idle_timeout = 30
35
- pool.open_timeout = MistralTranslator.configuration.ssl_timeout
35
+ pool.open_timeout = MistralTranslator.configuration.open_timeout
36
36
  pool.max_requests = 100
37
37
 
38
38
  # SSL/TLS configuration
@@ -1,14 +1,17 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "proxy"
4
+ require_relative "deprecated_options"
4
5
 
5
6
  module MistralTranslator
6
7
  class Configuration
7
- attr_accessor :api_key, :model, :default_max_tokens, :default_temperature, :retry_delays,
8
+ include DeprecatedOptions
9
+
10
+ attr_accessor :api_key, :model, :retry_delays,
8
11
  :on_translation_start, :on_translation_complete, :on_translation_error,
9
12
  :on_rate_limit, :on_batch_complete, :enable_metrics,
10
- :ssl_verify_mode, :ssl_ca_file, :ssl_ca_path, :ssl_timeout
11
- attr_reader :api_url, :proxy
13
+ :ssl_verify_mode, :ssl_ca_file, :ssl_ca_path
14
+ attr_reader :api_url, :proxy, :open_timeout, :read_timeout
12
15
 
13
16
  def initialize
14
17
  @api_key = nil
@@ -30,7 +33,10 @@ module MistralTranslator
30
33
  @ssl_verify_mode = :peer # :peer, :none, or OpenSSL constant
31
34
  @ssl_ca_file = nil # Path to CA certificate file
32
35
  @ssl_ca_path = nil # Path to CA certificates directory
33
- @ssl_timeout = 60 # SSL handshake timeout in seconds
36
+
37
+ # Délais en secondes : ouverture de la connexion (TCP puis TLS), puis attente de la réponse
38
+ @open_timeout = 60
39
+ @read_timeout = 60
34
40
 
35
41
  # Proxy : nil (aucun), URI ou String, ou :env (HTTPS_PROXY, HTTP_PROXY, NO_PROXY)
36
42
  @proxy = nil
@@ -66,6 +72,14 @@ module MistralTranslator
66
72
  @proxy = value
67
73
  end
68
74
 
75
+ def open_timeout=(seconds)
76
+ @open_timeout = positive_seconds!(:open_timeout, seconds)
77
+ end
78
+
79
+ def read_timeout=(seconds)
80
+ @read_timeout = positive_seconds!(:read_timeout, seconds)
81
+ end
82
+
69
83
  # Méthodes pour les callbacks
70
84
  def trigger_translation_start(from_locale, to_locale, text_length)
71
85
  @on_translation_start&.call(from_locale, to_locale, text_length, Time.now)
@@ -176,6 +190,12 @@ module MistralTranslator
176
190
 
177
191
  private
178
192
 
193
+ def positive_seconds!(name, seconds)
194
+ return seconds if seconds.is_a?(Numeric) && seconds.real? && seconds.positive?
195
+
196
+ raise ConfigurationError, "#{name} must be a positive number of seconds, got: #{seconds.inspect}"
197
+ end
198
+
179
199
  def validate_api_url(url)
180
200
  uri = parse_uri(url)
181
201
  validate_uri_scheme(uri, url)