verbatra diff

Liste, par locale cible, les clés exactes en attente : celles qu'une exécution ajouterait, celles qu'elle retraduirait et celles désormais orphelines. diff fait la même lecture et la même comparaison que verbatra translate, puis s'arrête : aucun appel de fournisseur, aucun fichier écrit, aucune mise à jour du fichier de verrouillage, aucune clé d'API requise.

SynopsisCopier le lien vers cette section

verbatra diff [flags]

ExemplesCopier le lien vers cette section

# liste les clés en attente par locale (sortie 1 s'il y en a)
verbatra diff

# seulement les locales allemande et française
verbatra diff --locales de,fr

# listes de clés lisibles par une machine pour un outil ou un commentaire de PR
verbatra diff --json

# liste aussi les clés source que ton code ne nomme plus
verbatra diff --unused

OptionsCopier le lien vers cette section

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

ComportementCopier le lien vers cette section

Clés en attente et orphelinesCopier le lien vers cette section

Chaque locale liste quatre sortes de clés :

Une locale a des changements en attente dès qu'elle a au moins une clé manquante ou modifiée. Les clés orphelines ne comptent jamais comme en attente, car une exécution par défaut les laisse en place ; seul verbatra translate --prune les supprime. verbatra check donne les décomptes, diff donne les listes de clés.

Clés source inutiliséesCopier le lien vers cette section

--unused répond à une autre question que orphaned : quelles clés de ton fichier de locale source ton application ne nomme-t-elle plus ? Il analyse les roots du bloc extract avec le lecteur de verbatra extract et liste chaque clé source qu'aucune référence statique ne nomme. Les deux listes ne sont jamais fusionnées. L'analyse ne fait que lire : rien n'est supprimé, et aucune clé d'API n'est lue. Supprimer une clé, c'est ta décision.

L'analyse modélise le runtime i18next. Ceci compte comme une référence :

• un appel t(...), $t(...) ou <object>.t(...) n'importe où sous les racines, aussi via un alias comme const { t: translate } = useTranslation(), const tr = i18n.t, t.bind(i18n) ou i18n.getFixedT(...) ;
• un keyPrefix statique ou un troisième argument statique de getFixedT, qui couvre aussi la forme préfixée de chaque clé statique de ce fichier, et un i18nKey statique sur Trans ou dans un objet ;
• une clé avec namespace (common:nav.home couvre aussi nav.home), une clé en langage naturel et chaque entrée d'un tableau statique de clés ;
• une variante de pluriel ou de contexte d'une clé référencée (t("items", { count }) couvre items_one et items_other) et chaque clé sous un parent référencé.

Les clés sont comparées dans l'encodage propre au format du catalogue, donc une clé JSON plate avec des points, un pluriel ou une entrée msgctxt gettext et une entrée <plurals> Android correspondent toutes à la clé que ton code nomme. Un template literal à tête statique, comme t(`nav.${page}`), liste les clés sous nav. comme possiblyDynamic, à part de unused, et ne fait jamais échouer l'exécution.

Le rapport porte un status : complete (chaque clé atteignable a été bornée, donc unused est fiable), unreliable (une clé listée peut encore servir ; unreliableBecause nomme chaque raison avec son nombre et ses emplacements) ou not-run (rien n'est listé ; reason dit pourquoi) :

Les sources de fonctions de traduction reconnues sont : useTranslation(...) déstructuré dans une liaison locale non exportée avec des arguments statiques ; un i18n.getFixedT(...) local avec des arguments statiques ; un appel direct sur un membre t (i18n.t("key"), this.props.t("key")) et son alias local ; <Translation>{(t) => ...}</Translation> ; withTranslation("ns")(Component) avec props.t(...) ; et import { t } from "i18next". Toute variable ou tout membre nommé t ou $t est jugé, donc un frame.t + 1 sans rapport peut rendre le rapport non fiable. Dans les fichiers .tsx, .jsx et .js, le texte JSX et les valeurs d'attribut entre guillemets sont lus comme du balisage, jamais comme du code.

Chaque clé listée montre sa forme décodée (une entrée msgctxt gettext comme menu|Open) ; --json porte aussi la catalogKey telle que l'adaptateur l'écrit. Une clé utilisée seulement hors du code analysé (un template serveur, un CMS) va dans extract.unused.ignore : un motif correspond à la clé décodée, et une clé qui correspond est listée sous ignored, jamais écartée en silence.

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

Les clés manquantes et modifiées que translate laisserait à une personne (une personne a écrit, importé ou modifié la valeur hors de verbatra, ou la clé correspond à pinnedKeys) sont listées en plus sous protected ; voir Protéger les traductions humaines. Elles restent sous add et re-translate, puisqu'elles sont toujours en attente. Si verbatra.provenance.json est corrompu ou vient d'un verbatra plus récent, seules les clés épinglées sont listées.

Sortie JSONCopier le lien vers cette section

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

--json affiche une enveloppe dont le result est un DiffSummary. hasPendingChanges est vrai exactement quand la commande sort avec 1 pour des clés en attente :

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

interface LocaleDiff {
  locale: string;
  missing: string[];           // serait ajoutée
  changed: string[];           // serait retraduite
  orphaned: string[];          // seulement signalée
  emptySource?: string[];      // valeur source vide : jamais en attente
  hasPendingChanges: boolean;  // missing.length > 0 || changed.length > 0
  changedOrigins?: Record<string, KeyOrigin>; // absent si le fichier de provenance est illisible
  protected?: string[];        // clés en attente que translate laisse intactes
}

Retour dans le terminalCopier le lien vers cette section

diff affiche une ligne pendant qu'il travaille (avec un décompte des fichiers quand --unused analyse le code) et suggère la commande suivante :

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

Quand toutes les clés en attente sont protégées, il suggère plutôt verbatra studio ; avec provider: { id: "none" }, il suggère verbatra export. Ces lignes vont sur stderr, et --quiet les supprime. Consulte Sortie dans le terminal.

Codes de sortieCopier le lien vers cette section

Les clés orphelines, possiblement dynamiques et ignorées, ainsi qu'un rapport unreliable ou not-run, ne produisent jamais 1 à eux seuls. Consulte le contrat des codes de sortie.

Voir aussiCopier le lien vers cette section

• verbatra check donne les décomptes par locale derrière ces listes.
• verbatra translate applique les changements en attente ; --prune supprime les clés orphelines.
• Le fichier de configuration documente le bloc extract et unused.ignore.
• CI et codes de sortie montre diff dans un pipeline.