Comment ça marche

Une exécution est un pipeline : lire la locale source, comparer chaque cible avec le fichier de verrouillage, n'envoyer au fournisseur que ce qui demande du travail, vérifier ce qui revient, écrire, et enregistrer le résultat. Cette page parcourt ce pipeline pour que tu saches exactement ce qui se passe quand tu lances verbatra translate.

Une exécution part de ta configuration validée ; voir Fichier de configuration pour savoir où elle est trouvée et ce qu'elle contient. Tout ce qui suit est identique que l'exécution vienne de la CLI, du SDK ou de watch.

Lire la locale source

L'adaptateur de format lit le fichier de la locale source en un ensemble neutre d'entrées à clés, pour que le reste du pipeline fonctionne pareil pour chaque format. Un fichier source absent fait échouer l'exécution avec SOURCE_UNREADABLE ; un fichier que l'adaptateur ne peut pas analyser échoue avec SOURCE_INVALID. Pendant la lecture, l'adaptateur signale aussi les clés source dont les valeurs sont invalides pour la syntaxe de message du format (ICU invalide) : ces clés suivent le mouvement mais sont mises de côté au lieu d'être envoyées au fournisseur dans un état cassé.

Comparer avec la référence du fichier de verrouillage

Cette comparaison existe pour qu'une exécution soit incrémentale : le fournisseur n'est appelé que pour les chaînes qui demandent vraiment du travail. verbatra lit le fichier de la locale cible existant (un fichier absent compte comme vide) et compare la source avec lui, en utilisant le fichier de verrouillage comme référence de ce qui a déjà été traduit. Chaque clé source atterrit dans l'un de quatre paniers :

• manquante : la cible n'a pas encore la clé.
• modifiée : la valeur source ne correspond plus au hash enregistré dans le fichier de verrouillage.
• inchangée : la valeur source correspond toujours au hash enregistré.
• orpheline : la clé est dans la cible mais plus dans la source.

Seules les clés manquantes et modifiées deviennent des candidates à la traduction. Les clés inchangées sont laissées tranquilles. Les clés orphelines sont rapportées et, par défaut, laissées en place ; avec --prune (ou prune: true dans la configuration) exactement ces clés sont supprimées du fichier cible et du fichier de verrouillage, et rien d'autre.

Envoyer par lots au fournisseur

Les candidates partent vers ton fournisseur configuré en sous-lots séquentiels d'au plus maxBatchSize entrées (50 par défaut), pour qu'une requête trop grosse ne puisse pas emporter toute une locale. Chaque sous-lot transporte les entrées plus tes glossary et tone optionnels. Si l'appel d'un sous-lot échoue (une limite de débit, un délai dépassé, une clé révoquée), ses clés sont retenues pour cette exécution et reprises à la suivante, pendant que les autres sous-lots continuent d'avancer. Voir Fournisseurs pour la façon dont chaque fournisseur applique ces entrées.

Valider la réponse

La sortie du fournisseur n'est jamais traitée comme du texte libre. Pour les fournisseurs LLM (Anthropic, OpenAI, Gemini et openai-compatible), la réponse est une donnée liée à un schéma, validée avant toute autre chose : une réponse malformée, ou qui contient une clé jamais demandée, fait échouer le sous-lot, et une clé demandée qui revient manquante ou dupliquée est redemandée une fois ; si elle reste non résolue après ça, la clé est traitée comme non traduite pour cette exécution et retentée à la suivante. DeepL est une API de traduction automatique sans cette couche de réponse, mais ses résultats passent par les mêmes contrôles d'intégrité ci-dessous.

Vérifier l'intégrité des placeholders et l'intégrité ICU

Une traduction qui a passé la validation de schéma peut quand même être cassée, donc verbatra recalcule sa propre décision d'acceptation ou de rejet à partir de la valeur candidate elle-même : il ne fait jamais confiance au rapport du fournisseur. Chaque candidate acceptée doit porter les mêmes placeholders que sa source, et pour les formats ICU elle doit rester un message valide. Une candidate qui échoue à l'un ou l'autre contrôle est retenue au lieu d'être écrite, apparaît sur le résumé d'exécution, et est retentée à l'exécution suivante. Voir Sûreté de la traduction pour le modèle de sûreté complet.

Écrire via l'adaptateur

Les traductions acceptées sont fusionnées dans la cible et écrites par l'adaptateur de format, de façon atomique, dans l'ordre des clés du document : une clé déjà dans la cible garde sa position, et une nouvelle clé s'ajoute là où la source la place. Une écriture interrompue ne laisse jamais un fichier de locale à moitié fini, et un formateur ou un relecteur de code voit des diffs stables et minimaux.

Mettre à jour le fichier de verrouillage

Après l'écriture d'une locale, ses entrées de verrouillage sont rafraîchies avec les hashs source actuels, avec une exception délibérée : une clé retenue pendant cette exécution garde son hash précédent, pour que l'exécution suivante la voie toujours comme demandant du travail. L'écriture de chaque locale se fait sous un verrou d'écriture inter-processus, pour que deux exécutions qui se chevauchent ne comparent jamais avec une référence périmée ni ne paient deux fois le même appel fournisseur. Les détails sont dans Le fichier de verrouillage.

Une locale à la fois, les échecs comme des données

Chaque locale cible s'exécute pour elle-même : une locale qui échoue n'arrête pas les autres. L'exécution renvoie un résumé par locale (traduites, inchangées, orphelines, retenues, signalées pour révision, avis), et un dry run (--dry-run) produit la même forme de résumé après l'étape de comparaison, sans construire de fournisseur ni rien écrire.