Docs / Concepts
Page traduite automatiquement
Comment se déroule une exécution
Le pipeline de traduction de bout en bout, de la lecture de la locale source et des clés modifiées à l'écriture des traductions et du fichier de verrouillage.
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 a besoin de travail, vérifier ce qui revient,
écrire, et enregistrer le résultat. Le pipeline est le même, que l'exécution vienne de la CLI, du
SDK ou de watch.
Lire la locale source
L'adaptateur de format lit le fichier source dans un ensemble neutre d'entrées à clés, si bien que
chaque étape suivante fonctionne de la même façon pour tous les formats. Une clé source dont la
valeur est invalide pour la syntaxe de message du format (ICU invalide) est mise de côté et
signalée au lieu d'être envoyée cassée au fournisseur. Un fichier source absent ou impossible à
analyser fait échouer l'exécution ; voir
SOURCE_ et
SOURCE_.
Comparer avec la référence du fichier de verrouillage
La comparaison est ce qui rend une exécution incrémentale. verbatra lit le fichier cible existant
(un fichier absent compte comme vide, même si les écrivains de xliff et apple-xcstrings refusent une cible absente) et compare chaque clé source avec
le fichier de verrouillage, la trace de ce qui a été traduit auparavant :
| Catégorie | Signification | Ce que fait l'exécution |
|---|---|---|
| manquante | la cible n'a pas encore la clé | la traduit |
| modifiée | la source ne correspond plus au hash enregistré | la traduit |
| inchangée | la source correspond toujours au hash enregistré | n'y touche pas |
| orpheline | la clé est dans la cible mais plus dans la source | la signale ; ne la supprime qu'avec --prune ou prune: true |
Clés retenues
Deux sortes de candidates sont retenues. Une clé modifiée dont une personne a écrit ou importé la
valeur actuelle est protégée par défaut (humanEdits), et une clé qui correspond à pinnedKeys
n'est jamais traduite automatiquement. Les deux restent obsolètes jusqu'à ce qu'une personne les
règle ; voir Garder les traductions humaines.
Envoyer par lots au fournisseur
Chaque candidate est d'abord cherchée dans le cache de traduction. Un succès est réutilisé et n'atteint jamais le fournisseur. Parmi les échecs, les clés au contenu source identique sont regroupées, pour que ce texte coûte une requête par locale plutôt qu'une par clé.
Les groupes partent vers ton fournisseur en sous-lots séquentiels d'au plus maxBatchSize (50 par
défaut), chacun avec les entrées, les termes du glossaire de cette locale et ton tone. Si 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 pendant que les autres sous-lots continuent.
Fournisseurs décrit comment chaque fournisseur applique ces entrées.
Valider la réponse
La sortie du fournisseur est une donnée, jamais du texte libre. Pour les fournisseurs LLM, la réponse doit correspondre à un schéma fixe :
- Une réponse malformée, ou qui contient une clé jamais demandée, fait échouer tout le sous-lot.
- Une clé demandée qui revient manquante ou en double est redemandée une fois.
- Une clé toujours non résolue après cela n'est pas traduite pendant cette exécution.
Les fournisseurs de traduction automatique n'ont pas de schéma de réponse, mais leurs résultats passent par la même barrière d'intégrité.
Exécuter la barrière d'intégrité
Une traduction valide selon le schéma peut quand même être cassée, donc verbatra décide à partir de la valeur candidate elle-même s'il l'accepte, sans jamais se fier au rapport du fournisseur. Une candidate qui perd un placeholder, casse un message ICU ou son balisage, revient vide ou dégénère est retenue au lieu d'être écrite. Les vérifications sont sur Sûreté de la traduction.
É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 et dans un ordre de clés stable : une clé déjà présente dans la cible garde sa position, et les nouvelles clés sont ajoutées après les clés existantes, dans l'ordre de la source. Une écriture interrompue ne laisse jamais de fichier à moitié écrit, et les relecteurs voient des diffs petits et stables.
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. Une clé retenue pendant cette exécution garde son hash précédent, donc l'exécution suivante la voit toujours comme à traiter. Chaque locale est écrite sous un verrou d'écriture inter-processus, donc deux exécutions qui se chevauchent ne comparent jamais avec une référence périmée et ne paient jamais deux fois le même appel.
Une locale à la fois, les échecs comme des données
Chaque locale cible tourne de son côté, et l'échec d'une locale n'arrête pas les autres. L'exécution renvoie un résumé par locale : traduites, inchangées, orphelines, retenues, signalées pour relecture, et avis. Ce que contient chaque champ est sur RunSummary.
Ce que cette conception garantit :
- Une seconde exécution sans modification de la source n'appelle le fournisseur pour rien.
- Rien de ce qu'une vérification a refusé n'est jamais écrit, et rien de retenu n'est enregistré comme fait.
- Une exécution à blanc (
--dry-run) s'arrête après la comparaison et renvoie un résumé de même forme, sans construire de fournisseur ni écrire de fichier.
Ce qu'elle ne fait pas : juger si une traduction est bonne. C'est le rôle des signalements de relecture et d'une personne.
Voir aussi
verbatra translate: options, sortie et codes de sortie d'une exécution.- Le fichier de verrouillage et la provenance : ce que la référence enregistre.
- Le cache de traduction : comment la réutilisation est indexée.
- Sûreté de la traduction : la barrière d'intégrité et les signalements de relecture.
- Codes d'erreur : chaque code qu'une exécution peut signaler.