verbatra diff

List the exact pending keys per target locale: the ones a run would add, the ones it would re-translate, and the ones now orphaned. diff runs the same read and diff as verbatra translate, then stops: no provider call, no file written, no lock file update, no API key needed.

SynopsisCopy Anchor Link

verbatra diff [flags]

ExamplesCopy Anchor Link

# list the pending keys per locale (exit 1 if any are pending)
verbatra diff

# only the German and French locales
verbatra diff --locales de,fr

# machine-readable key lists for tooling or a PR comment
verbatra diff --json

# also list the source keys your code no longer names
verbatra diff --unused

FlagsCopy Anchor Link

Also takes the global flags --cwd, --config and --json.

BehaviorCopy Anchor Link

Pending and orphaned keysCopy Anchor Link

Each locale lists four kinds of key:

A locale has pending changes when it has at least one missing or changed key. Orphaned keys never count as pending, because a default run leaves them in place; only verbatra translate --prune removes them. Where verbatra check gives the counts, diff gives the key lists.

Unused source keysCopy Anchor Link

--unused answers a different question from orphaned: which keys in the source locale file does your application no longer name? It scans the roots of the extract block with the reader verbatra extract uses and lists every source key no static reference names. The two lists are never merged. The scan stays read-only: nothing is removed, and no API key is read. Deleting a key is your call.

The scan models the i18next runtime. These count as a reference:

• a t(...), $t(...) or <object>.t(...) call anywhere under the roots, also through an alias such as const { t: translate } = useTranslation(), const tr = i18n.t, t.bind(i18n) or i18n.getFixedT(...);
• a static keyPrefix or third getFixedT argument, which also covers the prefixed form of every static key in that file, and a static i18nKey on Trans or in an object;
• a namespace-qualified key (common:nav.home covers nav.home too), a natural-language key, and every entry of a static key array;
• a plural or context variant of a referenced key (t("items", { count }) covers items_one and items_other), and every key under a referenced parent.

Keys are compared in the catalog format's own encoding, so a flat dotted JSON key, a gettext plural or msgctxt entry, and an Android <plurals> entry all match the key your code names. A template literal with a static head, such as t(`nav.${page}`), lists the keys under nav. as possiblyDynamic, apart from unused, and never fails the run.

The report carries a status: complete (every reachable key was bounded, so unused is trustworthy), unreliable (a listed key may still be in use; unreliableBecause names each reason with its count and sites) or not-run (nothing is listed; reason says why):

The recognised translate sources are useTranslation(...) destructured into a local, not exported binding with static arguments; a local i18n.getFixedT(...) with static arguments; a direct call on a member t (i18n.t("key"), this.props.t("key")) and its local alias; <Translation>{(t) => ...}</Translation>; withTranslation("ns")(Component) with props.t(...); and import { t } from "i18next". Any variable or member named t or $t is judged, so an unrelated frame.t + 1 can make a report unreliable. In .tsx, .jsx and .js files, JSX text and quoted attribute values are read as markup, never as code.

Each listed key shows its decoded spelling (a gettext msgctxt entry as menu|Open); --json also carries the catalogKey as the adapter spells it. A key used only outside the scanned source (a server template, a CMS) belongs in extract.unused.ignore: a pattern matches the decoded key, and a matched key is listed under ignored, never dropped.

Protected keysCopy Anchor Link

Missing and changed keys that translate would leave for a person (a person wrote, imported or changed the value outside verbatra, or the key matches pinnedKeys) are listed again under protected; see Protecting human translations. They stay in add and re-translate, since they are still pending. When verbatra.provenance.json is corrupt or from a newer verbatra, only pinned keys are listed.

JSON outputCopy Anchor Link

Schema: diff-envelope.json validates the whole envelope; Schemas lists the others.

--json prints one envelope whose result is a DiffSummary. hasPendingChanges is true exactly when the command exits 1 for pending keys:

interface DiffSummary {
  hasPendingChanges: boolean;
  locales: LocaleDiff[];
  unused?: UnusedKeysReport;   // only with --unused
}

interface LocaleDiff {
  locale: string;
  missing: string[];           // would be added
  changed: string[];           // would be re-translated
  orphaned: string[];          // reported only
  emptySource?: string[];      // source value empty: never pending
  hasPendingChanges: boolean;  // missing.length > 0 || changed.length > 0
  changedOrigins?: Record<string, KeyOrigin>; // absent when the provenance file is unreadable
  protected?: string[];        // pending keys translate would leave alone
}

Terminal feedbackCopy Anchor Link

diff shows one line while it works (with a running file count when --unused scans the source) and suggests the next command:

verbatra: diffing and scanning the source... done (0.8s)
next: verbatra translate (send the pending keys to your provider)

When every pending key is protected, it suggests verbatra studio instead; under provider: { id: "none" } it suggests verbatra export. These lines go to stderr, and --quiet drops them. See Terminal output.

Exit codesCopy Anchor Link

Orphaned, possibly dynamic and ignored keys, and an unreliable or not-run report, never cause 1 on their own. See the exit-code contract.

RelatedCopy Anchor Link

• verbatra check gives the per-locale counts behind these lists.
• verbatra translate applies the pending changes; --prune removes orphaned keys.
• The config file documents the extract block and unused.ignore.
• CI and exit codes shows diff in a pipeline.