verbatra diff

Liste pro Ziel-Locale die genauen ausstehenden Keys: die, die ein Lauf hinzufügen würde, die, die er neu übersetzen würde, und die inzwischen verwaisten. diff führt dasselbe Lesen und Diffen aus wie verbatra translate und hört dann auf: kein Provider-Aufruf, keine geschriebene Datei, keine Aktualisierung der Lock-Datei, kein API-Key nötig.

SynopsisLink zu diesem Abschnitt kopieren

verbatra diff [flags]

BeispieleLink zu diesem Abschnitt kopieren

# die ausstehenden Keys pro Locale auflisten (Exit 1, wenn welche ausstehen)
verbatra diff

# nur die deutsche und die französische Locale
verbatra diff --locales de,fr

# maschinenlesbare Key-Listen für Tools oder einen PR-Kommentar
verbatra diff --json

# zusätzlich die Quell-Keys auflisten, die dein Code nicht mehr nennt
verbatra diff --unused

FlagsLink zu diesem Abschnitt kopieren

Nimmt außerdem die globalen Flags --cwd, --config und --json.

VerhaltenLink zu diesem Abschnitt kopieren

Ausstehende und verwaiste KeysLink zu diesem Abschnitt kopieren

Jede Locale listet vier Arten von Keys:

Eine Locale hat ausstehende Änderungen, sobald sie mindestens einen fehlenden oder geänderten Key hat. Verwaiste Keys zählen nie als ausstehend, weil ein Standardlauf sie stehen lässt; nur verbatra translate --prune entfernt sie. verbatra check liefert die Zähler, diff die Key-Listen.

Ungenutzte Quell-KeysLink zu diesem Abschnitt kopieren

--unused beantwortet eine andere Frage als orphaned: Welche Keys in deiner Quell-Locale-Datei nennt deine Anwendung nicht mehr? Es scannt die roots des extract-Blocks mit dem Leser, den verbatra extract nutzt, und listet jeden Quell-Key, den keine statische Referenz nennt. Die beiden Listen werden nie zusammengeführt. Der Scan bleibt nur lesend: Nichts wird entfernt, und kein API-Key wird gelesen. Ob du einen Key löschst, entscheidest du.

Der Scan bildet die i18next-Laufzeit nach. Folgendes zählt als Referenz:

• ein Aufruf t(...), $t(...) oder <object>.t(...) irgendwo unter den Roots, auch über einen Alias wie const { t: translate } = useTranslation(), const tr = i18n.t, t.bind(i18n) oder i18n.getFixedT(...);
• ein statischer keyPrefix oder ein statisches drittes getFixedT-Argument, das auch die Form mit Präfix jedes statischen Keys dieser Datei abdeckt, und ein statischer i18nKey an Trans oder in einem Objekt;
• ein Key mit Namespace (common:nav.home deckt auch nav.home ab), ein Key in natürlicher Sprache und jeder Eintrag eines statischen Key-Arrays;
• eine Plural- oder Kontext-Variante eines referenzierten Keys (t("items", { count }) deckt items_one und items_other ab) und jeder Key unter einem referenzierten Eltern-Key.

Keys werden in der eigenen Kodierung des Katalogformats verglichen, sodass ein flacher JSON-Key mit Punkt, ein gettext-Plural oder msgctxt-Eintrag und ein Android-<plurals>-Eintrag alle zu dem Key passen, den dein Code nennt. Ein Template-Literal mit statischem Anfang wie t(`nav.${page}`) listet die Keys unter nav. getrennt von unused als possiblyDynamic und lässt den Lauf nie fehlschlagen.

Der Bericht trägt einen status: complete (jeder erreichbare Key wurde eingegrenzt, unused ist also verlässlich), unreliable (ein gelisteter Key kann noch genutzt werden; unreliableBecause nennt jeden Grund mit Anzahl und Fundstellen) oder not-run (nichts wird gelistet; reason sagt, warum):

Als Quellen von Übersetzungsfunktionen erkennt der Scan: useTranslation(...), destrukturiert in eine lokale, nicht exportierte Bindung mit statischen Argumenten; ein lokales i18n.getFixedT(...) mit statischen Argumenten; einen direkten Aufruf an einem Member t (i18n.t("key"), this.props.t("key")) und seinen lokalen Alias; <Translation>{(t) => ...}</Translation>; withTranslation("ns")(Component) mit props.t(...); und import { t } from "i18next". Jede Variable und jeder Member namens t oder $t wird geprüft, ein unbeteiligtes frame.t + 1 kann den Bericht also unzuverlässig machen. In .tsx-, .jsx- und .js-Dateien werden JSX-Text und Attributwerte in Anführungszeichen als Markup gelesen, nie als Code.

Jeder gelistete Key zeigt seine dekodierte Schreibweise (einen gettext-msgctxt-Eintrag als menu|Open); --json trägt zusätzlich den catalogKey so, wie der Adapter ihn schreibt. Ein Key, der nur außerhalb des gescannten Codes genutzt wird (ein Server-Template, ein CMS), gehört in extract.unused.ignore: Ein Muster passt auf den dekodierten Key, und ein passender Key erscheint unter ignored, er fällt nie stillschweigend weg.

Geschützte KeysLink zu diesem Abschnitt kopieren

Fehlende und geänderte Keys, die translate einer Person überlassen würde (eine Person hat den Wert außerhalb von verbatra geschrieben, importiert oder geändert, oder der Key passt auf pinnedKeys), erscheinen zusätzlich unter protected; siehe Menschliche Übersetzungen schützen. Sie bleiben auch in add und re-translate, weil sie weiter ausstehen. Ist verbatra.provenance.json beschädigt oder stammt von einer neueren verbatra-Version, werden nur angeheftete Keys gelistet.

JSON-AusgabeLink zu diesem Abschnitt kopieren

Schema: diff-envelope.json validiert den ganzen Envelope; Schemas listet die übrigen auf.

--json gibt einen Envelope aus, dessen result eine DiffSummary ist. hasPendingChanges ist genau dann wahr, wenn der Befehl wegen ausstehender Keys mit 1 endet:

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

interface LocaleDiff {
  locale: string;
  missing: string[];           // würde hinzugefügt
  changed: string[];           // würde neu übersetzt
  orphaned: string[];          // wird nur gemeldet
  emptySource?: string[];      // Quellwert leer: nie ausstehend
  hasPendingChanges: boolean;  // missing.length > 0 || changed.length > 0
  changedOrigins?: Record<string, KeyOrigin>; // fehlt, wenn die Provenienz-Datei unlesbar ist
  protected?: string[];        // ausstehende Keys, die translate stehen lässt
}

Rückmeldung im TerminalLink zu diesem Abschnitt kopieren

diff zeigt eine Zeile, während es arbeitet (mit laufender Dateizahl, wenn --unused den Code scannt), und schlägt den nächsten Befehl vor:

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

Sind alle ausstehenden Keys geschützt, schlägt es stattdessen verbatra studio vor; unter provider: { id: "none" } schlägt es verbatra export vor. Diese Zeilen gehen auf stderr, und --quiet blendet sie aus. Siehe Terminalausgabe.

Exit-CodesLink zu diesem Abschnitt kopieren

Verwaiste, möglicherweise dynamische und ignorierte Keys sowie ein Bericht mit unreliable oder not-run führen nie allein zu 1. Siehe den Exit-Code-Vertrag.

Siehe auchLink zu diesem Abschnitt kopieren

• verbatra check liefert die Zähler pro Locale hinter diesen Listen.
• verbatra translate übernimmt die ausstehenden Änderungen; --prune entfernt verwaiste Keys.
• Die Konfigurationsdatei beschreibt den extract-Block und unused.ignore.
• CI und Exit-Codes zeigt diff in einer Pipeline.