Inspect a project

Inspect state without writingCopy Anchor Link

None of these translate or mutate the lock. Only extract writes a file (the source catalog), and only doctor with live makes a network request (the provider's language list).

doctor Available from 0.9.0Copy Anchor Link

Validates the project setup and spends nothing: it constructs no provider and makes no network request unless live asks for one, and reads the API key value only for that one language-list request (LibreTranslate gets no key). Every check runs even when an earlier one failed, so one call reports every independent problem; verbatra doctor lists the checks.

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

Returns: DoctorResult

Throws: CONFIG_NOT_FOUND

The network-policy check fails when the effective network policy refuses the provider's host or proxy, or a network variable is invalid, and passes for the none provider. The informational checks never fail and rename nothing; a warn leaves ok true, and the check table says what each names and when it is skipped.

The locales check judges every configured locale as translate does before it spends: it fails on an unsupported locale, is skipped for none, and returns the verdicts in DoctorResult.locales as a LocaleCapabilityReport. With live: true it first fetches the provider's current language list, using no quota; LocaleCapabilityReport.live says how that went. See Language support.

With literals set, only the config and untranslated-literals checks run, as verbatra doctor --literals does. doctor loads the config itself, so a project with no config gets a report, not a thrown error: ok is true exactly when no check failed, and CONFIG_NOT_FOUND is thrown only for an explicit configPath that does not exist.

Only a failed check carries fix, one imperative next step; like detail, it names variables and paths, never a key value.

dataFlow Available from 0.12.0Copy Anchor Link

Describes where a project's data goes, for the loaded config, as a versioned DataFlowManifest. verbatra doctor --data-flow prints it and lists its fields; doctor({ dataFlow: true }) returns it as DoctorResult.dataFlow. It reads no API key and makes no network request. An invalid network variable or an unreadable source file is reported in the manifest rather than thrown.

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

Returns: DataFlowManifest

Throws: CONFIG_NOT_FOUND, CONFIG_INVALID

dataFlowManifestSchema Available from 0.12.0Copy Anchor Link

The zod schema for a DataFlowManifest, so a CI step or a reviewer's tooling can validate one. Unknown fields are kept, since a newer verbatra may add fields within version 1; ignore the ones you do not know. DATA_FLOW_MANIFEST_VERSION is the version this build writes.

const dataFlowManifestSchema: z.ZodType<DataFlowManifest>;

extract Available from 0.11.0Copy Anchor Link

Scans your application source for translation call sites and merges what it finds into the source locale catalog, even one that does not exist yet. It constructs no provider, reads no API key, and makes no network request.

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

Returns: ExtractResult

Throws: EXTRACT_NOT_CONFIGURED, EXTRACT_FS_UNSUPPORTED, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_INVALID, SOURCE_UNWRITABLE

Example: Extract keys from your source code

Only genuinely new keys are added (What it writes). What the scan cannot resolve comes back as data in dynamic, conflicts, and diagnostics, never thrown (What it reports), and the result never carries a source file's contents.

config.extract names the framework and the source roots. Discovery needs the optional readDirectory member of SdkFs; without it, EXTRACT_FS_UNSUPPORTED.

check Available from 0.4.0Copy Anchor Link

Reports per-locale drift as counts: missing (in source, absent from target), stale (source changed since last translated), and upToDate. Use it as a CI gate.

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

Returns: CheckSummary

Throws: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, UNKNOWN_LOCALE

Example: Check in CI without writing

inSync is true exactly when every checked locale has nothing missing and nothing stale.

With consistency: true, each LocaleCheckSummary also carries inconsistencies: one InconsistencyGroup per source string the locale translates more than one way under different keys, in the shape the consistency report shows. It is a report only: it never changes inSync, a count, or any file.

Each LocaleCheckSummary also carries provenance: counts byOrigin and byReviewState over the keys the locale has a value for, read from verbatra.provenance.json (origins). This and every other provenance field in a report is left out, never an error, when the file is corrupt or from a newer verbatra.

Each LocaleCheckSummary also carries protected, the share of stale a translate run would leave for a person under humanEdits and pinnedKeys (Protected keys). They still count as stale, so inSync stays false until a person resolves them; a missing pinned key counts only as missing.

With qa: true, check also runs the quality check over every committed value, keyless and without writing: each LocaleCheckSummary carries a qa report and the summary qa totals, in that section's shapes. Error reasons come from INTEGRITY_GATE_REASONS, warning reasons from REVIEW_REASON_CODES, severities from QA_SEVERITIES; qaSeverity: "error" skips warnings. It never changes inSync: a CI gate reads qa.errors, plus qa.warnings when strict.

Each LocaleCheckSummary also carries incompletePlurals, ordered by key: one IncompletePlural { code: "PLURAL_CATEGORIES_INCOMPLETE", key, argument?, ruleType, missing } per plural lacking CLDR categories the target language uses. A warning only; plural categories lists the formats and rules.

With requireReviewed: true, check also runs the review gate, keyless and without writing: each LocaleCheckSummary carries review: { unreviewed }, the machine-class keys not approved, and the summary carries review: { reviewed, unreviewed, code? } with the codes that section names. The report never changes inSync; a CI gate reads review.reviewed.

With sensitive: true, check also runs the sensitive content scan, keyless and without writing: the summary carries sensitive: { findings, glossaryTerms }, one { key, fields, detectors } per flagged key, never the matched text. A CI gate fails on either.

checkFile Available from 0.12.0Copy Anchor Link

Checks one locale file right after a person or an agent edited it. It reads only that file and, for a target locale, the source file; it calls no provider, reads no API key, and writes nothing.

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

Returns: CheckFileSummary

Throws: NOT_A_LOCALE_FILE, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

file is absolute or relative to cwd; One file shows the CheckFileSummary shape. A target file is checked like check with qa: true, the source file for syntax alone. A file that does not parse is not thrown: its locale carries one QaSyntaxFinding, with the position AdapterError.position reports for JSON and YAML. A path that is no configured locale's file, or a missing file, throws NOT_A_LOCALE_FILE.

diff Available from 0.4.0Copy Anchor Link

The detailed sibling of check: the same computation, but it returns the key lists per locale (missing, changed, orphaned) instead of counts. Orphaned keys are report-only and never flip hasPendingChanges, since a default run does not prune.

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

Returns: DiffSummary

Throws: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, UNKNOWN_LOCALE

Example: Check in CI without writing

With unused: true it also scans the config's extract roots, read-only and keyless, and adds an unused report of the source-locale keys no static reference names, separate from every orphaned list and never flipping hasPendingChanges; Unused source keys explains its fields.

Each LocaleDiff also carries changedOrigins, the origin of each changed key's current value (such as machine, human, or external): whose work a retranslation would replace.

Each LocaleDiff also carries protected, the missing and changed keys a translate run would leave alone, sorted; they still count as pending.

keyIntegrity Available from 0.5.0Copy Anchor Link

Reports, for each locale's changed keys, whether the current target value still matches the source's placeholders and inline markup and is valid ICU: each entry carries key, hasPlaceholders, matches, the missing and extra tokens on a mismatch, icuValid, markupMatches, and markupDetails, never a string value. Values written before the write-time gate existed or edited outside verbatra are judged the same. Studio surfaces this per-key report.

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

Returns: readonly LocaleKeyIntegrity[]

Throws: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, UNKNOWN_LOCALE, UNKNOWN_KEY

Each entry also carries icuArmsMatch and icuArmDetails: whether the value's ICU plural, selectordinal, and select arms fit the target language, judged as the write-time gate judges them, with one short problem per wrong arm. icuArmsMatch is always true for a format that does not check arms.

keys narrows the check; only keys that are "changed" for a locale are ever checked.

localeIntegrity Available from 0.12.0Copy Anchor Link

Finds every translation in the target locales that is broken right now: a lost or added placeholder or inline markup, invalid ICU, or ICU arms that do not fit the target language. Unlike keyIntegrity, it judges every key present in both the source and a target locale, whatever its sync state, by the same rules, and returns only failing keys: an empty entries list means the locale passes.

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

Returns: readonly LocaleKeyIntegrity[]

Throws: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_LOCALE

Each call reads and parses the source and each requested target file fresh, with no cache.

lockState Available from 0.5.0Copy Anchor Link

Reports the lock file's existence, version, and per-locale drift (baseline key count plus missing, stale, and up-to-date counts). exists comes from an explicit probe, so an absent and an empty lock file stay distinguishable; when absent, the result is { exists: false } and nothing else is read.

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

Returns: LockStateResult

Throws: UNKNOWN_LOCALE, LOCK_FILE_INVALID, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

Each locale also carries the same provenance counts check reports.

loadLockFile Available from 0.5.0Copy Anchor Link

Reads the lock file itself (verbatra.lock.json, also exported as LOCK_FILE_NAME) and returns its parsed shape: { version, locales }, where each locale maps keys to the source content hash they were last translated from. A missing file degrades to an empty lock, the same first-run behavior translate relies on; use lockState when you need to distinguish absence.

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

Returns: LockFile

Throws: LOCK_FILE_INVALID

No config needed.

loadProvenance Available from 0.12.0Copy Anchor Link

Reads the provenance file itself (verbatra.provenance.json, also exported as PROVENANCE_FILE_NAME) and returns its stored shape: { version, locales }, where each locale maps keys to a record { origin, provider?, model?, valueHash, reviewState?, reviewer?, reviewedSourceHash? }, with no translated text. A missing file, or one from a newer verbatra, reads as empty; a corrupt one throws PROVENANCE_FILE_INVALID. keyValue, localeValues, check, diff, and lockState report the interpreted view (KeyProvenance), which also tells unrecorded from external.

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

Returns: ProvenanceFile

Throws: PROVENANCE_FILE_INVALID

No config needed.

runStatus Available from 0.5.0Copy Anchor Link

Reads the review-flag and token-usage snapshot the most recent non-dry-run translate or watch run persisted to .verbatra-local/run-status.json. Never throws: an unusable file degrades to available: false. The file is best-effort telemetry, not a correctness baseline.

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

Returns: RunStatusResult

No config needed. Returns { available: false, reason } (see RUN_STATUS_UNAVAILABLE_REASONS) or { available: true, version, generatedAt, usage?, budget?, locales }.

A snapshot from before the token budget was enforced is still read, minus a budget with supported: false (its tokensUsed: 0 was not a count). New snapshots add only a marker field, so an older reader may show an estimated budget as not tracked. An unknown review reason is ignored, and an entry left with none is dropped.

reviewQueue Available from 0.12.0Copy Anchor Link

Reads the review queue from the committed files: every key whose current value has a machine-class origin (machine, memory, fuzzy, or agent, the MACHINE_CLASS_ORIGINS tuple) and is not approved, per target locale, in source order. It reads the locale files, verbatra.lock.json, and verbatra.provenance.json, so everyone on the same commit sees the same queue. A key leaves it once its value is approved or rejected, or a person writes or imports a new value; a value an agent rewrote stays, and so does an approval given before the source changed. The last runStatus snapshot only adds detail: each entry's reasons (empty when the run did not flag it with a known reason), the locale's fuzzyHits, and lastRunAt.

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

Returns: ReviewQueueResult

Throws: UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID

Example: Work through the review queue

Returns { available: true, locales, lastRunAt? }, each locale { locale, needsReview, approved?, fuzzyHits? } and each entry { key, reasons, provenance }; approved lists the approved machine-class values and is present only with includeApproved: true. When the provenance file is corrupt or from a newer verbatra it returns { available: false, reason: "provenance-unreadable" }. A source, target, or lock file that cannot be read fails the call as it fails check. Up to 0.11 the queue was the last run's flags only.

provenanceReport Available from 0.12.0Copy Anchor Link

Builds the per-locale report verbatra report provenance prints: every key with a value in both the source and a target locale, in source order, with its origin, review state, provider, model and reviewer, counted in one PROVENANCE_BUCKETS bucket (the provenance report defines them). It calls no provider and writes nothing.

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

Returns: ProvenanceReportResult

Throws: UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID

deps also takes now, the clock for generatedAt. The result's full shape is the JSON schema. When the provenance file is corrupt or from a newer verbatra it returns { available: false, reason: "provenance-unreadable" }, since every value would read as unrecorded. A source, target, or lock file that cannot be read fails the call as it fails check. The report is supporting evidence, not legal advice.

provenanceReportPage Available from 0.12.0Copy Anchor Link

Builds the same report as provenanceReport and returns its entries one page at a time, optionally only those in some buckets, with a cursor for the next page. Every page keeps each locale's full total and counts. The MCP server's report.provenance pages with it. Read-only.

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

Returns: ProvenanceReportPageResult

Throws: UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, PAGE_CURSOR_INVALID, PAGE_LIMIT_INVALID

Each locale carries entries only on the pages that hold one of them. A page holds at most limit entries, PAGE_LIMIT_DEFAULT by default; pass nextCursor back as cursor, with the same locales and buckets, until it is absent. It is unavailable, or fails, exactly when provenanceReport is.