--- title: "verbatra check" description: "Signale les clés manquantes ou obsolètes par locale sans écrire de fichiers ni appeler de fournisseur, et fait échouer la CI tant qu'une locale est en retard." type: "reference" --- # verbatra check Signale les clés manquantes ou obsolètes par locale sans écrire de fichiers ni appeler de fournisseur, et fait échouer la CI tant qu'une locale est en retard. 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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md) avant d'appeler le fournisseur, puis s'arrête : aucun appel au fournisseur, aucun fichier écrit, aucune clé d'API requise. ## Synopsis [#synopsis] ```bash verbatra check [flags] ``` ## Exemples [#exemples] ```bash # 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 ``` ## Options [#options] | Option | Argument | Défaut | Effet | | --- | --- | --- | --- | | `--locales` | `` | toutes les cibles configurées | vérifie seulement ce sous-ensemble séparé par des virgules ; une locale non configurée échoue avec `UNKNOWN_LOCALE` et une liste vide avec `INVALID_LOCALES`, les deux avec la sortie `2` | | `--consistency` | aucun | désactivé | liste aussi les textes source traduits de plusieurs façons ; rapport seulement, voir le [rapport de cohérence](#rapport-de-cohérence) | | `--qa` | aucun | désactivé | lance aussi le [contrôle qualité](#contrôle-qualité) sur chaque traduction commitée ; sortie `1` en cas d'erreur | | `--file` | `` | désactivé | vérifie seulement ce fichier de locale, voir [Un seul fichier](#un-seul-fichier) ; pas avec `--locales`, `--consistency`, `--require-reviewed` ni `--sensitive` | | `--severity` | `error` ou `warning` | `warning` | avec `--qa` ou `--file`, la gravité minimale signalée | | `--strict` | aucun | désactivé | avec `--qa` ou `--file`, sortie `1` aussi sur un avertissement ou un [pluriel incomplet](#catégories-de-pluriel) ; pas avec `--severity error` | | `--require-reviewed` | aucun | désactivé | sortie `1` aussi tant qu'une traduction écrite par une machine n'est [pas approuvée](#exiger-des-traductions-relues) | | `--sensitive` | aucun | désactivé | analyse aussi le fichier source et le glossaire à la recherche de [contenu sensible](#contenu-sensible) ; sortie `1` à la moindre trouvaille | Accepte aussi les [options globales](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md). ## Comportement [#comportement] ### Rapport de cohérence [#rapport-de-cohérence] `--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ées [#clés-protégées] 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](https://verbatra.kreitz-webdev.de/fr/docs/protecting-human-translations.md)). `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 pluriel [#catégories-de-pluriel] Chaque `check` liste les pluriels auxquels il manque une catégorie de pluriel CLDR utilisée par leur langue cible, comme un `` Android polonais avec seulement `one` et `other` : ```text output 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](https://verbatra.kreitz-webdev.de/fr/docs/language-support.md#pluriels)). Formats vérifiés : | Format | Formes de pluriel lues | | --- | --- | | `i18next-json` | les suffixes de clé `_one`, `_few`, ... et les pluriels `_ordinal_` selon les règles ordinales | | `android-xml` | les entrées `` de chaque `` | | `apple-strings` | les règles de pluriel du `.stringsdict` à côté du fichier `.strings` | | `apple-xcstrings` | les catégories `variations.plural` de chaque locale | | `next-intl-json`, `arb` | chaque `plural` et `selectordinal` ICU, y compris imbriqué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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md) signale les mêmes pluriels. Avec `--json`, chaque locale porte `incompletePlurals`, trié par clé : ```ts 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é [#contrôle-qualité] `--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é](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md#la-barrière-dinté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](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md#signalements-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. ```text output 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` : ```ts 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 relues [#exiger-des-traductions-relues] `--require-reviewed` échoue avec `1` tant qu'une valeur dont l'[origine](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md#la-provenance-de-chaque-valeur) est `machine`, `memory`, `fuzzy` ou `agent` n'est pas approuvée dans le `verbatra.provenance.json` commité, où [Studio](https://verbatra.kreitz-webdev.de/fr/docs/review-in-studio.md) et les [outils MCP](https://verbatra.kreitz-webdev.de/fr/docs/cli/mcp.md) enregistrent leurs décisions. Une approbation antérieure au changement du texte source ou de la valeur ne compte pas. ```text output 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 sensible [#contenu-sensible] `--sensitive` lance l'analyse de la [protection des contenus sensibles](https://verbatra.kreitz-webdev.de/fr/docs/data-handling.md#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](https://verbatra.kreitz-webdev.de/fr/docs/data-handling.md#protection-des-contenus-sensibles) : teste donc avec une adresse d'apparence réelle. ```text output 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-`. ### Un seul fichier [#un-seul-fichier] `--file ` 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` (s'il est inutilisable, ignoré avec un avis sur stderr, comme sous `--qa` ; [`doctor`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md) 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`](#contrôle-qualité), 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 : ```ts 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 JSON [#sortie-json] Schéma : [`check-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/check-envelope.json) valide l'enveloppe entière ; [Schémas](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#schémas) liste les autres. `--json` affiche une [enveloppe](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-json) dont le `result` est le document d'état. Sans `--qa`, `--require-reviewed` ni `--sensitive`, `inSync` est vrai exactement quand la commande sort avec `0` : ```ts 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 terminal [#retour-dans-le-terminal] `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](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-dans-le-terminal). ## Codes de sortie [#codes-de-sortie] | Code | Signification | | --- | --- | | `0` | synchronisé, et aucun résultat que les options passées transforment en échec | | `1` | une locale a une clé manquante ou obsolète, `--qa` ou `--file` a trouvé une erreur (ou, avec `--strict`, un avertissement ou un pluriel incomplet), `--require-reviewed` a trouvé une traduction non approuvée, ou `--sensitive` a trouvé du contenu sensible | | `2` | exécution impossible : une erreur sur toute l'exécution comme `SOURCE_UNREADABLE` ou `NOT_A_LOCALE_FILE`, ou une erreur d'usage comme `INVALID_QA_OPTION`, `INVALID_SEVERITY` ou `INVALID_OPTION` pour un `--file` vide ou combiné avec `--locales`, `--consistency`, `--require-reviewed` ou `--sensitive` | 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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md) continue de signaler. Le contrat est dans [Codes de sortie](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#codes-de-sortie). ## Voir aussi [#voir-aussi] - [`verbatra diff`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md) liste les clés exactes derrière ces chiffres. - [CI et codes de sortie](https://verbatra.kreitz-webdev.de/fr/docs/ci-and-exit-codes.md) montre `check` comme contrôle de dérive. - [Le fichier de verrouillage](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md) explique comment l'obsolescence est détectée.