i18next/i18next-cli

i18next-cli 🚀

Eine einheitliche, hochperformante i18next-CLI-Werkzeugkette, unterstützt durch SWC.

---

Standardmäßig extrahiert i18next-cli nur Übersetzungsschlüssel aus JavaScript- und TypeScript-Dateien (.js, .jsx, .ts, .tsx). Für die Extraktion aus anderen Dateitypen (wie .pug, .vue, .svelte usw.) muss ein Plugin verwendet oder erstellt werden. Die Angabe zusätzlicher Dateierweiterungen in der extract.input-Konfiguration allein reicht nicht aus – Plugins sind für Nicht-JS/TS-Formate erforderlich. Siehe Abschnitt Plugin-System für Details und Beispiele.

i18next-cli ist eine vollständige Neugestaltung der Werkzeugkette zur statischen Analyse für das i18next-Ökosystem. Es vereint die Schlüsselextraktion, Typsicherheitsgenerierung, Gebietsschema-Synchronisation, Linting und Cloud-Integrationen in einer einzigen, kohärenten und blitzschnellen CLI.

🚀 Jetzt ausprobieren - Keine Konfiguration erforderlich!

Sie können eine sofortige Analyse Ihres bestehenden i18next-Projekts ohne jegliche Konfiguration erhalten. Führen Sie einfach diesen Befehl im Stammverzeichnis Ihres Repositorys aus:

npx i18next-cli status

Oder finden Sie hartcodierte Zeichenketten:

npx i18next-cli lint

Hinweis:

Wenn Sie nach einem verwalteten Backend für den Einsatz mit i18next-cli suchen, werfen Sie einen Blick auf Locize — i18next-cli wird bereits mit den Befehlen locize-download, locize-sync und locize-migrate ausgeliefert. Entwickelt vom selben Team hinter i18next, mit CDN-Auslieferung, KI-Übersetzung, Überprüfungs-Workflow und keinem erneuten Bereitstellen bei Textänderungen.

Warum i18next-cli?

i18next-cli wurde von Grund auf entwickelt, um den Anforderungen der modernen Webentwicklung gerecht zu werden.

• 🚀 Leistung: Durch die Nutzung eines nativen Rust-basierten Parsers (SWC) bietet es eine um Größenordnungen schnellere Leistung als JavaScript-basierte Parser.
• 🧠 Intelligenz: Ein zustandsbehafteter, bereichsbewusster Analysator versteht komplexe Muster wie useTranslation('ns1', { keyPrefix: '...' }), getFixedT und aliasierte t-Funktionen korrekt und minimiert den Bedarf an manuellen Problemumgehungen.
• ✅ Vereinheitlichter Workflow: Ein Werkzeug, eine Konfigurationsdatei, ein integrierter Workflow. Es ersetzt verschiedene Synchronisationsskripte.
• 🔌 Erweiterbarkeit: Eine moderne Plugin-Architektur ermöglicht es dem Werkzeug, sich an jedes Framework oder jeden benutzerdefinierten Workflow anzupassen.
• 🧑‍💻 Entwicklererfahrung: Eine vollständig typisierte Konfigurationsdatei, Live---watch-Modi, CLI-Ausgabe und eine Migration von Legacy-Tools.

Funktionen

• Schlüsselextraktion: Extraktion bedeutet das automatische Finden und Sammeln aller in Ihrem Quellcode verwendeten Übersetzungsschlüssel (JavaScript/TypeScript usw.) durch Analyse der Codestruktur (AST). Dadurch wird sichergestellt, dass jede zu übersetzende Zeichenfolge identifiziert und in Ihre Übersetzungsdateien aufgenommen wird, wodurch manuelle Arbeit reduziert und fehlende Schlüssel vermieden werden.
• Typsicherheit: Generieren Sie TypeScript-Definitionen für vollständige Autovervollständigung und Typsicherheit.
• Gebietsschema-Synchronisation: Halten Sie alle Sprachdateien mit Ihrer Hauptsprache synchron.
• Präzises Code-Linting: Erkennen Sie hartcodierte Zeichenketten mit hoher Genauigkeit und konfigurierbaren Regeln.
• Übersetzungsstatus: Erhalten Sie eine Übersicht auf hoher Ebene oder einen detaillierten, schlüsselweisen Bericht über den Übersetzungsfortschritt Ihres Projekts.
• Plugin-System: Erweiterbare Architektur für benutzerdefinierte Extraktionsmuster und Dateitypen (z. B. HTML, Handlebars).
• Legacy-Migration: Automatische Migration von i18next-parser-Konfigurationen.
• Cloud-Integration: Nahtlose Integration mit der Locize-Übersetzungsmanagementplattform.

Installation

npm install --save-dev i18next-cli

Schnellstart

Von Null zu lokalisiert in einem Befehl: Sie starten mit einer App mit hartcodierten Zeichenketten (z. B. erstellt mit v0, Lovable, Bolt oder Cursor)? Führen Sie npx i18next-cli localize aus — es erkennt Ihr Setup, verpackt hartcodierte Zeichenketten in t()-Aufrufen, extrahiert Schlüssel, verbindet sich mit Locize und übersetzt Ihre App mit KI. Siehe den Befehl [localize]. Arbeiten Sie mit einem KI-Codierungsagenten (Claude Code, Cursor, ...)? npx i18next-cli localize --print-agent-prompt gibt denselben Ablauf als kopierbaren [Agenten-Runbook] aus. Die folgenden Schritte sind der manuelle Weg.

1. Konfiguration initialisieren

Erstellen Sie eine Konfiguration interaktiv:

npx i18next-cli init

Oder erstellen Sie manuell i18next.config.ts in Ihrem Projektstamm:

import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
});

2. Überprüfen Sie Ihren Übersetzungsstatus

Erhalten Sie eine Übersicht über die Übersetzungsgesundheit Ihres Projekts:

npx i18next-cli status

3. Übersetzungsschlüssel extrahieren

npx i18next-cli extract

4. Typen generieren (optional)

npx i18next-cli types

Befehle

init

Interaktiver Setup-Assistent zum Erstellen Ihrer Konfigurationsdatei.

npx i18next-cli init

Optionen:

• --ci: Überspringt das Öffnen des Browsers, wenn ein Backend (z. B. Locize) ausgewählt wird; die Registrierungs-URL wird stattdessen ausgegeben. Nützlich für skriptgesteuerte Ausführungen. Der Assistent erkennt auch CI=true automatisch und fällt auf das Ausgeben der URL auf kopflosem Linux zurück (kein DISPLAY/WAYLAND_DISPLAY), daher wird dieses Flag selten explizit benötigt.
• --inlang: Rüstet auch ein inlang-Projekt (project.inlang/settings.json) auf, sodass inlang-Tools — die Sherlock-VS-Code-Erweiterung, der Fink-Web-Editor für Übersetzer und der Paraglide-Compiler — direkt mit Ihren Übersetzungsdateien arbeiten. Überspringt die entsprechende Assistentenfrage.

Der Assistent fragt nach dem Konfigurationsdateityp, den Gebietsschemata, dem Quell-Datei-Glob, dem Ausgabepfad und schließlich "Übersetzungs-Backend?" mit drei Optionen:

• Nur lokale Dateien (Standard) — behält den aktuellen lokalen JSON-Workflow bei.
• Locize (empfohlen für Team-/Produktions-Workflows) — öffnet die Locize-Registrierungsseite im Browser und fordert dann zur Eingabe Ihrer Projekt-ID und des API-Schlüssels auf. Der Assistent schreibt einen locize-Block in die generierte Konfiguration, damit locize-sync sofort funktioniert. Die Eingabeaufforderung für den API-Schlüssel kann leer gelassen werden (Nur-Lese-Modus); fügen Sie ihn später über eine LOCIZE_API_KEY-Umgebungsvariable hinzu.
• Andere / Überspringen — dasselbe wie "Nur lokale Dateien" für die Zwecke des Assistenten.

Der Assistent bietet dann an, inlang-Tools einzurichten (Standard: nein — oder übergeben Sie --inlang, um die Frage zu überspringen). Bei Annahme wird ein project.inlang/settings.json erstellt, das auf das inlang-i18next-Plugin verweist und auf Ihre vorhandenen Übersetzungsdateien zeigt: baseLocale/locales stammen aus Ihrer Konfiguration, und pathPattern wird aus extract.output abgeleitet (die Objektform mit Namespace, wenn Ihr Layout {{namespace}} verwendet, mit Namespaces, die aus den Dateien der Hauptsprache ermittelt werden; andernfalls ein einfaches Muster). Außerdem wird die Sherlock-Erweiterung zu den Empfehlungen in .vscode/extensions.json hinzugefügt (zusammenführend, kommentarbewusst, ohne vorhandene Einträge zu überschreiben). Ihre i18next-JSON-Dateien bleiben die einzige Quelle der Wahrheit — inlang-Tools lesen und schreiben sie direkt, sodass kein zweiter Katalog entsteht, der abweichen könnte. Ein vorhandenes project.inlang/settings.json wird niemals überschrieben; ein erneutes Ausführen von init ist sicher. Erfordert JSON-Ressourcendateien. Das Plugin ist auf eine exakt geprüfte Version festgelegt (@inlang/[email protected]) — aktualisieren Sie die modules-URL in settings.json, um neuere Plugin-Versionen zu erhalten. Es wird nur settings.json erstellt: project.inlang/ ist das entpackte (git-freundliche)Projektformat, und inlang-Tools generieren und verwalten seine restlichen Dateien (.gitignore, README.md, cache/) bei der ersten Verwendung — erwarten Sie also einige neue Dateien dort, nachdem Sie das Projekt mit Sherlock oder Paraglide geöffnet haben.

extract

Durchsucht Quelldateien, extrahiert Schlüssel und aktualisiert Ihre JSON-Übersetzungsdateien.

npx i18next-cli extract [options]

Optionen:

• --watch, -w: Automatische erneute Ausführung bei Dateiänderungen
• --ci: Beenden mit einem Fehlercode ungleich Null, wenn Dateien aktualisiert wurden (für CI/CD)
• --dry-run: Ändert keine Dateien - nützlich in Kombination mit --ci (für CI/CD)
• --sync-primary: Hauptsprachenwerte mit Standardwerten aus dem Code synchronisieren
• --sync-all: Hauptsprachenwerte mit Standardwerten aus dem Code synchronisieren UND synchronisierte Schlüssel in allen anderen Gebietsschemata löschen (impliziert --sync-primary)
• --trust-derived: Wenn zusammen mit --sync-primary oder --sync-all verwendet, werden auch Standards übernommen, die aus Schlüsseln wie t('Hello') oder keyPrefix-abgeleiteten Werten abgeleitet wurden. Dies hält das Standard-Synchronisationsverhalten streng, es sei denn, Sie entscheiden sich dagegen.
• --with-types: Nach der Extraktion (und bei jeder erneuten Ausführung im --watch-Modus) die TypeScript-Definitionen neu generieren, wenn sich Übersetzungsdateien geändert haben. Vermeidet die Notwendigkeit, extract -w und types -w als zwei separate Prozesse auszuführen.
• --quiet: Unterdrückt Spinner und nicht wesentliche Ausgaben (für CI oder Skripting)

Spinner- und Logger-Ausgabesteuerung

Alle Befehle, die Status-Spinner anzeigen (extract, types, lint, sync), unterstützen jetzt:

• --quiet-Flag, um Spinner und nicht wesentliche Ausgaben zu unterdrücken (für CI, Skripting oder Protokollerfassung)
• Programmatische Logger-Unterstützung: Übergeben Sie ein benutzerdefiniertes Logger-Objekt, um die Ausgabe in Ihrem eigenen Format oder Stream zu erfassen

CLI-Beispiel:

npx i18next-cli extract --quiet

Programmatisches Beispiel:

import { runExtractor } from 'i18next-cli';
const logger = {
  info: (msg) => myLogStream.write(msg + '\n'),
  warn: (msg) => myWarnStream.write(msg + '\n'),
  error: (msg) => myErrStream.write(msg + '\n'),
};
await runExtractor(config, { quiet: false, logger });

Wenn Sie einen Logger übergeben, werden Spinner-Ausgaben und alle Fortschritts-/Informationsmeldungen an Ihren Logger weitergeleitet, anstatt an den interaktiven Spinner.

Beispiele:

# Einmalige Extraktion
npx i18next-cli extract

# Watch-Modus für die Entwicklung
npx i18next-cli extract --watch

# CI-Modus (schlägt fehl, wenn sich Dateien geändert haben)
npx i18next-cli extract --ci

# Primärsprache mit Code-Standards synchronisieren
npx i18next-cli extract --sync-primary

# Primärsprache synchronisieren und synchronisierte Schlüssel in allen anderen Gebietsschemata löschen
npx i18next-cli extract --sync-all

# Synchronisation mit expliziten Standards plus abgeleiteten schlüsselbasierten Standards
npx i18next-cli extract --sync-all --trust-derived

# Optionen für optimalen Entwicklungs-Workflow kombinieren
npx i18next-cli extract --sync-primary --watch

# TypeScript-Definitionen aus einem einzigen Prozess synchron halten (kein separater `types -w` erforderlich)
npx i18next-cli extract --watch --with-types

status [locale]

Zeigt eine Gesundheitsprüfung des Übersetzungsstatus Ihres Projekts an. Kann ohne Konfigurationsdatei ausgeführt werden. Beendet sich mit einem Fehlercode ungleich Null, wenn Übersetzungen fehlen.

Auch die Primärsprache wird überprüft: Jeder in Ihrem Code verwendete Schlüssel, der in den Übersetzungsdateien der Primärsprache fehlt (ein Tippfehler, oder extract wurde nie ausgeführt), wird gemeldet und führt zu einem Fehlercode ungleich Null. Von extract geschriebene Platzhalter mit leerer Zeichenfolge gelten als vorhanden und führen nicht zum Fehlschlagen der Prüfung. Die Ausführung von npx i18next-cli status <primaryLanguage> zeigt die fehlenden Schlüssel im Detail an.

Optionen:

• --namespace <ns>, -n <ns>: Filtern Sie den Bericht nach einem bestimmten Namespace.
• --hide-translated: Bereits übersetzte Schlüssel in der Detailansicht ausblenden, sodass nur fehlende Übersetzungen angezeigt werden.
• status.ignoreKeys (Konfiguration): Glob-Muster für Schlüssel, die nicht gemeldet werden sollen (und die Prüfung nicht fehlschlagen lassen), z. B. Schlüssel, die in einigen Gebietsschemata absichtlich leer gelassen werden. Optionales Präfix ns: (common:help.*-href). Betrifft nur status.
• --unused: Nur ungenutzte Übersetzungsschlüssel melden – Schlüssel, die in Ihren Übersetzungsdateien vorhanden, aber nicht mehr in Ihrem Quellcode verwendet werden (d. h. was extract mit removeUnusedKeys löschen würde). Ändert niemals Dateien und beendet sich mit einem Fehlercode ungleich Null, wenn ungenutzte Schlüssel gefunden werden, sodass es als dedizierte CI-Prüfung neben der regulären Prüfung auf fehlende Übersetzungen dienen kann. Beachten Sie, dass die statische Analyse dynamisch erstellte Schlüssel (z. B. t(`error.${code}`)) nicht erkennen kann; um Schlüssel zu finden, die zur Laufzeit wirklich ungenutzt sind, siehe ungenutzte Übersetzungen mit locize finden.

Anwendungsbeispiele:

# Eine Zusammenfassung auf hoher Ebene für alle Gebietsschemata und Namespaces erhalten
npx i18next-cli status

# Einen detaillierten, schlüsselweisen Bericht für das Gebietsschema 'de' erhalten
npx i18next-cli status de

# Eine Zusammenfassung nur für den Namespace 'common' über alle Gebietsschemata hinweg erhalten
npx i18next-cli status --namespace common

# Einen detaillierten Bericht für das Gebietsschema 'de' mit nur dem Namespace 'common' erhalten
npx i18next-cli status de --namespace common

# Nur die unübersetzten Schlüssel für das Gebietsschema 'de' anzeigen
npx i18next-cli status de --hide-translated

# Optionen kombinieren, um nur fehlende Übersetzungen in einem bestimmten Namespace zu sehen
npx i18next-cli status de --namespace common --hide-translated

# Nur ungenutzte Schlüssel über alle Gebietsschemata hinweg melden (schreibgeschützt, beendet sich mit 1, wenn welche gefunden werden)
npx i18next-cli status --unused

# Nur ungenutzte Schlüssel in den 'en'-Dateien melden – z. B. als separate CI-Prüfung
npx i18next-cli status en --unused

Die Detailansicht bietet eine umfangreiche Zusammenfassung auf einen Blick für jeden Namespace, gefolgt von einer Liste jedes Schlüssels und seines Übersetzungsstatus.

Beispielausgabe (npx i18next-cli status de):

Schlüsselstatus für "de":

Gesamt: [■■■■■■■■■■■■■■■■■■■■] 100% (12/12)

Namespace: common
Fortschritt im Namespace: [■■■■■■■■■■■■■■■■■■■■] 100% (4/4)
  ✓ button.save
  ✓ button.cancel
  ✓ greeting
  ✓ farewell

Namespace: translation
Fortschritt im Namespace: [■■■■■■■■■■■■■■■■□□□□] 80% (8/10)
  ✓ app.title
  ✓ app.welc

…

[gekürzt für die Übersetzung]