Lancer des traductions

Traduire et surveillerCopier le lien vers cette section

translateCopier le lien vers cette section

Le flux en une passe : lire la source, comparer chaque locale cible à la ligne de base du verrou, envoyer les clés manquantes et modifiées au fournisseur, exécuter les contrôles d'intégrité, écrire les fichiers de locale et mettre à jour le verrou. Utilise-le pour les scripts, les étapes de build et les jobs CI.

function translate(
  input: TranslateInput,
  deps?: TranslateDeps,
): Promise<RunSummary>;

Renvoie : RunSummary

Lève : UNKNOWN_LOCALE, LOCALE_UNSUPPORTED_BY_PROVIDER, UNKNOWN_FORMAT, CONCURRENCY_INVALID, CONCURRENCY_BUDGET_CONFLICT, MAX_TOKENS_INVALID, LOCK_TIMEOUT_INVALID, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, PROVIDER_CONSTRUCTION_FAILED, NETWORK_POLICY_VIOLATION, CONFIG_INVALID, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID

Exemple : Traduis et lis le résumé

Ce que le tableau ne couvre pas :

• cache est le cache de mémoire de traduction local (verbatra.cache.json, exporté aussi comme CACHE_FILE_NAME).
• humanEdits (à partir de 0.12.0) : par défaut, les clés obsolètes dont la valeur a été écrite, importée ou modifiée hors de verbatra par une personne sont gardées et listées dans LocaleSummary.protected. Voir Protéger les traductions humaines.
• onProgress reçoit les événements de progression décrits plus bas.
• maxBatchSize et budgetBehavior sont réservés à la config ; il n'y a pas de surcharge par exécution.

Les problèmes globaux lèvent une SdkError ; l'échec d'une seule locale ne lève jamais rien et se retrouve en status: "failed" sur l'entrée de cette locale pendant que l'exécution continue. Voir l'anatomie du RunSummary.

Événements de progression Disponible à partir de 0.12.0Copier le lien vers cette section

onProgress reçoit un ProgressEvent, une union discriminée par type. Une version mineure peut ajouter des types, donc ignore un type que tu ne reconnais pas.

provider-retry ne nomme aucune locale, car un seul fournisseur sert toute l'exécution. Gemini indique le délai et le statut, Anthropic, OpenAI, OpenCode et openai-compatible indiquent la tentative quand leur client la lance, et DeepL, Google Cloud Translation et LibreTranslate n'indiquent rien. Un dry run et une estimation n'émettent que locale-started, locale-finished et run-finished. Les enregistrements de progression --json de la CLI s'en tiennent aux quatre types d'origine : locale-started, sub-batch, locale-finished et run-finished.

extract, diff avec unused et doctor avec literals acceptent leur propre onProgress. Il reçoit un ScanProgressEvent, { type: "files-scanned", scanned, total }, une fois après chaque fichier source de l'application que l'analyse lit.

Un CreateProvider personnalisé reçoit un troisième argument, CreateProviderHooks, dès qu'une exécution signale sa progression. Appelle son onRetry avec { attempt, delayMs?, status? } et les nouvelles tentatives de ton fournisseur apparaissent comme événements provider-retry.

resolveDryRun Disponible à partir de 0.11.0Copier le lien vers cette section

Indique si un ensemble d'options d'exécution se résout en un dry run. La fonction prend le dryRun et l'estimate que tu t'apprêtes à passer à translate et dit si cette exécution construira un fournisseur, écrira un fichier ou dépensera quoi que ce soit. C'est le seul endroit où la règle voulant qu'estimate implique dryRun est décidée : utilise-la dès que quelque chose autour d'une exécution doit le savoir à l'avance, plutôt que de redire l'implication et de t'en écarter.

function resolveDryRun(input: {
  readonly dryRun?: boolean | undefined;
  readonly estimate?: boolean | undefined;
}): boolean;

Renvoie : boolean

import { resolveDryRun, translate, type VerbatraConfig } from "@verbatra/sdk";

declare const config: VerbatraConfig;

const options = { dryRun: false, estimate: true };
resolveDryRun(options); // true

const summary = await translate({ config, ...options });

watchCopier le lien vers cette section

Surveille le fichier de la locale source et relance translate à chaque changement temporisé. Il déclenche une exécution initiale immédiatement au démarrage, puis une exécution par changement stabilisé. Les exécutions sont sérialisées : les changements survenus pendant une exécution se regroupent en une seule exécution de suivi.

function watch(
  input: WatchInput,
  deps?: WatchDeps,
): Promise<WatchController>;

Renvoie : WatchController

Lève : UNKNOWN_LOCALE, LOCALE_UNSUPPORTED_BY_PROVIDER, CONCURRENCY_INVALID, LOCK_TIMEOUT_INVALID, CONCURRENCY_BUDGET_CONFLICT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, NETWORK_POLICY_VIOLATION, PROVIDER_CONSTRUCTION_FAILED, CONFIG_INVALID

Exemple : Surveiller dans un processus de longue durée

debounceMs vaut 300 par défaut. onRun est appelé une fois par exécution avec un WatchRunResult : { status: "succeeded", summary } ou { status: "failed", error: { code, message, causeCode?, hint? } }, où causeCode nomme l'erreur codée que l'échec enveloppe et hint est l'étape suivante que donne errorHint. onReady est appelé une fois, quand les vérifications de démarrage passent et juste avant l'exécution initiale, pour que tu puisses annoncer la session avant la sortie de cette exécution. Si onReady lève une erreur, la surveillance est fermée et watch rejette avec cette erreur avant le début de toute exécution. Le SDK n'écrit aucun log ; onRun est la seule sortie. concurrency, cache, onProgress, onLockWait et lockAcquireTimeoutMs sont transmis à chaque exécution et se comportent exactement comme sur translate. locales restreint chaque exécution de la session à ce sous-ensemble et est validé une seule fois au démarrage, pas à chaque cycle.

Renvoie un WatchController avec une seule méthode, stop(), qui ferme la surveillance et attend l'exécution en cours. Chaque code de la ligne Lève est refusé au démarrage, avant que la surveillance n'existe, donc watch lui-même rejette au lieu de renvoyer un contrôleur. Deux d'entre eux pèsent plus sur une session que sur une seule exécution : un concurrency supérieur à 1 face à une config qui fixe maxTokens lève toujours CONCURRENCY_BUDGET_CONFLICT, car il n'existe pas de watch en dry run, et, depuis 0.12.0, un fournisseur impossible à construire, par exemple parce que sa variable de clé d'API manque, lève PROVIDER_CONSTRUCTION_FAILED une seule fois au lieu de faire échouer chaque exécution. Tout échec après le démarrage remonte via onRun et la surveillance continue.

releaseHeldLocks Disponible à partir de 0.12.0Copier le lien vers cette section

Supprime tous les verrous d'écriture que détient le processus courant, pour un processus sur le point de se terminer sans laisser finir ses exécutions en cours : la CLI l'appelle quand une interruption arrête translate ou import, et quand une seconde interruption force l'arrêt de watch. Les exécutions qui ont pris ces verrous perdent leur protection, appelle-le donc seulement juste avant la fin du processus. Il ne prend aucun argument et ne rejette, avec une AggregateError qui nomme les chemins des verrous, que si un verrou détenu n'a pas pu être supprimé, après avoir tenté chaque verrou. Un verrou qu'une opération encore en cours prend, ou tente de prendre, pendant son exécution est refusé avec RUN_CANCELLED et ne laisse aucun fichier ; il attend au plus trois secondes une telle acquisition.

function releaseHeldLocks(): Promise<void>;

Renvoie : void

Un verrou resté en place malgré tout, parce qu'un processus a été tué net, n'en a pas besoin : une exécution en attente sur la même machine voit que le processus enregistré n'existe plus et reprend le verrou elle-même. Voir le verrou d'écriture.

Pseudo-localisationCopier le lien vers cette section

pseudolocalize Disponible à partir de 0.11.0Copier le lien vers cette section

Construit une locale factice à partir des seules chaînes source, si bien que les troncatures de mise en page et les chaînes qui n'ont jamais été extraites pour la traduction apparaissent avant même qu'une clé d'API existe. Chaque valeur est accentuée, allongée d'environ un tiers de sa longueur traduisible et entourée des marqueurs de délimitation [ et ], tandis que les placeholders restent intacts dans toutes les syntaxes que reconnaissent les adaptateurs, y compris les branches plural et select d'ICU, les balises de balisage et les séquences d'échappement. Il ne construit aucun fournisseur, ne lit aucune clé d'API et ne fait aucune requête réseau.

function pseudolocalize(
  input: PseudolocalizeInput,
  deps?: PseudolocalizeDeps,
): Promise<PseudolocalizeResult>;

Renvoie : PseudolocalizeResult

Lève : PSEUDO_OUTPUT_CONFLICT, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, TARGET_UNWRITABLE

Exemple : Construire une pseudo-locale

Chaque valeur générée est tenue à la même barrière d'intégrité qu'une traduction de fournisseur doit franchir. Une valeur qui ne la franchirait pas est copiée telle quelle depuis la source et nommée dans copied plutôt qu'écrite sous une forme cassée, l'entrée reste donc présente et continue de s'afficher.

mode choisit la transformation dans PSEUDO_MODES : accented, celle par défaut, ou bidi, qui entoure plutôt chaque mot de texte traduisible d'une marque et d'un forçage de droite à gauche et laisse dehors les placeholders, la syntaxe ICU, le balisage, les chiffres et la ponctuation, sans rien accentuer. En mode bidi, locale vaut ar-XB par défaut, un code résolu de droite à gauche ; voir verbatra pseudo pour la rencontre entre ses règles de pluriel de l'arabe et les formes de pluriel de ta source.

locale vaut en-XA par défaut et out .verbatra-local/pseudo, que verbatra init ajoute déjà à .gitignore ; le files.pattern configuré y est développé, le fichier garde donc la disposition qu'attend l'application. Une pseudo-locale qui nomme une locale configurée, ou qui se poserait sur un fichier de locale configuré, est refusée avec PSEUDO_OUTPUT_CONFLICT avant que quoi que ce soit ne soit lu ou écrit, elle ne peut donc ni écraser une vraie traduction ni en tenir lieu ; il en va de même d'un out absolu, qui sort de cwd ou qui nomme cwd lui-même, comme ., et, quand deps.fs implémente realpath comme la valeur par défaut, d'un out qui y aboutit, dans le dossier d'un fichier de locale configuré ou sur un autre fichier dont le projet dépend, une fois les liens symboliques résolus. Comme le fichier vit en dehors de files.pattern, translate ne dépense jamais pour lui et check et diff ne le signalent jamais comme désynchronisé.

Renvoie un PseudolocalizeResult : la locale, le mode, le path absolu, combien d'entries ont été traitées, combien ont été transformed, les clés qui ont été copied, et si quelque chose a été written. La transformation est déterministe, une seconde exécution sur une source inchangée ne réécrit donc rien et signale written à false. Pour xliff et apple-xcstrings, dont l'écriture se contente de retoucher un document qui existe déjà, la sortie est recopiée depuis la source à chaque écriture, si bien qu'une clé ajoutée à la source après la première exécution parvient quand même à la pseudo-locale, et un XLIFF copié voit son target-language réécrit vers la pseudo-locale.

Catalogues typésCopier le lien vers cette section

generateTypes Disponible à partir de 0.11.0Copier le lien vers cette section

Déclare le catalogue source d'un projet en TypeScript : une union de toutes les clés qu'il contient et, par clé, les arguments que son message interpole. Type une fonction de traduction sur le résultat et une clé mal orthographiée ou un argument d'interpolation manquant devient une erreur de compilation au lieu d'un échec de recherche à l'exécution. Il ne dépense rien : aucun fournisseur n'est construit, aucune variable d'environnement contenant une clé d'API n'est lue et aucune requête réseau n'est faite.

function generateTypes(
  input: GenerateTypesInput,
  deps?: GenerateTypesDeps,
): Promise<GenerateTypesResult>;

Renvoie : GenerateTypesResult

Lève : TYPES_OUTPUT_CONFLICT, TYPES_UNWRITABLE, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

Exemple : Générer un catalogue typé

Un fichier est lu (le catalogue de la locale source) et un fichier est écrit (la déclaration) ; un fichier de locale cible n'est jamais touché. Les clés sont exactement ce que l'adaptateur de format avait déjà produit, dans l'ordre du document, si bien que deux exécutions sur un catalogue inchangé écrivent des octets identiques. Les arguments viennent des jetons de placeholder que l'adaptateur a extraits, sauf dans les formats de messages ICU (next-intl-json et arb), où chaque message est lu avec le même parseur ICU que celui de l'adaptateur. Chaque clé est émise comme un littéral de chaîne entre guillemets : une clé portant un point, un mot réservé, un chiffre en tête, un guillemet, ou même la clé vide, est donc déclarée telle quelle plutôt qu'abandonnée ou redécoupée, et une clé que l'adaptateur a signalée dans excludedLeafPaths n'est pas déclarée du tout.

Ce qu'il refuse d'affirmer compte autant que ce qu'il déclare. Un message sans placeholder reçoit une forme qui fait de tout argument passé une erreur de type ; un message dont les placeholders nomment leurs arguments reçoit une forme d'objet ; un message aux placeholders numérotés ou anonymes reçoit un tuple readonly. Un argument ICU que seules certaines branches select ou plural utilisent est déclaré comme membre optionnel. Les types d'arguments viennent uniquement de ce que le catalogue enregistre : number pour un argument ICU number, plural ou selectordinal et pour un formateur ou une conversion numériques, Date | number pour un argument ICU date ou time et un formateur i18next datetime, string pour un argument ICU select et une conversion printf de chaîne, et un alias de string | number partout ailleurs, jamais un any permissif. Une interpolation i18next non échappée ({{- name}}) est déclarée sous le nom qui suit son préfixe. Un message que l'adaptateur a signalé comme invalide, un message qui semble à la fois nommer et numéroter ses arguments, et un message dont l'index d'un placeholder est hors limites sont déclarés avec leurs arguments signalés dans unresolved plutôt que déclarés en silence comme n'en prenant aucun. Les clés plurielles sœurs ne sont jamais fusionnées : chacune est déclarée à part, et celles que l'adaptateur a marquées au pluriel sont listées.

out vaut par défaut DEFAULT_TYPES_PATH (verbatra-types.d.ts). Avant toute lecture ou écriture, TYPES_OUTPUT_CONFLICT refuse un out qui ne nomme aucun fichier (y compris un out terminé par un séparateur de chemin), est absolu, sort de cwd avec .., nomme cwd lui-même (.) ou ne se termine pas par .ts, .mts ou .cts, ainsi qu'un out qui nomme un fichier de locale configuré, le fichier de verrouillage, le cache de mémoire de traduction, un fichier où verbatra cherche sa configuration, configPath, le fichier de configuration d'où config a été chargée, ou glossaryPath, le fichier de glossaire qu'elle désigne ; les noms sont comparés sans tenir compte de la casse, et quand deps.fs implémente realpath, comme le fait la valeur par défaut, les mêmes vérifications sont refaites sur l'endroit où le chemin aboutit une fois les liens symboliques résolus. Une exécution qui génère refuse aussi, avec le même code, de remplacer un fichier existant qui ne commence pas par la ligne d'en-tête qu'écrit verbatra, et laisse ce fichier intact. La liste complète se trouve sur la page de verbatra types. Avec check, rien n'est écrit du tout, rien n'est refusé à cause de son contenu, et l'exécution signale seulement si le fichier commité correspond toujours, ce qui est exactement la forme qu'attend un garde-fou de CI.

Renvoie un GenerateTypesResult : le path absolu, le sourcePath dont il a été construit, combien de keys ont été déclarées et combien d'entre elles prennent au moins un argument que verbatra a pu déterminer (withArguments, qui ne compte jamais une clé de unresolved), les clés unresolved ainsi que les excluded et plural, si quelque chose a été written, si le fichier sur disque était stale au démarrage de l'exécution, s'il manquait tout à fait (missing, un fichier manquant est aussi stale), et s'il s'agissait d'une exécution check.