verbatra check

Melde pro Ziel-Locale, wie viele Keys fehlen, veraltet oder aktuell sind, und beende den Lauf mit einem Code, auf den ein CI-Schritt verzweigen kann. check liest und difft wie verbatra translate vor dem Provider-Aufruf und hört dann auf: kein Provider-Aufruf, keine geschriebene Datei, kein API-Key nötig.

SynopsisLink zu diesem Abschnitt kopieren

verbatra check [flags]

BeispieleLink zu diesem Abschnitt kopieren

# den Build scheitern lassen, wenn Übersetzungen abgedriftet sind
verbatra check

# maschinenlesbarer Status für zwei Locales
verbatra check --locales de,fr --json

# zusätzlich Quelltexte listen, die unterschiedlich übersetzt sind
verbatra check --consistency

# bei kaputten Platzhaltern, Markup und ICU scheitern, und auch bei Warnungen
verbatra check --qa --strict

# scheitern, solange maschinelle Übersetzungen auf Freigabe warten
verbatra check --require-reviewed

# bei E-Mails, API-Keys oder Kartennummern in der Quelle fehlschlagen
verbatra check --sensitive

# nur die eine Datei prüfen, die ein Editor oder Agent gerade geändert hat
verbatra check --file locales/de.json --json

FlagsLink zu diesem Abschnitt kopieren

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

Ein Key fehlt, wenn die Quelle ihn hat und das Ziel nicht, und er ist veraltet, wenn sich sein Quelltext seit der letzten Übersetzung geändert hat. Eine Locale ist synchron, wenn sie keins von beidem hat. Die Key-Listen hinter den Zahlen liefert verbatra diff.

VerhaltenLink zu diesem Abschnitt kopieren

KonsistenzberichtLink zu diesem Abschnitt kopieren

--consistency listet pro Ziel-Locale jeden Quelltext, den zwei oder mehr Keys unterschiedlich übersetzen: die Quelle, jede Übersetzung und die Keys, die sie tragen. Er ändert nie den Exit-Code, einen Wert oder die Review-Warteschlange. Die Vergleichsregeln:

• Werte werden nach Unicode-NFC-Normalisierung verglichen, \r\n wird zu \n, äußere Leerzeichen fallen weg. Leerzeichen im Inneren und Groß- und Kleinschreibung zählen.
• Nur aktuelle Keys werden verglichen, und eine Übersetzung gleich ihrer Quelle bleibt EQUALS_SOURCE überlassen.
• Keys mit unterschiedlicher Beschreibung, Bedeutung, Plural-Kennzeichnung oder gettext-msgctxt werden nie gruppiert.
• Pluralformen werden pro Form verglichen: Die Formen one und other eines Keys werden nie miteinander gruppiert.

Bekannte Fehlalarme: i18next-Kontextvarianten (invite_male, invite_female), gettext-Einträge mit #, fuzzy, pluralartige Keys in einem Format ohne Plurale (yaml, ngx-translate-json, xliff, properties, ini, resx) und die Pluralformen eines custom:-Formats. Gib solchen Keys eine abweichende Beschreibung oder Bedeutung oder ignoriere den Befund. Mit --json trägt jede Locale inconsistencies: { source, context?, description?, meaning?, isPlural, pluralForm?, translations: [{ value, keys }] }[].

Geschützte KeysLink zu diesem Abschnitt kopieren

Ein veralteter Key, den eine Person geschrieben, importiert oder außerhalb von verbatra geändert hat, oder ein Key, der auf pinnedKeys passt, bleibt bei translate für eine Person liegen (siehe Menschliche Übersetzungen schützen). check zählt ihn trotzdem und zeigt den geschützten Anteil, etwa 2 stale (1 protected). --json liefert ihn als protected pro Locale; ist verbatra.provenance.json unlesbar, zählen nur gepinnte Keys.

PluralkategorienLink zu diesem Abschnitt kopieren

Jedes check listet die Plurale, denen eine CLDR-Pluralkategorie ihrer Zielsprache fehlt, etwa ein polnisches Android-<plurals> mit nur one und other:

plural categories (warning: exit 1 only under --qa --strict)
  pl: 2 plurals missing CLDR categories
    cart {count} plural: missing few, many
    files: missing few, many

Die Kategorien stammen aus den CLDR-Regeln von Node.js (siehe Sprachunterstützung). Geprüfte Formate:

other ist immer Pflicht. Ein exakter Zweig wie =1 ersetzt nie eine Kategorie, select-Zweige werden nie geprüft, und geprüft wird nur ein Plural, von dem das Ziel mindestens eine Form hat. Es ist eine Warnung: Ein einfaches check behält seinen Exit-Code, --qa --strict schlägt daran fehl. verbatra doctor meldet dieselben Plurale. Mit --json trägt jede Locale incompletePlurals, nach Key sortiert:

interface IncompletePlural {
  code: "PLURAL_CATEGORIES_INCOMPLETE";
  key: string;              // Basis-Key oder der Key der ICU-Nachricht
  argument?: string;        // das Argument des ICU-Plurals, etwa count
  ruleType: "cardinal" | "ordinal";
  missing: ("zero" | "one" | "two" | "few" | "many" | "other")[]; // in CLDR-Reihenfolge
}

QualitätsprüfungLink zu diesem Abschnitt kopieren

--qa wendet die Prüfungen, die ein Übersetzungslauf auf Provider-Ausgaben anwendet, auf die Werte an, die schon in deinen Locale-Dateien stehen, veraltet oder nicht, samt zusätzlicher Pluralformen, die die Zielsprache braucht. Befunde gibt es in zwei Schweregraden:

• error: Der Wert fällt durch das Integritäts-Gate, mit placeholder, markup, icu, degenerate oder empty. Die Details listen entfernte Tokens als -{{name}} und hinzugefügte als +{{nom}}.
• warning: Der Wert trägt einen Review-Grund, der sich aus dem Wert, seiner Quelle und deiner Konfiguration (Glossar, maxLength) ergibt, also keinen, der vom Provider oder vom Cache abhängt; bei FOREIGN_PLACEHOLDER_CHANGED nennen die details des Befunds jedes verlorene oder veränderte Token, etwa -{name}. Ein Wert mit Fehler bekommt keine Warnungen.

qa: 1 error, 1 warning
  de: 1 error, 1 warning in 42 values checked
    greeting: error placeholder (-{{name}}, +{{nme}})
    title: warning EQUALS_SOURCE

Verwaiste und fehlende Keys werden übersprungen, und Quell-Keys, die kein gültiges ICU sind, stehen einmal unter invalidSourceKeys. Geschützte, gepinnte und abgelehnte Werte werden wie alle anderen geprüft. Mit --json hält result.qa die Summen und jede Locale ihr eigenes qa:

interface CheckQaSummary { errors: number; warnings: number; invalidSourceKeys: string[] }
interface LocaleQaReport { checked: number; errors: number; warnings: number; findings: QaFinding[] }
type QaFinding =
  | { key: string; severity: "error"; reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty"; details?: string[] }
  | { key: string; severity: "warning"; reason: string; details?: string[] }; // einer der Review-Gründe oben

Freigegebene Übersetzungen verlangenLink zu diesem Abschnitt kopieren

--require-reviewed schlägt mit Exit 1 fehl, solange ein Wert mit Herkunft machine, memory, fuzzy oder agent in der committeten verbatra.provenance.json nicht freigegeben ist; dort speichern Studio und die MCP-Tools ihre Entscheidungen. Eine Freigabe von vor der Änderung des Quelltexts oder des Werts zählt nicht.

review: failed [REVIEW_REQUIRED] 2 machine-written translations not approved
  de: 2 unreviewed: checkout.title, checkout.total

Mit --json ist result.review gleich { reviewed, unreviewed, code? }, wobei code REVIEW_REQUIRED ist oder REVIEW_STATE_UNREADABLE, wenn die Provenance-Datei beschädigt ist oder von einem neueren verbatra stammt (das Gate schlägt dann fehl). Jede Locale trägt review.unreviewed, die Keys in Quellreihenfolge.

Sensible InhalteLink zu diesem Abschnitt kopieren

--sensitive führt die Prüfung des Schutzes für sensible Inhalte über jeden Quell-Key (Key-Name, Wert, Beschreibung und Bedeutung) und das Glossar jeder geprüften Locale aus, mit den Detektoren, Mustern und der Allow-Liste aus sensitiveData (ohne Block den Standard-Detektoren), bei jedem mode und Provider, auch none: Werte verlassen den Rechner trotzdem über Export-, XLIFF- und TMX-Übergaben. Es meldet Keys und Detektoren, nie gefundenen Text außerhalb eines Key-Namens, und endet bei jedem Fund mit Exit 1.

Der Detektor email überspringt reservierte Beispiel-Domains, teste also mit einer realistisch wirkenden Adresse.

sensitive: 1 key and 0 glossary terms hold content that looks sensitive
  support.contact: email in value

Mit --json ist result.sensitive gleich { findings, glossaryTerms }, jeder Fund { key, fields, detectors }; detectors kann pattern-timeout-<n> enthalten.

Eine DateiLink zu diesem Abschnitt kopieren

--file <path> prüft eine einzelne Locale-Datei, gedacht für Editor- und Agent-Hooks nach einer Änderung. Es liest diese Datei, verbatra.limits.json neu (wenn unbrauchbar, mit einem Hinweis auf stderr ignoriert, wie unter --qa; doctor nennt das Problem) und, bei einer Ziel-Locale, die Quelldatei, sonst nichts. Der Pfad wird gegen --cwd aufgelöst und über files.pattern einer Locale zugeordnet.

• Eine Datei, die sich nicht parsen lässt, ergibt einen syntax-Fehler mit dem Code des Adapters (INVALID_JSON, INVALID_YAML, ...) und Zeile und Spalte, wenn der Parser eine Position meldet.
• Eine Zieldatei wird wie bei --qa geprüft, Pluralkategorien eingeschlossen, eine Quelldatei nur auf Syntax. Ein apple-xcstrings-Katalog wird für jede Ziel-Locale geprüft.
• Ein Pfad, der keine konfigurierte Locale-Datei ist, schlägt mit NOT_A_LOCALE_FILE und Exit 2 fehl.

Mit --json verwendet result den Bericht von --qa wieder, sodass ein Hook nur eine Form parst:

interface CheckFileSummary {
  file: string;                          // relativ zur Projektwurzel
  role: "source" | "target" | "catalogue";
  locales: {
    locale: string;
    incompletePlurals: IncompletePlural[];
    qa: { checked: number; errors: number; warnings: number; findings: (QaFinding | QaSyntaxFinding)[] };
  }[];
  qa: CheckQaSummary;
}
interface QaSyntaxFinding {
  severity: "error"; reason: "syntax"; code: string; message: string;
  line?: number; column?: number;       // wenn der Parser eine Position meldet, ab 1 gezählt
}

Fehlende und veraltete Keys gehören nicht zur Dateiprüfung.

JSON-AusgabeLink zu diesem Abschnitt kopieren

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

--json gibt einen Umschlag aus, dessen result das Statusdokument ist. Ohne --qa, --require-reviewed und --sensitive ist inSync genau dann wahr, wenn der Befehl mit 0 endet:

interface CheckSummary {
  inSync: boolean;
  locales: LocaleCheckSummary[];
  qa?: CheckQaSummary;          // nur mit --qa
  review?: CheckReviewSummary;  // nur mit --require-reviewed
  sensitive?: CheckSensitiveSummary; // nur mit --sensitive
}

interface LocaleCheckSummary {
  locale: string;
  missing: number;              // in der Quelle, fehlt im Ziel
  stale: number;                // Quelle seit der letzten Übersetzung geändert
  upToDate: number;
  inSync: boolean;              // missing === 0 && stale === 0
  emptySource?: number;         // Quellwert leer: nie fehlend oder veraltet
  provenance?: ProvenanceSummary; // Zählungen nach Herkunft und Review-Status
  protected?: number;
  incompletePlurals?: IncompletePlural[];
  inconsistencies?: InconsistencyGroup[]; // nur mit --consistency
  qa?: LocaleQaReport;          // nur mit --qa
  review?: LocaleReviewReport;  // nur mit --require-reviewed
}

Ein Quell-Key, dessen Wert leer ist oder nur aus Leerraum besteht, etwa einer, den extract ohne Standardwert ergänzt hat, hat noch nichts zu übersetzen: Er wird in emptySource statt in missing oder stale gezählt, bringt eine Locale nie aus dem Takt, und die Terminalausgabe nennt die Zahl.

Rückmeldung im TerminalLink zu diesem Abschnitt kopieren

check zeigt auf stderr verbatra: checking the locales... done (0.1s), mit --file verbatra: checking locales/de.json.... --quiet lässt die Zeile weg. Siehe Terminalausgabe.

Exit-CodesLink zu diesem Abschnitt kopieren

Exit 1 heißt, dass das Ergebnis nicht sauber ist, nicht dass der Lauf gescheitert ist; der Bericht wird trotzdem ausgegeben. Bei einem Projekt, dessen Quelldatei noch fehlt, meldet verbatra doctor weiterhin. Den Vertrag findest du unter Exit-Codes.

Siehe auchLink zu diesem Abschnitt kopieren

• verbatra diff listet die genauen Keys hinter diesen Zahlen.
• CI und Exit-Codes zeigt check als Drift-Gate.
• Die Lock-Datei erklärt, wie Veraltung erkannt wird.