verbatra check

Indique, pour chaque locale cible, combien de clés manquent, sont obsolètes ou à jour, et termine avec un code sur lequel une étape de CI peut s'appuyer. check lit et compare comme verbatra translate avant d'appeler le fournisseur, puis s'arrête : aucun appel au fournisseur, aucun fichier écrit, aucune clé d'API requise.

SynopsisCopier le lien vers cette section

verbatra check [flags]

ExemplesCopier le lien vers cette section

# faire échouer le build quand les traductions ont dérivé
verbatra check

# état lisible par une machine pour deux locales
verbatra check --locales de,fr --json

# lister aussi les textes source traduits de plusieurs façons
verbatra check --consistency

# échouer sur des placeholders, du markup ou de l'ICU cassés, et sur les avertissements
verbatra check --qa --strict

# échouer tant que des traductions automatiques attendent une approbation
verbatra check --require-reviewed

# échouer sur des e-mails, clés d'API ou numéros de carte dans la source
verbatra check --sensitive

# vérifier seulement le fichier qu'un éditeur ou un agent vient de modifier
verbatra check --file locales/de.json --json

OptionsCopier le lien vers cette section

Accepte aussi les options globales --cwd, --config et --json.

Une clé manque quand la source l'a et pas la cible, et elle est obsolète quand son texte source a changé depuis sa dernière traduction. Une locale est synchronisée quand elle n'a ni l'un ni l'autre. Pour les listes de clés derrière les chiffres, utilise verbatra diff.

ComportementCopier le lien vers cette section

Rapport de cohérenceCopier le lien vers cette section

--consistency liste, par locale cible, chaque texte source que deux clés ou plus traduisent différemment : la source, chaque traduction et les clés qui la portent. Il ne change jamais le code de sortie, une valeur ni la file de relecture. Les règles de comparaison :

• Les valeurs sont comparées après normalisation Unicode NFC, \r\n ramené à \n et espaces de début et de fin retirés. Les espaces internes et la casse comptent.
• Seules les clés à jour sont comparées, et une traduction identique à sa source relève de EQUALS_SOURCE.
• Des clés dont la description, le sens, le marqueur de pluriel ou le msgctxt gettext diffèrent ne sont jamais regroupées.
• Les formes plurielles sont comparées forme par forme : les formes one et other d'une clé ne sont jamais regroupées entre elles.

Faux positifs connus : les variantes de contexte i18next (invite_male, invite_female), les entrées gettext marquées #, fuzzy, les clés d'allure plurielle dans un format sans pluriels (yaml, ngx-translate-json, xliff, properties, ini, resx) et les formes plurielles d'un format custom:. Donne-leur une description ou un sens différents, ou ignore le résultat. Avec --json, chaque locale porte inconsistencies: { source, context?, description?, meaning?, isPlural, pluralForm?, translations: [{ value, keys }] }[].

Clés protégéesCopier le lien vers cette section

Une clé obsolète qu'une personne a écrite, importée ou modifiée hors de verbatra, ou une clé qui correspond à pinnedKeys, est une clé que translate laisse à une personne (voir Protéger les traductions humaines). check la compte quand même et affiche la part protégée, par exemple 2 stale (1 protected). --json la donne en protected par locale ; quand verbatra.provenance.json est illisible, seules les clés épinglées comptent.

Catégories de plurielCopier le lien vers cette section

Chaque check liste les pluriels auxquels il manque une catégorie de pluriel CLDR utilisée par leur langue cible, comme un <plurals> Android polonais avec seulement one et other :

plural categories (warning: exit 1 only under --qa --strict)
  pl: 2 plurals missing CLDR categories
    cart {count} plural: missing few, many
    files: missing few, many

Les catégories viennent des règles CLDR intégrées à Node.js (voir la prise en charge des langues). Formats vérifiés :

other est toujours requise. Une branche exacte comme =1 ne remplace jamais une catégorie, les branches select ne sont jamais vérifiées, et seul un pluriel dont la cible a au moins une forme est vérifié. C'est un avertissement : un check simple garde son code de sortie, et --qa --strict échoue dessus. verbatra doctor signale les mêmes pluriels. Avec --json, chaque locale porte incompletePlurals, trié par clé :

interface IncompletePlural {
  code: "PLURAL_CATEGORIES_INCOMPLETE";
  key: string;              // clé de base, ou la clé du message ICU
  argument?: string;        // l'argument du pluriel ICU, comme count
  ruleType: "cardinal" | "ordinal";
  missing: ("zero" | "one" | "two" | "few" | "many" | "other")[]; // dans l'ordre CLDR
}

Contrôle qualitéCopier le lien vers cette section

--qa applique les vérifications qu'une traduction fait sur la sortie du fournisseur aux valeurs déjà présentes dans tes fichiers de locale, obsolètes ou non, y compris les formes plurielles supplémentaires dont la langue cible a besoin. Les résultats ont deux gravités :

• error : la valeur échoue à la barrière d'intégrité, avec placeholder, markup, icu, degenerate ou empty. Les détails listent les tokens perdus en -{{name}} et les ajoutés en +{{nom}}.
• warning : la valeur porte un motif de relecture calculé à partir de la valeur, de sa source et de ta configuration (glossaire, maxLength), donc aucun qui dépende du fournisseur ou du cache ; pour FOREIGN_PLACEHOLDER_CHANGED, les details du constat nomment chaque jeton perdu ou modifié, comme -{name}. Une valeur en erreur ne reçoit pas d'avertissement.

qa: 1 error, 1 warning
  de: 1 error, 1 warning in 42 values checked
    greeting: error placeholder (-{{name}}, +{{nme}})
    title: warning EQUALS_SOURCE

Les clés orphelines et manquantes sont ignorées, et les clés source qui ne sont pas de l'ICU valide figurent une fois dans invalidSourceKeys. Les valeurs protégées, épinglées et rejetées sont vérifiées comme les autres. Avec --json, result.qa contient les totaux et chaque locale son propre qa :

interface CheckQaSummary { errors: number; warnings: number; invalidSourceKeys: string[] }
interface LocaleQaReport { checked: number; errors: number; warnings: number; findings: QaFinding[] }
type QaFinding =
  | { key: string; severity: "error"; reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty"; details?: string[] }
  | { key: string; severity: "warning"; reason: string; details?: string[] }; // un des motifs de relecture ci-dessus

Exiger des traductions reluesCopier le lien vers cette section

--require-reviewed échoue avec 1 tant qu'une valeur dont l'origine est machine, memory, fuzzy ou agent n'est pas approuvée dans le verbatra.provenance.json commité, où Studio et les outils MCP enregistrent leurs décisions. Une approbation antérieure au changement du texte source ou de la valeur ne compte pas.

review: failed [REVIEW_REQUIRED] 2 machine-written translations not approved
  de: 2 unreviewed: checkout.title, checkout.total

Avec --json, result.review vaut { reviewed, unreviewed, code? }, où code est REVIEW_REQUIRED, ou REVIEW_STATE_UNREADABLE quand le fichier de provenance est corrompu ou vient d'un verbatra plus récent (le contrôle échoue alors). Chaque locale porte review.unreviewed, les clés dans l'ordre de la source.

Contenu sensibleCopier le lien vers cette section

--sensitive lance l'analyse de la protection des contenus sensibles sur chaque clé source (nom de clé, valeur, description et sens) et le glossaire de chaque locale vérifiée, avec les détecteurs, motifs et la liste allow de sensitiveData (sans bloc, les détecteurs par défaut), quels que soient le mode et le fournisseur, none compris : les valeurs quittent quand même la machine lors des transmissions par export, XLIFF et TMX. Il signale les clés et les détecteurs, jamais le texte trouvé hors d'un nom de clé, et sort avec 1 à la moindre trouvaille.

Le détecteur email ignore les domaines d'exemple réservés : teste donc avec une adresse d'apparence réelle.

sensitive: 1 key and 0 glossary terms hold content that looks sensitive
  support.contact: email in value

Avec --json, result.sensitive vaut { findings, glossaryTerms }, chaque trouvaille { key, fields, detectors } ; detectors peut contenir pattern-timeout-<n>.

Un seul fichierCopier le lien vers cette section

--file <path> vérifie un seul fichier de locale, pour les hooks d'éditeur et d'agent après une modification. Il lit ce fichier, verbatra.limits.json nouveau (s'il est inutilisable, ignoré avec un avis sur stderr, comme sous --qa ; doctor nomme le problème) et, pour une locale cible, le fichier source, rien d'autre. Le chemin est résolu par rapport à --cwd et associé à sa locale via files.pattern.

• Un fichier dont l'analyse échoue donne une erreur syntax avec le code de l'adaptateur (INVALID_JSON, INVALID_YAML, ...) et la ligne et la colonne quand l'analyseur signale une position.
• Un fichier cible est vérifié comme avec --qa, catégories de pluriel comprises ; un fichier source, pour sa syntaxe seulement. Un catalogue apple-xcstrings est vérifié pour chaque locale cible.
• Un chemin qui n'est le fichier d'aucune locale configurée échoue avec NOT_A_LOCALE_FILE et la sortie 2.

Avec --json, result reprend le rapport de --qa, pour qu'un hook n'analyse qu'une forme :

interface CheckFileSummary {
  file: string;                          // relatif à la racine du projet
  role: "source" | "target" | "catalogue";
  locales: {
    locale: string;
    incompletePlurals: IncompletePlural[];
    qa: { checked: number; errors: number; warnings: number; findings: (QaFinding | QaSyntaxFinding)[] };
  }[];
  qa: CheckQaSummary;
}
interface QaSyntaxFinding {
  severity: "error"; reason: "syntax"; code: string; message: string;
  line?: number; column?: number;       // si l'analyseur signale une position, compté à partir de 1
}

Les clés manquantes et obsolètes ne font pas partie de la vérification d'un fichier.

Sortie JSONCopier le lien vers cette section

Schéma : check-envelope.json valide l'enveloppe entière ; Schémas liste les autres.

--json affiche une enveloppe dont le result est le document d'état. Sans --qa, --require-reviewed ni --sensitive, inSync est vrai exactement quand la commande sort avec 0 :

interface CheckSummary {
  inSync: boolean;
  locales: LocaleCheckSummary[];
  qa?: CheckQaSummary;          // seulement avec --qa
  review?: CheckReviewSummary;  // seulement avec --require-reviewed
  sensitive?: CheckSensitiveSummary; // seulement avec --sensitive
}

interface LocaleCheckSummary {
  locale: string;
  missing: number;              // dans la source, absente de la cible
  stale: number;                // source modifiée depuis la dernière traduction
  upToDate: number;
  inSync: boolean;              // missing === 0 && stale === 0
  emptySource?: number;         // valeur source vide : jamais manquante ni obsolète
  provenance?: ProvenanceSummary; // décomptes par origine et état de relecture
  protected?: number;
  incompletePlurals?: IncompletePlural[];
  inconsistencies?: InconsistencyGroup[]; // seulement avec --consistency
  qa?: LocaleQaReport;          // seulement avec --qa
  review?: LocaleReviewReport;  // seulement avec --require-reviewed
}

Une clé source dont la valeur est vide ou ne contient que des espaces, comme une clé qu'extract a ajoutée sans valeur par défaut, n'a encore rien à traduire : elle est comptée dans emptySource au lieu de missing ou stale, ne désynchronise jamais une locale, et la sortie du terminal en donne le nombre.

Retour dans le terminalCopier le lien vers cette section

check affiche verbatra: checking the locales... done (0.1s) sur stderr, ou verbatra: checking locales/de.json... avec --file. --quiet la supprime. Voir Sortie dans le terminal.

Codes de sortieCopier le lien vers cette section

La sortie 1 signifie que le résultat n'est pas propre, pas que l'exécution a échoué ; le rapport est quand même affiché. Sur un projet dont le fichier source n'est pas encore en place, verbatra doctor continue de signaler. Le contrat est dans Codes de sortie.

Voir aussiCopier le lien vers cette section

• verbatra diff liste les clés exactes derrière ces chiffres.
• CI et codes de sortie montre check comme contrôle de dérive.
• Le fichier de verrouillage explique comment l'obsolescence est détectée.