i18next/i18next-cli

i18next-cli 🚀

Une CLI i18next unifiée et haute performance, propulsée par SWC.

---

Par défaut, i18next-cli extrait uniquement les clés de traduction des fichiers JavaScript et TypeScript (.js, .jsx, .ts, .tsx). Pour extraire d'autres types de fichiers (tels que .pug, .vue, .svelte, etc.), vous devez utiliser ou créer un plugin. Spécifier des extensions de fichier supplémentaires dans la configuration extract.input n'est pas suffisant en soi — des plugins sont nécessaires pour les formats non-JS/TS. Voir la section Système de plugins pour plus de détails et des exemples.

i18next-cli est une réinvention complète de la chaîne d'outils d'analyse statique pour l'écosystème i18next. Elle consolide l'extraction de clés, la génération de sécurité de typage, la synchronisation de locales, le linting et les intégrations cloud dans une seule CLI cohérente et extrêmement rapide.

🚀 Essayez-le maintenant - Zéro configuration !

Vous pouvez obtenir une analyse instantanée de votre projet i18next existant sans aucune configuration. Exécutez simplement cette commande à la racine de votre dépôt :

npx i18next-cli status

Ou trouvez les chaînes codées en dur :

npx i18next-cli lint

Conseil :

Si vous recherchez un backend géré à associer avec i18next-cli, jetez un œil à Locize — i18next-cli est déjà livré avec les commandes locize-download, locize-sync et locize-migrate. Construit par la même équipe derrière i18next, avec la livraison par CDN, la traduction IA, un workflow de révision et aucun redéploiement pour les modifications de contenu.

Pourquoi i18next-cli ?

i18next-cli est construit de zéro pour répondre aux exigences du développement web moderne.

• 🚀 Performance : En utilisant un analyseur natif basé sur Rust (SWC), il offre des performances d'ordres de grandeur supérieures à celles des analyseurs JavaScript.
• 🧠 Intelligence : Un analyseur stateful et conscient de la portée comprend correctement des motifs complexes comme useTranslation('ns1', { keyPrefix: '...' }), getFixedT et les fonctions t aliasées, minimisant le besoin de solutions de contournement manuelles.
• ✅ Flux de travail unifié : Un outil, un fichier de configuration, un flux de travail intégré. Il remplace divers scripts de synchronisation.
• 🔌 Extensibilité : Une architecture de plugins moderne permet à l'outil de s'adapter à n'importe quel framework ou flux de travail personnalisé.
• 🧑‍💻 Expérience développeur : Un fichier de configuration entièrement typé, des modes --watch en direct, une sortie CLI et une migration depuis les outils existants.

Fonctionnalités

• Extraction de clés : L'extraction signifie trouver et collecter automatiquement toutes les clés de traduction utilisées dans votre code source (JavaScript/TypeScript, etc.) en analysant la structure du code (AST). Cela garantit que chaque chaîne nécessitant une traduction est identifiée et incluse dans vos fichiers de traduction, réduisant le travail manuel et empêchant les clés manquantes.
• Sécurité de typage : Générer des définitions TypeScript pour une autocomplétion complète et une sécurité de typage.
• Synchronisation des locales : Gardez tous les fichiers de langue synchronisés avec votre langue principale.
• Linting de code précis : Détectez les chaînes codées en dur avec une haute précision et des règles configurables.
• Statut de traduction : Obtenez un aperçu de haut niveau ou un rapport détaillé, clé par clé, de l'exhaustivité des traductions de votre projet.
• Système de plugins : Architecture extensible pour des motifs d'extraction personnalisés et des types de fichiers (par exemple, HTML, Handlebars).
• Migration héritée : Migration automatique depuis les configurations i18next-parser.
• Intégration cloud : Intégration transparente avec la plateforme de gestion de traduction Locize.

Installation

npm install --save-dev i18next-cli

Démarrage rapide

Du zéro au localisé en une commande : vous partez d'une application avec des chaînes codées en dur (par exemple, générée avec v0, Lovable, Bolt ou Cursor) ? Exécutez npx i18next-cli localize — elle détecte votre configuration, encapsule les chaînes codées en dur dans des appels t(), extrait les clés, se connecte à Locize et traduit votre application par IA. Voir la commande localize. Vous travaillez avec un agent de codage IA (Claude Code, Cursor, ...) ? npx i18next-cli localize --print-agent-prompt affiche le même flux sous forme d'un runbook d'agent copiable. Les étapes ci-dessous sont le chemin manuel.

1. Initialiser la configuration

Créez une configuration de manière interactive :

npx i18next-cli init

Ou créez manuellement i18next.config.ts à la racine de votre projet :

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. Vérifier le statut de vos traductions

Obtenez un aperçu de l'état de santé de la localisation de votre projet :

npx i18next-cli status

3. Extraire les clés de traduction

npx i18next-cli extract

4. Générer les types (Optionnel)

npx i18next-cli types

Commandes

init

Assistant de configuration interactif pour créer votre fichier de configuration.

npx i18next-cli init

Options :

• --ci : Ignorer l'ouverture du navigateur lorsqu'un backend (par exemple Locize) est sélectionné ; l'URL d'inscription est affichée à la place. Utile pour les exécutions scriptées. L'assistant détecte également automatiquement CI=true et revient à l'affichage de l'URL sur Linux sans tête (pas de DISPLAY/WAYLAND_DISPLAY), donc ce drapeau est rarement nécessaire explicitement.
• --inlang : Crée également une structure de projet inlang (project.inlang/settings.json) afin que les outils inlang — l'extension VS Code Sherlock, l'éditeur web Fink pour les traducteurs et le compilateur Paraglide — fonctionnent directement sur vos fichiers de traduction. Ignore la question correspondante de l'assistant.

L'assistant demande le type de fichier de configuration, les locales, le glob des fichiers source, le chemin de sortie et enfin « Backend de traduction ? » avec trois options :

• Fichiers locaux uniquement (par défaut) — conserve le flux de travail JSON local actuel.
• Locize (recommandé pour les flux de travail en équipe / production) — ouvre la page d'inscription Locize dans votre navigateur, puis demande votre ID de projet et votre clé API. L'assistant écrit un bloc locize dans la configuration générée afin que locize-sync fonctionne immédiatement. La demande de clé API peut rester vide (mode lecture seule) ; ajoutez-la plus tard via une variable d'environnement LOCIZE_API_KEY.
• Autre / ignorer — identique à « Fichiers locaux uniquement » pour les besoins de l'assistant.

L'assistant propose ensuite de configurer les outils inlang (par défaut : non — ou passez --inlang pour ignorer la question). Si accepté, il crée un project.inlang/settings.json qui pointe le plugin i18next inlang vers vos fichiers de traduction existants : baseLocale/locales proviennent de votre configuration, et pathPattern est dérivé de extract.output (la forme d'objet avec espace de noms lorsque votre modèle utilise {{namespace}}, avec les espaces de noms découverts à partir des fichiers de la langue principale ; un modèle simple sinon). Il ajoute également l'extension Sherlock aux recommandations de .vscode/extensions.json (fusion sensible aux commentaires, sans jamais écraser les entrées existantes). Vos fichiers JSON i18next restent la seule source de vérité — les outils inlang les lisent et les écrivent sur place, il n'y a donc pas de deuxième catalogue pouvant diverger. Un project.inlang/settings.json existant n'est jamais écrasé ; réexécuter init est sans danger. Nécessite des fichiers de ressources JSON. Le plugin est épinglé à une version vérifiée exacte (@inlang/[email protected]) — mettez à jour l'URL du modules dans settings.json pour obtenir les versions plus récentes du plugin. Seul settings.json est créé par conception : project.inlang/ est la forme de projet décompressée (compatible git), et les outils inlang génèrent et gèrent ses fichiers restants (.gitignore, README.md, cache/) lors de la première utilisation — attendez-vous donc à quelques nouveaux fichiers après avoir ouvert le projet avec Sherlock ou Paraglide.

extract

Analyse les fichiers source, extrait les clés et met à jour vos fichiers de traduction JSON.

npx i18next-cli extract [options]

Options :

• --watch, -w : Réexécuter automatiquement lorsque les fichiers changent
• --ci : Quitter avec un statut non nul si des fichiers sont mis à jour (pour CI/CD)
• --dry-run : Ne modifie aucun fichier - utile en combinaison avec --ci (pour CI/CD)
• --sync-primary : Synchroniser les valeurs de la langue principale avec les valeurs par défaut du code
• --sync-all : Synchroniser les valeurs de la langue principale avec les valeurs par défaut du code ET effacer les clés synchronisées dans toutes les autres locales (implique --sync-primary)
• --trust-derived : Lorsqu'il est utilisé avec --sync-primary ou --sync-all, fait également confiance aux valeurs par défaut déduites des clés telles que t('Hello') ou les valeurs dérivées de keyPrefix. Cela maintient le comportement de synchronisation par défaut strict, sauf si vous optez.
• --with-types : Après l'extraction (et à chaque réexécution en mode --watch), régénérer les définitions TypeScript chaque fois que les fichiers de traduction ont changé. Évite d'avoir à exécuter extract -w et types -w comme deux processus séparés.
• --quiet : Supprimer le spinner et la sortie non essentielle (pour CI ou script)

Contrôle de la sortie du spinner et du logger

Toutes les commandes qui affichent des spinners de progression (extract, types, lint, sync) prennent désormais en charge :

• Le drapeau --quiet pour supprimer le spinner et la sortie non essentielle (pour CI, script ou capture de logs)
• La prise en charge du logger programmatique : passez un objet logger personnalisé pour capturer la sortie dans votre propre format ou flux

Exemple CLI :

npx i18next-cli extract --quiet

Exemple programmatique :

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 });

Si vous passez un logger, la sortie du spinner et tous les messages de progression/information sont redirigés vers votre logger au lieu du spinner interactif.

Exemples :

# Extraction unique
npx i18next-cli extract

# Mode surveillance pour le développement
npx i18next-cli extract --watch

# Mode CI (échoue si des fichiers ont changé)
npx i18next-cli extract --ci

# Synchroniser la langue principale avec les valeurs par défaut du code
npx i18next-cli extract --sync-primary

# Synchroniser la langue principale et effacer les clés synchronisées dans toutes les autres locales
npx i18next-cli extract --sync-all

# Synchroniser en utilisant les valeurs par défaut explicites plus les valeurs par défaut déduites des clés
npx i18next-cli extract --sync-all --trust-derived

# Combiner les options pour un flux de développement optimal
npx i18next-cli extract --sync-primary --watch

# Maintenir les définitions TypeScript synchronisées à partir d'un seul processus (pas besoin de `types -w` séparé)
npx i18next-cli extract --watch --with-types

status [locale]

Affiche un état de santé du statut de traduction de votre projet. Peut être exécuté sans fichier de configuration. Quitte avec un code de statut non nul lorsque des traductions sont manquantes.

La langue principale est également vérifiée : toute clé utilisée dans votre code mais absente des fichiers de traduction de la langue principale (une faute de frappe, ou extract n'a jamais été exécuté) est signalée et provoque un code de sortie non nul. Les espaces réservés de chaîne vide écrits par extract sont considérés comme présents et ne font pas échouer la vérification. Exécuter npx i18next-cli status <primaryLanguage> montre les clés absentes en détail.

Options :

• --namespace <ns>, -n <ns> : Filtrer le rapport par un espace de noms spécifique.
• --hide-translated : Masquer les clés déjà traduites dans la vue détaillée, montrant uniquement les traductions manquantes.
• status.ignoreKeys (configuration) : motifs glob pour les clés qui ne doivent pas être signalées (et ne font pas échouer la vérification), par exemple les clés qui sont intentionnellement laissées vides dans certaines locales. Préfixe optionnel ns: (common:help.*-href). Affecte uniquement status.
• --unused : Signaler uniquement les clés de traduction inutilisées — les clés présentes dans vos fichiers de traduction qui ne sont plus utilisées dans votre code source (c'est-à-dire ce que extract avec removeUnusedKeys supprimerait). Ne modifie jamais les fichiers et quitte avec un code de statut non nul lorsque des clés inutilisées sont trouvées, il peut donc servir de vérification CI dédiée en plus de la vérification régulière des traductions manquantes. Notez que l'analyse statique ne peut pas détecter les clés construites dynamiquement (par exemple ` `\`t(\`error.\${code}\`)`) ; pour trouver les clés vraiment inutilisées à l'exécution, consultez trouver les traductions inutilisées avec Locize.

Exemples d'utilisation :

# Obtenir un résumé de haut niveau pour toutes les locales et tous les espaces de noms
npx i18next-cli status

# Obtenir un rapport détaillé, clé par clé, pour la locale 'de'
npx i18next-cli status de

# Obtenir un résumé uniquement pour l'espace de noms 'common' dans toutes les locales
npx i18next-cli status --namespace common

# Obtenir un rapport détaillé pour la locale 'de', ne montrant que l'espace de noms 'common'
npx i18next-cli status de --namespace common

# Afficher uniquement les clés non traduites pour la locale 'de'
npx i18next-cli status de --hide-translated

# Combiner les options pour voir uniquement les traductions manquantes dans un espace de noms spécifique
npx i18next-cli status de --namespace common --hide-translated

# Signaler uniquement les clés inutilisées dans toutes les locales (lecture seule, quitte avec 1 si trouvées)
npx i18next-cli status --unused

# Signaler uniquement les clés inutilisées dans les fichiers 'en' — par exemple comme vérification CI séparée
npx i18next-cli status en --unused

La vue détaillée fournit un résumé riche et en un coup d'œil pour chaque espace de noms, suivi d'une liste de chaque clé et de son statut de traduction.

Exemple de sortie (npx i18next-cli status de) :

Key Status for "de":

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

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

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

…