CLI-Referenz

svelte-dialect bringt ein einziges Programm mit drei Befehlen mit: typegen, check und migrate. Es gibt keine Konfigurationsdatei, alle Einstellungen sind Flags.

Aufruf #

Ohne Argumente oder mit --help als einzigem Argument gibt das Programm die Befehlsliste aus und endet mit 0. Ein unbekannter Befehl gibt dieselbe Liste aus und endet mit 1. Auch ein unbekanntes Flag, ein nicht lesbares Message-Verzeichnis und ungültiges JSON sind Fehler: Der Befehl schreibt eine Zeile nach stderr und endet mit 1.

npx svelte-dialect <command> [flags]

typegen #

Schreibt eine .d.ts-Datei mit der MessageKey-Union und den MessageParams-Formen. Wie du sie nutzt, zeigt Typisierte Schlüssel.

$ npx svelte-dialect typegen --messages src/lib/messages --out src/lib/i18n-keys.d.ts
svelte-dialect typegen: 3 keys → src/lib/i18n-keys.d.ts

Flags #

Flag	Standard	Beschreibung
--messages <dir>	src/lib/messages	Das Message-Verzeichnis im Aufbau <locale>/<namespace>.json. Du kannst das Flag wiederholen, um mehrere Verzeichnisse zusammenzuführen, etwa einen gebündelten und einen lazy Baum. Wird ignoriert, wenn --from-json gesetzt ist.
--from-json <file>	—	Liest einen JSON-Dump der Form {locale: {namespace: {…}}} statt eines Verzeichnisses. Gedacht für Kataloge, die in einer Datenbank liegen.
--out <file>	src/lib/i18n-keys.d.ts	Die Datei, die geschrieben wird. Ihr Verzeichnis muss schon existieren. Eine vorhandene Datei wird überschrieben.

Exit-Codes #

Code	Wann
0	Die Datei wurde geschrieben.
1	Unbekanntes Flag, ein --messages-Verzeichnis oder eine --from-json-Datei, die sich nicht lesen lässt, ungültiges JSON oder ein --out-Pfad, in den nicht geschrieben werden kann.

check #

Vergleicht die t('ns:key')-Aufrufe in deinem Quellcode mit den Message-Dateien, damit ein umbenannter oder gelöschter Schlüssel in der CI scheitert, statt in Produktion als Rohtext zu erscheinen.

$ npx svelte-dialect check --unused
Missing:
  home:footer — missing in en, ru
  home:greeting — missing in ru
Unused:
  home:old
3 keys used, 2 missing, 1 unused
$ echo $?
1

Der Scan ist eine Textsuche, kein Parser. Er sieht nur String-Literale: Ein Schlüssel, der aus einer Variablen oder einem Template-Literal mit ${…} zusammengesetzt ist, wird übersprungen, sowohl in der Liste der fehlenden Schlüssel als auch bei --unused. Ein Aufruf loadTranslations('ns') wird als ns:* geprüft und schlägt fehl, wenn eine Locale diesen Namespace nicht hat.

Flags #

Flag	Standard	Beschreibung
--messages <dir>	src/lib/messages	Das Message-Verzeichnis im Aufbau <locale>/<namespace>.json. Wiederholbar.
--src <dir>	src	Das Verzeichnis, das rekursiv nach .ts-, .js- und .svelte-Dateien durchsucht wird. node_modules und Verzeichnisse, deren Name mit einem Punkt beginnt, werden übersprungen.
--unused	false	Listet zusätzlich die Schlüssel in den Message-Dateien auf, auf die kein Code verweist. Der Exit-Code ändert sich dadurch nicht.

Exit-Codes #

Code	Wann
0	Jeder Schlüssel, den der Code verwendet, existiert in jeder Locale.
1	Ein verwendeter Schlüssel fehlt in mindestens einer Locale, unter --messages wurde trotz verwendeter Schlüssel keine Locale gefunden, oder der Befehl ist so fehlgeschlagen, wie unter „Aufruf“ beschrieben.

migrate #

Wandelt i18next- und ICU-MessageFormat-JSON-Dateien direkt an Ort und Stelle in MF2 um. Die Umstiegsanleitung begleitet eine Migration von Anfang bis Ende.

$ npx svelte-dialect migrate --dry-run --strict
svelte-dialect migrate: en/common.json — 3 converted, 0 unchanged, 1 warnings
  …
svelte-dialect migrate: 3 messages would change, 1 warnings (dry run, nothing written)
svelte-dialect migrate: --strict: 1 warnings, exiting with 1

Ergebnisse und die Zusammenfassung gehen nach stdout, Warnungen nach stderr. Eine Datei wird nur dann neu geschrieben, wenn sich mindestens eine ihrer Messages geändert hat, als JSON mit Tab-Einrückung. Ein zweiter Lauf ändert nichts.

Flags #

Flag	Standard	Beschreibung
--messages <dir>	src/lib/messages	Das Message-Verzeichnis, das umgewandelt wird, im Aufbau <locale>/<namespace>.json. Wiederholbar: Jedes Verzeichnis wird für sich migriert.
--dry-run	false	Gibt jede Änderung als Vorher-Nachher-Paar aus und schreibt nichts.
--strict	false	Endet mit 1, sobald eine Warnung ausgegeben wurde. Die Dateien werden trotzdem geschrieben; das Flag ändert nur den Exit-Code, für die CI.

Exit-Codes #

Code	Wann
0	Der Lauf ist durchgelaufen. Warnungen allein lassen ihn nicht scheitern.
1	--strict wurde gesetzt und mindestens eine Warnung ausgegeben.
1	Das Verzeichnis enthält nur flache <locale>.json-Dateien, es gab also nichts zu migrieren. Verschiebe jede nach <locale>/<namespace>.json.
1	Unbekanntes Flag, ein Message-Verzeichnis, das sich nicht lesen lässt, oder ungültiges JSON.