Versions et releases

Entre une clé dans votre code et la valeur que votre app récupère à l'exécution, il y a un statut, une release et un bundle. Cette page décrit les trois, et surtout ce qui part et ce qui ne part pas.

Les statuts qu'une valeur traverse

La publication commence à translated : tout ce qui est en dessous ne quitte jamais le projet.

Statut	Ce que ça veut dire
`missing`	Aucune valeur pour cette langue. L'état par défaut d'une cible non traduite.
`draft`	Une valeur existe mais n'est pas validée. Les écritures agent et IA atterrissent ici, sous le seuil de publication.
`translated`	Une valeur complète. C'est le seuil : les bundles publient à partir d'ici.
`reviewed`	La valeur a été relue.
`approved`	La valeur est validée. Une valeur tapée par un humain atterrit directement ici (auteur = approbateur).
`rejected`	La valeur a été rejetée. Jamais publiée, état terminal hors-bande.

Un draft pur ne peut pas être approuvé en une étape : approve_translation renvoie not_approvable, il doit d'abord atteindre translated. Le périmètre d'export par défaut (XLIFF, CSV) est de même translated,reviewed,approved et exclut le draft sauf demande explicite.

Ce qui part au CDN

Une release (publish_cdn) construit un bundle par langue et par namespace. Seuls les statuts publiables y entrent, et seulement les valeurs non vides.

Inclus : translated, reviewed, approved, c'est-à-dire tout à partir du seuil.
Exclus : draft, missing, rejected. Une valeur vide est ignorée aussi, même si son statut qualifierait.

Le garde-fou du bundle vide

C'est le point qui évite l'accident le plus coûteux : vider un namespace en ligne sans s'en apercevoir.

Si aucune clé d'un bundle n'est publiable, publish_cdn saute ce bundle. Rien n'est écrasé, skipped: true, et une entrée arrive dans warnings[] avec {language_code, namespace, key_count, included_count, excluded_count, skipped, reason}.

Le reason est explicite :

namespace '{ns}' / '{lang}': 0 of {N} keys are publishable: all are below 'translated' status (e.g. draft). The bundle is EMPTY: nothing will be served. Publish was SKIPPED for this bundle; set allow_empty=true to force an empty bundle.

Passez allow_empty: true pour publier quand même le bundle vide, ce qui reste toujours signalé. En clair : vous ne pouvez pas vider par accident un namespace en ligne en publiant une pile de clés draft.

Avant de publier : valider

Lancez validate_translations avant de publier, pour attraper les problèmes tant qu'ils sont faciles à corriger. Sans payload, il audite les valeurs stockées ; passez un payload pour inspecter une soumission.

Il renvoie quality_issues[] (et counts.quality_issues), chaque entrée étant {key, type, detail}, où type vaut same_as_source, wrong_language ou looks_like_raw_key. Le detail dit par exemple « value is identical to the source, likely not translated » ou « value '{v}' looks like a key path/identifier, not text ».

C'est indicatif : il signale, il ne réécrit jamais vos valeurs.

Confirmer qu'une langue est en ligne

Une fois publiée, il y a deux questions distinctes, et deux vérifications différentes. Les confondre est la source d'erreur la plus commune.

Est-elle publiée ?

distribution_info, en lecture seule via MCP et sans crédit, renvoie la base CDN et le gabarit d'URL de bundle, la version de production, quelles paires langue/namespace sont publiées, et les manques. C'est exactement ce que les SDK clients peuvent récupérer.

Se résout-elle ?

sonenta pull --language <code> télécharge les traductions résolues de cette langue. C'est la preuve concrète que les valeurs se récupèrent, pas seulement qu'elles existent.

Les SDK abonnés reçoivent aussi un événement translations_published et se rafraîchissent en place.

Deux aides de préflight à connaître : sonenta doctor vérifie que le MCP est câblé, joignable et de scope mcp:*, et sonenta ci évalue l'impact i18n d'une pull request.

Ensuite

CI : attraper les problèmes i18n à chaque pull request
Imbrication des clés : clés à plat ou imbriquées, et le piège de la clé pointée
Référence CLI : sonenta releases