Inspecter un projet

Inspecter l'état sans écrireCopier le lien vers cette section

Aucune de ces fonctions ne traduit ni ne modifie le verrou. Seule extract écrit un fichier (le catalogue source), et seule doctor avec live fait une requête réseau (la liste des langues du fournisseur).

doctor Disponible à partir de 0.9.0Copier le lien vers cette section

Valide la mise en place du projet et ne dépense rien : il ne construit aucun fournisseur et ne fait aucune requête réseau sauf si live en demande une, et ne lit la valeur de la clé d'API que pour cette seule requête de liste des langues (LibreTranslate ne reçoit aucune clé). Toutes les vérifications s'exécutent même si une précédente a échoué, donc un seul appel signale tous les problèmes indépendants ; verbatra doctor liste les vérifications.

function doctor(
  input?: DoctorInput,
  deps?: DoctorDeps,
): Promise<DoctorResult>;

Renvoie : DoctorResult

Lève : CONFIG_NOT_FOUND

La vérification network-policy échoue quand la politique réseau effective refuse l'hôte ou le proxy du fournisseur, ou qu'une variable réseau est invalide, et réussit pour le fournisseur none. Les vérifications informatives n'échouent jamais et ne renomment rien ; un warn laisse ok à true, et le tableau des vérifications dit ce que chacune nomme et quand elle vaut skipped.

La vérification locales juge chaque locale configurée comme translate avant de dépenser : elle échoue sur une locale non prise en charge, vaut skipped pour none et renvoie les verdicts dans DoctorResult.locales sous forme de LocaleCapabilityReport. Avec live: true, elle récupère d'abord la liste de langues actuelle du fournisseur, sans consommer de quota ; LocaleCapabilityReport.live indique comment cela s'est passé. Voir Prise en charge des langues.

Avec literals activé, seules les vérifications config et untranslated-literals s'exécutent, comme avec verbatra doctor --literals. doctor charge la config lui-même, donc un projet sans config obtient un rapport, pas une erreur levée : ok est vrai exactement quand aucune vérification n'a échoué, et CONFIG_NOT_FOUND n'est levé que pour un configPath explicite qui n'existe pas.

Seule une vérification en échec porte fix, une prochaine étape à l'impératif ; comme detail, il nomme des variables et des chemins, jamais la valeur d'une clé.

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

Décrit où vont les données d'un projet, pour la config chargée, sous forme d'un DataFlowManifest versionné. verbatra doctor --data-flow l'affiche et en liste les champs ; doctor({ dataFlow: true }) le renvoie comme DoctorResult.dataFlow. Il ne lit aucune clé d'API et ne fait aucune requête réseau. Une variable réseau invalide ou un fichier source illisible est signalé dans le manifeste au lieu d'être levé.

function dataFlow(
  input?: DataFlowInput,
  deps?: DataFlowDeps,
): Promise<DataFlowManifest>;

Renvoie : DataFlowManifest

Lève : CONFIG_NOT_FOUND, CONFIG_INVALID

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

Le schéma zod d'un DataFlowManifest, pour qu'une étape de CI ou l'outil d'un relecteur puisse en valider un. Les champs inconnus sont conservés, car un verbatra plus récent peut ajouter des champs dans la version 1 ; ignore ceux que tu ne connais pas. DATA_FLOW_MANIFEST_VERSION est la version qu'écrit ce build.

const dataFlowManifestSchema: z.ZodType<DataFlowManifest>;

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

Analyse le code de ton application à la recherche des sites d'appel de traduction et fusionne ce qu'il trouve dans le catalogue de la locale source, même s'il n'existe pas encore. Il ne construit aucun fournisseur, ne lit aucune clé d'API et ne fait aucune requête réseau.

function extract(
  input: ExtractInput,
  deps?: ExtractDeps,
): Promise<ExtractResult>;

Renvoie : ExtractResult

Lève : EXTRACT_NOT_CONFIGURED, EXTRACT_FS_UNSUPPORTED, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_INVALID, SOURCE_UNWRITABLE

Exemple : Extraire les clés de ton code source

Seules les clés réellement nouvelles sont ajoutées (Ce qu'elle écrit). Ce que l'analyse ne peut pas résoudre revient sous forme de données dans dynamic, conflicts et diagnostics, jamais levé (Ce qu'elle signale), et le résultat ne porte jamais le contenu d'un fichier source.

config.extract nomme le framework et les racines de sources. La découverte exige le membre optionnel readDirectory de SdkFs ; sans lui, EXTRACT_FS_UNSUPPORTED.

check Disponible à partir de 0.4.0Copier le lien vers cette section

Rapporte la dérive par locale sous forme de comptes : missing (dans la source, absent de la cible), stale (source modifiée depuis la dernière traduction) et upToDate. Utilise-le comme garde-fou de CI.

function check(
  input: CheckInput,
  deps?: CheckDeps,
): Promise<CheckSummary>;

Renvoie : CheckSummary

Lève : UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, UNKNOWN_LOCALE

Exemple : Vérifier en CI sans écrire

inSync est vrai exactement quand chaque locale vérifiée n'a rien de manquant ni d'obsolète.

Avec consistency: true, chaque LocaleCheckSummary porte aussi inconsistencies : un InconsistencyGroup par chaîne source que la locale traduit de plusieurs façons sous des clés différentes, sous la forme que montre le rapport de cohérence. Ce n'est qu'un rapport : il ne change jamais inSync, un compte ou un fichier.

Chaque LocaleCheckSummary porte aussi provenance : des comptes byOrigin et byReviewState sur les clés pour lesquelles la locale a une valeur, lus dans verbatra.provenance.json (origines). Ce champ, comme tout autre champ de provenance d'un rapport, est omis plutôt que de provoquer une erreur quand le fichier est corrompu ou vient d'un verbatra plus récent.

Chaque LocaleCheckSummary porte aussi protected, la part de stale qu'une exécution de translate laisserait à une personne selon humanEdits et pinnedKeys (Clés protégées). Elles comptent toujours comme obsolètes, donc inSync reste à false jusqu'à ce qu'une personne les résolve ; une clé épinglée manquante compte seulement comme manquante.

Avec qa: true, check lance aussi le contrôle qualité sur chaque valeur commitée, sans clé et sans rien écrire : chaque LocaleCheckSummary porte un rapport qa et le résumé les totaux qa, sous les formes de cette section. Les motifs d'erreur viennent de INTEGRITY_GATE_REASONS, ceux d'avertissement de REVIEW_REASON_CODES, les gravités de QA_SEVERITIES ; qaSeverity: "error" ignore les avertissements. inSync ne change jamais : un contrôle CI lit qa.errors, et en mode strict aussi qa.warnings.

Chaque LocaleCheckSummary porte aussi incompletePlurals, trié par clé : un IncompletePlural { code: "PLURAL_CATEGORIES_INCOMPLETE", key, argument?, ruleType, missing } par pluriel auquel manquent des catégories CLDR que la langue cible utilise. Ce n'est qu'un avertissement ; les formats et les règles sont dans catégories de pluriel.

Avec requireReviewed: true, check exécute aussi la barrière de relecture, sans clé et sans rien écrire : chaque LocaleCheckSummary porte review: { unreviewed }, les clés de machine non approuvées, et le résumé porte review: { reviewed, unreviewed, code? } avec les codes que nomme cette section. Le rapport ne change jamais inSync ; une barrière de CI lit review.reviewed.

Avec sensitive: true, check lance aussi l'analyse de contenu sensible, sans clé et sans rien écrire : le résumé porte sensitive: { findings, glossaryTerms }, un { key, fields, detectors } par clé signalée, jamais le texte trouvé. Une barrière de CI échoue sur l'un ou l'autre.

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

Vérifie un seul fichier de locale juste après qu'une personne ou un agent l'a modifié. Il ne lit que ce fichier et, pour une locale cible, le fichier source ; il n'appelle aucun fournisseur, ne lit aucune clé d'API et n'écrit rien.

function checkFile(
  input: CheckFileInput,
  deps?: CheckFileDeps,
): Promise<CheckFileSummary>;

Renvoie : CheckFileSummary

Lève : NOT_A_LOCALE_FILE, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

file est absolu ou relatif à cwd ; Un seul fichier montre la forme du CheckFileSummary. Un fichier cible est vérifié comme check avec qa: true, le fichier source seulement pour sa syntaxe. Un fichier qui ne s'analyse pas n'est pas levé : sa locale porte un QaSyntaxFinding, avec pour JSON et YAML la position que signale AdapterError.position. Un chemin qui n'est le fichier d'aucune locale configurée, ou un fichier absent, lève NOT_A_LOCALE_FILE.

diff Disponible à partir de 0.4.0Copier le lien vers cette section

Le pendant détaillé de check : le même calcul, mais il renvoie les listes de clés par locale (missing, changed, orphaned) au lieu de comptes. Les clés orphelines ne font l'objet que d'un rapport et ne font jamais basculer hasPendingChanges, puisqu'une exécution par défaut ne les supprime pas.

function diff(
  input: DiffInput,
  deps?: DiffDeps,
): Promise<DiffSummary>;

Renvoie : DiffSummary

Lève : UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, UNKNOWN_LOCALE

Exemple : Vérifier en CI sans écrire

Avec unused: true, il analyse aussi les racines extract de la config, en lecture seule et sans clé, et ajoute un rapport unused des clés source qu'aucune référence statique ne nomme, séparé de chaque liste orphaned et sans jamais faire basculer hasPendingChanges ; Clés source inutilisées en explique les champs.

Chaque LocaleDiff porte aussi changedOrigins, l'origine de la valeur actuelle de chaque clé changed (comme machine, human ou external) : le travail qu'une retraduction remplacerait.

Chaque LocaleDiff porte aussi protected, les clés manquantes et modifiées qu'une exécution de translate laisserait tranquilles, triées ; elles comptent toujours comme en attente.

keyIntegrity Disponible à partir de 0.5.0Copier le lien vers cette section

Rapporte, pour les clés modifiées de chaque locale, si la valeur cible actuelle correspond toujours aux placeholders et au balisage en ligne de la source et est de l'ICU valide : chaque entrée porte key, hasPlaceholders, matches, les jetons missing et extra en cas de discordance, icuValid, markupMatches et markupDetails, jamais de valeur de chaîne. Les valeurs écrites avant la barrière appliquée à l'écriture ou modifiées hors de verbatra sont jugées de même. Studio affiche ce rapport par clé.

function keyIntegrity(
  input: KeyIntegrityInput,
  deps?: KeyIntegrityDeps,
): Promise<readonly LocaleKeyIntegrity[]>;

Renvoie : readonly LocaleKeyIntegrity[]

Lève : UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, UNKNOWN_LOCALE, UNKNOWN_KEY

Chaque entrée porte aussi icuArmsMatch et icuArmDetails : si les branches ICU plural, selectordinal et select de la valeur conviennent à la langue cible, jugées comme la barrière appliquée à l'écriture les juge, avec un problème court par branche fautive. icuArmsMatch vaut toujours true pour un format qui ne vérifie pas les branches.

keys restreint la vérification ; seules les clés "modifiées" pour une locale sont vérifiées.

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

Trouve chaque traduction des locales cibles cassée à cet instant : un placeholder ou du balisage en ligne perdu ou ajouté, de l'ICU invalide, ou des branches ICU qui ne conviennent pas à la langue cible. Contrairement à keyIntegrity, il juge chaque clé présente à la fois dans la source et dans une locale cible, quel que soit son état de synchronisation, selon les mêmes règles, et ne renvoie que les clés en échec : une liste entries vide signifie que la locale passe.

function localeIntegrity(
  input: LocaleIntegrityInput,
  deps?: LocaleIntegrityDeps,
): Promise<readonly LocaleKeyIntegrity[]>;

Renvoie : readonly LocaleKeyIntegrity[]

Lève : UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_LOCALE

Chaque appel relit et analyse le fichier source et chaque fichier cible demandé, sans cache.

lockState Disponible à partir de 0.5.0Copier le lien vers cette section

Rapporte l'existence du fichier de verrouillage, sa version et la dérive par locale (nombre de clés de la ligne de base, plus les comptes de clés manquantes, obsolètes et à jour). exists vient d'une sonde explicite, donc un fichier de verrouillage absent et un fichier vide restent distinguables ; s'il est absent, le résultat est { exists: false } et rien d'autre n'est lu.

function lockState(
  input: LockStateInput,
  deps?: LockStateDeps,
): Promise<LockStateResult>;

Renvoie : LockStateResult

Lève : UNKNOWN_LOCALE, LOCK_FILE_INVALID, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

Chaque locale porte aussi les mêmes comptes provenance que check rapporte.

loadLockFile Disponible à partir de 0.5.0Copier le lien vers cette section

Lit le fichier de verrouillage lui-même (verbatra.lock.json, aussi exporté sous LOCK_FILE_NAME) et renvoie sa forme analysée : { version, locales }, où chaque locale associe les clés au hash du contenu source depuis lequel elles ont été traduites pour la dernière fois. Un fichier manquant se dégrade en verrou vide, le même comportement de première exécution sur lequel translate s'appuie ; utilise lockState quand tu dois distinguer l'absence.

function loadLockFile(
  input?: LoadLockFileInput,
  deps?: LoadLockFileDeps,
): Promise<LockFile>;

Renvoie : LockFile

Lève : LOCK_FILE_INVALID

Aucune config requise.

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

Lit le fichier de provenance lui-même (verbatra.provenance.json, aussi exporté sous PROVENANCE_FILE_NAME) et renvoie sa forme stockée : { version, locales }, où chaque locale associe chaque clé à un enregistrement { origin, provider?, model?, valueHash, reviewState?, reviewer?, reviewedSourceHash? }, sans texte traduit. Un fichier absent, ou venant d'un verbatra plus récent, se lit comme vide ; un fichier corrompu lève PROVENANCE_FILE_INVALID. keyValue, localeValues, check, diff et lockState rapportent la vue interprétée (KeyProvenance), qui distingue aussi unrecorded de external.

function loadProvenance(
  input?: LoadProvenanceInput,
  deps?: LoadProvenanceDeps,
): Promise<ProvenanceFile>;

Renvoie : ProvenanceFile

Lève : PROVENANCE_FILE_INVALID

Aucune config nécessaire.

runStatus Disponible à partir de 0.5.0Copier le lien vers cette section

Lit l'instantané des signalements de relecture et de la consommation de tokens que la dernière exécution translate ou watch hors dry run a persisté dans .verbatra-local/run-status.json. Ne lève jamais : un fichier inutilisable se dégrade en available: false. Ce fichier est de la télémétrie sans garantie, pas une référence d'exactitude.

function runStatus(
  input?: RunStatusInput,
  deps?: RunStatusDeps,
): Promise<RunStatusResult>;

Renvoie : RunStatusResult

Aucune config requise. Renvoie { available: false, reason } (voir RUN_STATUS_UNAVAILABLE_REASONS) ou { available: true, version, generatedAt, usage?, budget?, locales }.

Un instantané antérieur à l'application du budget de tokens est toujours lu, sans un budget avec supported: false (son tokensUsed: 0 n'était pas un décompte). Les nouveaux instantanés ajoutent seulement un champ marqueur, donc un lecteur plus ancien peut afficher un budget estimé comme non suivi. Un motif de relecture inconnu est ignoré, et une entrée qui n'en a plus aucun est retirée.

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

Lit la file de relecture dans les fichiers commités : chaque clé dont la valeur actuelle a une origine de machine (machine, memory, fuzzy ou agent, le tuple MACHINE_CLASS_ORIGINS) et n'est pas approuvée, par locale cible et dans l'ordre de la source. Elle lit les fichiers de locale, verbatra.lock.json et verbatra.provenance.json, donc tout le monde sur le même commit voit la même file. Une clé en sort dès que sa valeur est approuvée ou rejetée, ou qu'une personne écrit ou importe une nouvelle valeur ; une valeur réécrite par un agent reste, tout comme une approbation antérieure à une modification de la source. Le dernier instantané de runStatus n'ajoute que des détails : les reasons de chaque entrée (vides si l'exécution ne l'a pas signalée avec un motif connu), les fuzzyHits de la locale et lastRunAt.

function reviewQueue(
  input: ReviewQueueInput,
  deps?: ReviewQueueDeps,
): Promise<ReviewQueueResult>;

Renvoie : ReviewQueueResult

Lève : UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID

Exemple : Traiter la file de relecture

Renvoie { available: true, locales, lastRunAt? }, chaque locale sous la forme { locale, needsReview, approved?, fuzzyHits? } et chaque entrée sous la forme { key, reasons, provenance } ; approved liste les valeurs de machine approuvées et n'est présent qu'avec includeApproved: true. Quand le fichier de provenance est corrompu ou vient d'une version plus récente de verbatra, elle renvoie { available: false, reason: "provenance-unreadable" }. Un fichier source, cible ou de verrouillage illisible fait échouer l'appel comme pour check. Jusqu'à la 0.11, la file ne contenait que les signalements de la dernière exécution.

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

Construit le rapport par locale qu'affiche verbatra report provenance : chaque clé qui a une valeur à la fois dans la source et dans une locale cible, dans l'ordre de la source, avec son origine, son état de relecture, son fournisseur, son modèle et son relecteur, comptée dans une catégorie de PROVENANCE_BUCKETS (le rapport de provenance les définit). Il n'appelle aucun fournisseur et n'écrit rien.

function provenanceReport(
  input: ProvenanceReportInput,
  deps?: ProvenanceReportDeps,
): Promise<ProvenanceReportResult>;

Renvoie : ProvenanceReportResult

Lève : UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID

deps accepte aussi now, l'horloge de generatedAt. La forme complète du résultat figure dans le schéma JSON. Quand le fichier de provenance est corrompu ou vient d'un verbatra plus récent, il renvoie { available: false, reason: "provenance-unreadable" }, puisque chaque valeur se lirait comme unrecorded. Un fichier source, cible ou de verrouillage illisible fait échouer l'appel comme pour check. Le rapport est un élément de preuve à l'appui, pas un conseil juridique.

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

Construit le même rapport que provenanceReport et renvoie ses entrées page par page, si tu veux seulement celles de certains buckets, avec un curseur pour la page suivante. Chaque page garde complets les total et counts de chaque locale. report.provenance du serveur MCP pagine avec. En lecture seule.

function provenanceReportPage(
  input: ProvenanceReportPageInput,
  deps?: ProvenanceReportDeps,
): Promise<ProvenanceReportPageResult>;

Renvoie : ProvenanceReportPageResult

Lève : UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, PAGE_CURSOR_INVALID, PAGE_LIMIT_INVALID

Une locale ne porte entries que sur les pages qui contiennent une de ses entrées. Une page contient au plus limit entrées, PAGE_LIMIT_DEFAULT par défaut ; repasse nextCursor comme cursor, avec les mêmes locales et buckets, jusqu'à ce qu'il soit absent. Il est indisponible, ou échoue, exactement quand provenanceReport l'est.