Installation

Le package publié est uniquement ESM. Utilisez import/import() dans Node.js ou votre outil de regroupement, et non require('ai-i18n-tools'). Le package déclare engines.node >=22.16.0 ; les anciennes versions de Node.js ne sont pas prises en charge. L'archive tar de npm inclut uniquement les fichiers en anglais sous docs/ ; les copies spécifiques aux paramètres régionaux situées sous translated-docs/ se trouvent dans le dépôt GitHub.

npm install ai-i18n-tools
# or
pnpm add ai-i18n-tools
# or
yarn add ai-i18n-tools

ai-i18n-tools inclut son propre extracteur de chaînes. Si vous avez précédemment utilisé i18next-scanner, babel-plugin-i18next-extract ou des outils similaires, vous pouvez supprimer ces dépendances de développement après la migration.

Utilisation de l'interface en ligne de commande (CLI)

Installez ai-i18n-tools en tant que dépendance ou devDependency dans votre projet (voir Installation ci-dessus). Le package déclare une entrée bin que votre gestionnaire de packages lie à node_modules/.bin/ai-i18n-tools. Ce shim (bin/ai-i18n-tools.mjs à l'intérieur du package installé) charge l'interface de ligne de commande compilée.

Pour taper la commande simple ai-i18n-tools dans un shell interactif, configurez l'une des options ci-dessous. Sans configuration, le shell ne peut pas trouver le binaire même après une installation locale.

direnv — à ajouter à un .envrc à la racine du projet (bash/zsh ; voir direnv.net) :

PATH_add node_modules/.bin

Après direnv allow, la commande simple est disponible chaque fois que vous cd dans le projet.

Chemin d'accès manuel — exécutez ces commandes depuis la racine du projet (le répertoire qui contient node_modules/.bin). Les sous-répertoires continuent de fonctionner par la suite tant que vous laissez cette entrée PATH en place ; relancer l'exportation depuis un dossier imbriqué échoue car $PWD ne pointe plus vers la racine du projet.

# bash/zsh — from the project root
export PATH="$PWD/node_modules/.bin:$PATH"
ai-i18n-tools sync

# Windows PowerShell — from the project root
$env:Path = "$PWD\node_modules\.bin;$env:Path"
ai-i18n-tools sync

Installation globale — installez la CLI une fois et invoquez-la depuis n'importe quel répertoire :

npm install -g ai-i18n-tools
# or
pnpm add -g ai-i18n-tools

Avec pnpm, exécutez pnpm setup une fois par machine (et ouvrez un nouveau shell) si des commandes globales sont manquantes — pnpm nécessite son répertoire de binaires global sur PATH. Une installation globale utilise la version épinglée globalement. Pour l'épinglage de version par projet, préférez direnv ou le PATH manuel afin que node_modules/.bin se résolve à la dépendance du projet.

package.json scripts — lorsque npm ou pnpm exécute un script, il ajoute node_modules/.bin à PATH, de sorte que le nom de la commande fonctionne dans les scripts sans modifier le PATH du shell. Préférez sync plutôt que d'enchaîner manuellement les étapes de traduction — l'ordre et les indicateurs de fonctionnalité sont faciles à mal interpréter lorsqu'ils sont exécutés manuellement :

"scripts": {
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:dashboard": "ai-i18n-tools dashboard"
}

Exécutez ensuite, par exemple, pnpm run i18n:sync. Consultez Scripts package.json recommandés pour l'ensemble complet recommandé.

Alternatives — si vous préférez ne pas ajuster PATH : npx ai-i18n-tools … (npm) ou pnpm exec ai-i18n-tools … (pnpm). Pour une exécution unique sans installation et sans entrée package.json : npx ai-i18n-tools <cmd> ou pnpm dlx ai-i18n-tools <cmd>.

Monorepo ai-i18n-tools cloné

Lors du développement du package ou de l'exécution des exemples de l'espace de travail à partir d'un clone complet de ai-i18n-tools :

• Exemples d'espaces de travail (examples/console-app, examples/nextjs-app et les autres paquets listés dans pnpm-workspace.yaml) — exécutez pnpm install à la racine du dépôt, puis cd examples/<name>. Utilisez les scripts pnpm run i18n:* de l'exemple, ou configurez PATH (voir Utilisation de la CLI) et exécutez ai-i18n-tools … directement. Les liens overrides de l'espace de travail ai-i18n-tools vers votre copie locale.
• Racine du dépôt — pnpm ne lie pas les propres bin du paquet racine dans node_modules/.bin. Utilisez plutôt node bin/ai-i18n-tools.mjs … ou les scripts pnpm i18n:* de la racine (ou un alias de shell / pnpm add -g . — voir Guide de développement).
• Fixtures autonomes (multi-provider, test-markdown) — depuis le dossier de la fixture, utilisez node ../../bin/ai-i18n-tools.mjs ….

Exécutez pnpm run build à la racine du dépôt après avoir modifié la source de l'interface de ligne de commande. Consultez le Guide de développement pour les étapes de construction et les solutions de contournement facultatives pour l'installation globale.

Sous Linux, macOS et WSL, les installations depuis le registre définissent automatiquement le bit d'exécution sur le script CLI. Sous Windows, les gestionnaires de paquets génèrent des shim .cmd et .ps1 qui invoquent explicitement Node.

Les commandes de traduction (translate-ui, translate-docs, translate-json, translate-svg, sync) nécessitent une configuration de fournisseur dans ai-i18n-tools.config.json et une clé API pour le fournisseur actif. Exécutez ai-i18n-tools init [-P <provider>] pour échafauder un bloc de fournisseur par défaut (openrouter si omis) ; modifiez provider / providers pour changer les préréglages ou les modèles — voir Fournisseurs et modèles LLM. Ollama est le seul préréglage intégré qui ne nécessite pas de clé API.

Définissez la clé API qui correspond à votre fournisseur actif (voir le tableau des préréglages) :

# Default init (openrouter)
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Example: init -P anthropic
# export ANTHROPIC_API_KEY=sk-ant-your-key-here

Ou créez un fichier .env à la racine du projet :

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Langue de l'interface utilisateur de l'outil

L'interface de ligne de commande (CLI) localise son propre texte d'aide, les résumés de journaux et le tableau de bord de traduction indépendamment des paramètres régionaux que vous traduisez. Par défaut, elle suit les paramètres régionaux de votre système d'exploitation. Vous pouvez les remplacer par -L pt-BR, export AI_I18N_LANG=es ou "uiLanguage" dans la configuration. Voir Langue de l'interface utilisateur de l'outil.