---
title: "Inspecter un projet"
description: "Les points d'entrée en lecture seule du SDK derrière doctor, check et diff, plus les contrôles d'intégrité et l'état du verrou et de la provenance."
type: "reference"
---
# Inspecter un projet

Les points d'entrée en lecture seule du SDK derrière doctor, check et diff, plus les contrôles d'intégrité et l'état du verrou et de la provenance.

## Inspecter l'état sans écrire [#inspecter-létat-sans-écrire]

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 [#doctor]

<AvailableFrom version="0.9.0" />

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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md#ce-quil-vérifie) liste les vérifications.

```ts title="Signature"
function doctor(
  input?: DoctorInput,
  deps?: DoctorDeps,
): Promise<DoctorResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `cwd` | `string` | no | Directory to search the config from. Defaults to the process working directory. Locale paths resolve against the project root resolveProjectRoot returns: the directory of a config found by the search, otherwise this directory. |
| `configPath` | `string` | no | An explicit config file to validate, bypassing the search. A missing file is an error rather than a failed check. |
| `literals` | `boolean` | no | Run the untranslated-literal scan instead of the setup checks: the config is loaded, then the source roots of its `extract` block are scanned for hardcoded user-facing string literals. No other setup check runs (`format-adapter`, `provider`, `api-key`, `network-policy`, `source-file`, `plural-rules`, `plural-completeness`, `locale-codes`, `locale-state`, `locales`), so no API key environment variable is looked at and a run with no key set can pass. |
| `dataFlow` | `boolean` | no | Describe where the project's data goes instead of running the setup checks: the config is loaded and DoctorResult.dataFlow carries the DataFlowManifest dataFlow builds. Only the `config` and `data-flow` checks run, no API key is read and no network request is made. Takes precedence over DoctorInput.live; ignored when DoctorInput.literals is set. |
| `live` | `boolean` | no | Fetch the configured machine-translation provider's current language list before the `locales` check, instead of judging against the table verbatra ships. It is the one doctor option that sends a network request: to the provider's language list endpoint only (DeepL's `/v3/languages`, Google Cloud Translation's `languages`, or the `languages` endpoint of the configured LibreTranslate server), which uses no translation quota. For DeepL and Google Cloud Translation the request is sent only when the provider's API key variable is set, while LibreTranslate needs no key variable; in every case it is sent only when the network policy permits the provider's host; otherwise, or when the request fails, the static table is used and LocaleCapabilityReport.live says why. It does nothing for an LLM provider or `none`. Ignored on a literal run. Defaults to false. |
| `onProgress` | `ScanProgressListener` | no | Called once after each application source file the `literals` scan reads, with the running count and the total, for progress reporting. |

**Renvoie :** `DoctorResult`

**Lève :** [`CONFIG_NOT_FOUND`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#config_not_found)

<AvailableFrom version="0.12.0" />

La vérification `network-policy` échoue quand la [politique réseau](https://verbatra.kreitz-webdev.de/fr/docs/network-policy.md) 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](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md#ce-quil-vérifie) dit ce que chacune nomme et quand elle vaut `skipped`.

<AvailableFrom version="0.12.0" />

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](https://verbatra.kreitz-webdev.de/fr/docs/language-support.md#vérifier-la-prise-en-charge-avant-une-exécution).

Avec `literals` activé, seules les vérifications `config` et `untranslated-literals` s'exécutent, comme avec [`verbatra doctor --literals`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md#littéraux-non-traduits). `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.

<AvailableFrom version="0.12.0" />

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 [#dataflow]

<AvailableFrom version="0.12.0" />

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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md#flux-de-données) 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é.

```ts title="Signature"
function dataFlow(
  input?: DataFlowInput,
  deps?: DataFlowDeps,
): Promise<DataFlowManifest>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `cwd` | `string` | no | Directory to search the config from. Defaults to the process working directory. Every path resolves against the project root resolveProjectRoot returns: the directory of a config found by the search, otherwise this directory. |
| `configPath` | `string` | no | An explicit config file to describe, bypassing the search. |

**Renvoie :** `DataFlowManifest`

**Lève :** [`CONFIG_NOT_FOUND`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#config_not_found), [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#config_invalid)

### dataFlowManifestSchema [#dataflowmanifestschema]

<AvailableFrom version="0.12.0" />

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.

```ts title="Signature"
const dataFlowManifestSchema: z.ZodType<DataFlowManifest>;
```

### extract [#extract]

<AvailableFrom version="0.11.0" />

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.

```ts title="Signature"
function extract(
  input: ExtractInput,
  deps?: ExtractDeps,
): Promise<ExtractResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | A resolved config whose `extract` block names the framework and the source roots. |
| `cwd` | `string` | no | Directory the roots and locale paths are resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `dryRun` | `boolean` | no | Report what would be added without writing anything. |
| `onProgress` | `ScanProgressListener` | no | Called once after each application source file the scan reads, with the running count and the total, for progress reporting. |

**Renvoie :** `ExtractResult`

**Lève :** [`EXTRACT_NOT_CONFIGURED`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#extract_not_configured), [`EXTRACT_FS_UNSUPPORTED`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#extract_fs_unsupported), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`SOURCE_UNWRITABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unwritable)

**Exemple :** [Extraire les clés de ton code source](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#extraire-les-clés-de-ton-code-source)

Seules les clés réellement nouvelles sont ajoutées ([Ce qu'elle écrit](https://verbatra.kreitz-webdev.de/fr/docs/cli/extract.md#ce-quelle-é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](https://verbatra.kreitz-webdev.de/fr/docs/cli/extract.md#ce-quelle-signale-plutôt-que-de-deviner)), 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 [#check]

<AvailableFrom version="0.4.0" />

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.

```ts title="Signature"
function check(
  input: CheckInput,
  deps?: CheckDeps,
): Promise<CheckSummary>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |
| `consistency` | `boolean` | no | Also report, per locale, every source string translated more than one way under different keys (see LocaleCheckSummary.inconsistencies). Defaults to false. |
| `qa` | `boolean` | no | Also run the quality check over every committed value (see LocaleCheckSummary.qa): the write-time integrity gate, whose refusals are reported as errors, and the review reasons a translation run computes, reported as warnings. Keyless: no provider is called and nothing is written. Defaults to false. |
| `qaSeverity` | `"error" \| "warning"` | no | The lowest severity the quality check reports. `error` skips the review reasons entirely, so only integrity failures are reported. Ignored unless CheckInput.qa is true. Defaults to `warning`. |
| `requireReviewed` | `boolean` | no | Also run the review gate (see CheckSummary.review): every value written by a machine-class path (see MACHINE_CLASS_ORIGINS) must be approved in the provenance file. A value a person wrote, imported, or edited outside verbatra needs no approval, and neither does one with no provenance record. An approval given against a source text that has changed since does not count. Keyless: no provider is called and nothing is written. Defaults to false. |
| `sensitive` | `boolean` | no | Also scan the source file and the glossary of every reported locale for content that looks sensitive (see CheckSummary.sensitive), with the config's `sensitiveData` detectors, patterns and allow list, or the default detectors when the block is absent. It scans every field a language model would receive, whatever the configured provider and `sensitiveData.mode`. Keyless: no provider is called and nothing is written. Defaults to false. |

**Renvoie :** `CheckSummary`

**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale)

**Exemple :** [Vérifier en CI sans écrire](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#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.

<AvailableFrom version="0.11.0" />

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](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#rapport-de-cohérence). Ce n'est qu'un rapport : il ne change jamais `inSync`, un compte ou un fichier.

<AvailableFrom version="0.12.0" />

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](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md#la-provenance-de-chaque-valeur)). 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.

<AvailableFrom version="0.12.0" />

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](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#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.

<AvailableFrom version="0.12.0" />

Avec `qa: true`, `check` lance aussi le [contrôle qualité](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#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`.

<AvailableFrom version="0.12.0" />

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](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#catégories-de-pluriel).

Avec `requireReviewed: true`, `check` exécute aussi la [barrière de relecture](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#exiger-des-traductions-relues), 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`.

<AvailableFrom version="0.12.0" />

Avec `sensitive: true`, `check` lance aussi l'analyse de [contenu sensible](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#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 [#checkfile]

<AvailableFrom version="0.12.0" />

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.

```ts title="Signature"
function checkFile(
  input: CheckFileInput,
  deps?: CheckFileDeps,
): Promise<CheckFileSummary>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` and CheckFileInput.file are resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `file` | `string` | yes | The locale file to check, absolute or relative to the working directory. |
| `qaSeverity` | `"error" \| "warning"` | no | The lowest severity to report. `error` skips the review reasons, so only syntax and integrity failures are reported. Defaults to `warning`. |

**Renvoie :** `CheckFileSummary`

**Lève :** [`NOT_A_LOCALE_FILE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#not_a_locale_file), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid)

`file` est absolu ou relatif à `cwd` ; [Un seul fichier](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#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 [#diff]

<AvailableFrom version="0.4.0" />

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.

```ts title="Signature"
function diff(
  input: DiffInput,
  deps?: DiffDeps,
): Promise<DiffSummary>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |
| `unused` | `boolean` | no | Also scan the application source configured in the `extract` block and report the source-catalog keys nothing references, as DiffSummary.unused. Off by default. |
| `onProgress` | `ScanProgressListener` | no | Called once after each application source file the `unused` scan reads, with the running count and the total, for progress reporting. |

**Renvoie :** `DiffSummary`

**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale)

**Exemple :** [Vérifier en CI sans écrire](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#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](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md#clés-source-inutilisées) en explique les champs.

<AvailableFrom version="0.12.0" />

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.

<AvailableFrom version="0.12.0" />

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 [#keyintegrity]

<AvailableFrom version="0.5.0" />

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é.

```ts title="Signature"
function keyIntegrity(
  input: KeyIntegrityInput,
  deps?: KeyIntegrityDeps,
): Promise<readonly LocaleKeyIntegrity[]>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |
| `keys` | `readonly string[]` | no | Restrict the report to these keys. Each must exist in the source resource. Only keys the diff reports as changed are ever judged, so a requested key whose translation is missing or up to date is left out rather than reported. Defaults to every changed key. |

**Renvoie :** `readonly LocaleKeyIntegrity[]`

**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`UNKNOWN_KEY`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_key)

<AvailableFrom version="0.12.0" />

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](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md#branches-plurielles-par-langue-cible) 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 [#localeintegrity]

<AvailableFrom version="0.12.0" />

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.

```ts title="Signature"
function localeIntegrity(
  input: LocaleIntegrityInput,
  deps?: LocaleIntegrityDeps,
): Promise<readonly LocaleKeyIntegrity[]>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |

**Renvoie :** `readonly LocaleKeyIntegrity[]`

**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale)

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

### lockState [#lockstate]

<AvailableFrom version="0.5.0" />

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.

```ts title="Signature"
function lockState(
  input: LockStateInput,
  deps?: LockStateDeps,
): Promise<LockStateResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |

**Renvoie :** `LockStateResult`

**Lève :** [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid)

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

### loadLockFile [#loadlockfile]

<AvailableFrom version="0.5.0" />

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.

```ts title="Signature"
function loadLockFile(
  input?: LoadLockFileInput,
  deps?: LoadLockFileDeps,
): Promise<LockFile>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `cwd` | `string` | no | Directory holding the lock-file. Defaults to the process working directory, even when the config was found in a parent directory: pass the root resolveProjectRoot returns. |

**Renvoie :** `LockFile`

**Lève :** [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid)

Aucune config requise.

### loadProvenance [#loadprovenance]

<AvailableFrom version="0.12.0" />

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`.

```ts title="Signature"
function loadProvenance(
  input?: LoadProvenanceInput,
  deps?: LoadProvenanceDeps,
): Promise<ProvenanceFile>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `cwd` | `string` | no | Directory holding the provenance file. Defaults to the process working directory, even when the config was found in a parent directory: pass the root resolveProjectRoot returns. |

**Renvoie :** `ProvenanceFile`

**Lève :** [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#provenance_file_invalid)

Aucune config nécessaire.

### runStatus [#runstatus]

<AvailableFrom version="0.5.0" />

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.

```ts title="Signature"
function runStatus(
  input?: RunStatusInput,
  deps?: RunStatusDeps,
): Promise<RunStatusResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `cwd` | `string` | no | Directory holding the `.verbatra-local` status directory. Defaults to the process working directory, even when the config was found in a parent directory: pass the root resolveProjectRoot returns. |

**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 [#reviewqueue]

<AvailableFrom version="0.12.0" />

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`.

```ts title="Signature"
function reviewQueue(
  input: ReviewQueueInput,
  deps?: ReviewQueueDeps,
): Promise<ReviewQueueResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the queue to these target locales. Defaults to every configured target locale. |
| `includeApproved` | `boolean` | no | Also list, per locale, the machine-class values already approved (see ReviewQueueLocale.approved), for a reviewer who wants to revisit them. Defaults to false. |

**Renvoie :** `ReviewQueueResult`

**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid)

**Exemple :** [Traiter la file de relecture](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#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 [#provenancereport]

<AvailableFrom version="0.12.0" />

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](https://verbatra.kreitz-webdev.de/fr/docs/provenance-evidence.md#le-rapport-de-provenance) les définit). Il n'appelle aucun fournisseur et n'écrit rien.

```ts title="Signature"
function provenanceReport(
  input: ProvenanceReportInput,
  deps?: ProvenanceReportDeps,
): Promise<ProvenanceReportResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |
| `toolVersion` | `string` | no | The verbatra version to stamp on the report, as ProvenanceReport.toolVersion. Defaults to `unknown`. |

**Renvoie :** `ProvenanceReportResult`

**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid)

`deps` accepte aussi `now`, l'horloge de `generatedAt`. La forme complète du résultat figure dans [le schéma JSON](https://verbatra.kreitz-webdev.de/fr/docs/provenance-evidence.md#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 [#provenancereportpage]

<AvailableFrom version="0.12.0" />

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.

```ts title="Signature"
function provenanceReportPage(
  input: ProvenanceReportPageInput,
  deps?: ProvenanceReportDeps,
): Promise<ProvenanceReportPageResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `buckets` | `array` | no | List only the entries in these buckets. The counts always cover every bucket. |
| `limit` | `number` | no | The most entries the page holds, a whole number from 1 to PAGE_LIMIT_CAP. Defaults to PAGE_LIMIT_DEFAULT. |
| `cursor` | `string` | no | The `nextCursor` of the previous page. Omit it to read the first page. |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |
| `toolVersion` | `string` | no | The verbatra version to stamp on the report, as ProvenanceReport.toolVersion. Defaults to `unknown`. |

**Renvoie :** `ProvenanceReportPageResult`

**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`PAGE_CURSOR_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#page_cursor_invalid), [`PAGE_LIMIT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#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.