Installation
Cette page installe l'interface de ligne de commande (CLI) et fait fonctionner la commande ai-i18n-tools de base. Déjà installé ? Accédez au Démarrage rapide.
Le package publié est uniquement ESM. Utilisez import ou import() dans Node.js ou votre bundler ; n'utilisez pas require('ai-i18n-tools'). Le package déclare engines.node >=22.16.0 ; les versions plus anciennes de Node.js ne sont pas prises en charge. Le tarball npm inclut le contexte consommateur à docs/ai-i18n-tools-context.md et l'arborescence complète skills/, pas le site de documentation complet ; les copies spécifiques à la locale 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-toolsExécutables autonomes
Les versions GitHub incluent une version exécutable unique de Node.js. Utilisez ce binaire lorsque le projet ne s'exécute pas sur Node.js. Les projets Python et .NET exécutent la même CLI à partir de celui-ci, y compris extract, translate-ui et suggest-models, sans installation de Node.js.
Linux et macOS :
curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bashWindows (PowerShell) :
irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iexL'installeur détecte le système, télécharge une archive gzip de l'exécutable correspondant, vérifie SHA256SUMS.txt, la décompresse, installe la commande en tant que ai-i18n-tools (ai-i18n-tools.exe sous Windows), et ajoute le répertoire d'installation à PATH. Linux et macOS décompressent avec gzip. Windows PowerShell décompresse avec le lecteur gzip .NET, qui fait déjà partie de Windows. Le répertoire par défaut est ~/.local/bin. Ouvrez un nouveau terminal si la commande n'est pas encore trouvée. Définissez AI_I18N_VERSION (par exemple v1.11.0) pour épingler une version, ou AI_I18N_INSTALL_DIR pour choisir un autre répertoire. Une version publiée avant les archives gzip contient toujours l'exécutable brut, et l'installeur accepte ce fichier.
Les binaires ne sont pas notarisés ni signés Authenticode. macOS peut vous demander d'approuver un programme non signé. Windows SmartScreen peut afficher un avertissement. L'installateur macOS efface l'indicateur de quarantaine une fois que la somme de contrôle correspond.
Chaque version inclut également SHA256SUMS.txt, ai-i18n-tools-python-examples.zip (les quatre exemples Python) et ai-i18n-tools-dotnet-examples.zip (dotnet-console, dotnet-resx et les assistants assets/dotnet que ces projets compilent). Les versions publiées avant l'archive .NET ne l'incluent pas. À partir de la version qui ajoute l'archive de compétences, la même page inclut ai-i18n-tools-skill.zip, chaque répertoire de compétences d'agent de codage. Les versions publiées avant ce fichier zip de compétences ne l'incluent pas, et le premier fichier zip de compétences contient uniquement ai-i18n-tools/. install.sh et install.ps1 restent à la racine du dépôt, et les commandes ci-dessus les téléchargent à partir de là. Le tarball npm et l'exécutable ne contiennent pas les archives d'exemples ni le fichier zip de compétences. Les exemples restent dans le dépôt. Les répertoires de compétences se trouvent dans le tarball npm. Voir Compétence d'agent de codage.
Instructions manuelles pour installer l'exécutable ai-i18n-tools
| Plateforme | Actif |
|---|---|
| Linux x64 | ai-i18n-tools-linux-x64.gz |
| Linux arm64 | ai-i18n-tools-linux-arm64.gz |
| macOS arm64 | ai-i18n-tools-macos-arm64.gz |
| macOS x64 | ai-i18n-tools-macos-x64.gz |
| Windows x64 | ai-i18n-tools-win-x64.exe.gz |
- Téléchargez l'actif qui correspond à votre machine, et
SHA256SUMS.txt, depuis la page Versions GitHub. - Vérifiez la somme de contrôle de l'archive gzip. Sous Linux,
grep ' ai-i18n-tools-linux-x64.gz$' SHA256SUMS.txt | sha256sum -c -(utilisez le nom de l'actif que vous avez téléchargé). Sous macOS, la même ligne avecshasum -a 256 -c -. Sous Windows,(Get-FileHash -Algorithm SHA256 .\ai-i18n-tools-win-x64.exe.gz).Hashet comparez-le avec le hachage dansSHA256SUMS.txt. - Décompressez l'archive et placez la commande sur
PATH.
Linux et macOS, en utilisant l'actif Linux x64 comme exemple (substituez l'actif que vous avez téléchargé) :
mkdir -p "$HOME/.local/bin"
gzip -dc ai-i18n-tools-linux-x64.gz > "$HOME/.local/bin/ai-i18n-tools"
chmod +x "$HOME/.local/bin/ai-i18n-tools"Si $HOME/.local/bin n'est pas déjà sur PATH, ajoutez ceci au profil shell (.bashrc, .bash_profile, .profile ou .zshrc) et ouvrez un nouveau terminal :
export PATH="$HOME/.local/bin:$PATH"Windows (PowerShell). GZipStream fait partie de Windows PowerShell ; il n'y a pas d'installation gzip séparée :
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.local\bin" | Out-Null
Add-Type -AssemblyName System.IO.Compression
$gz = [System.IO.File]::OpenRead("$PWD\ai-i18n-tools-win-x64.exe.gz")
$outPath = "$env:USERPROFILE\.local\bin\ai-i18n-tools.exe"
try {
$gzipStream = New-Object System.IO.Compression.GZipStream($gz, [System.IO.Compression.CompressionMode]::Decompress)
try {
$out = [System.IO.File]::Create($outPath)
try { $gzipStream.CopyTo($out) } finally { $out.Dispose() }
} finally { $gzipStream.Dispose() }
} finally { $gz.Dispose() }
$installDir = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ([string]::IsNullOrEmpty($userPath)) {
[Environment]::SetEnvironmentVariable("Path", $installDir, "User")
} elseif ($userPath -notlike "*${installDir}*") {
[Environment]::SetEnvironmentVariable("Path", "$installDir;$userPath", "User")
}Ouvrez un nouveau terminal et exécutez ai-i18n-tools --version. Le nom de la commande est ai-i18n-tools sur toutes les plateformes.
Définissez la clé API pour le fournisseur actif de la même manière qu'une installation npm (voir ci-dessous). Ensuite, choisissez le modèle init pour le projet et traduisez. Un projet Python utilise -t ui-python. Un projet .NET utilise -t ui-dotnet. Une application qui charge déjà des chaînes avec ResourceManager ou IStringLocalizer utilise -t ui-dotnet-resx. Exécutez une ligne init :
# Python
ai-i18n-tools init -t ui-python -P cheaperinference
# .NET
# ai-i18n-tools init -t ui-dotnet -P cheaperinference
# .NET ResourceManager or IStringLocalizer
# ai-i18n-tools init -t ui-dotnet-resx -P cheaperinference
ai-i18n-tools suggest-models --apply
ai-i18n-tools syncUtilisez init uniquement pour une nouvelle configuration : il écrase le fichier de configuration sélectionné. Pour les projets existants, modifiez plutôt la configuration. sync gère tous les pipelines de traduction configurés/activés, y compris l'extraction d'interface utilisateur.
Procédures pas à pas : Ajouter l'i18n à une application Python, Ajouter l'i18n à une application .NET et Ajouter l'i18n à une application .NET ResourceManager. Référence des commandes : suggest-models.
Définir la clé API
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é d'API pour le fournisseur actif. Exécutez ai-i18n-tools init -P <provider> pour générer la structure de ce préréglage. Préréglages de fournisseur et clés d'API : Fournisseurs de LLM. La liste de modèles de init est un point de départ. Remplacez-la à partir de Modèles d'IA avec suggest-models ou l'onglet Modèles du tableau de bord. Ollama est le seul préréglage intégré qui ne nécessite aucune clé d'API.
Définissez la clé qui correspond au fournisseur que vous passez à init (voir le tableau des préréglages) :
# init -P openrouter
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# init -P openai
# export OPENAI_API_KEY=sk-your-key-hereOu créez un fichier .env ou .env.local à côté de ai-i18n-tools.config.json. Ces fichiers ne sont lus que si aucune clé API de fournisseur n'est déjà définie :
OPENROUTER_API_KEY=sk-or-v1-your-key-hereUtilisation de l'interface en ligne de commande (CLI)
Installez ai-i18n-tools en tant que dépendance ou devDependency dans votre projet (voir le haut de cette page). Si le code de l'application importe ai-i18n-tools/runtime, maintenez-le disponible dans l'environnement d'exécution/de construction de production ; une CLI globale ou un binaire autonome ne peut pas satisfaire cette importation. 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 la CLI 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 — ajoutez à un .envrc à la racine du projet (bash/zsh ; voir direnv.net) :
PATH_add node_modules/.binAprès direnv allow, la commande simple est disponible chaque fois que vous cd dans le projet.
PATH 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 syncInstallation globale — installez l'interface de ligne de commande une fois et invoquez-la depuis n'importe quel répertoire :
npm install -g ai-i18n-tools
# or
pnpm add -g ai-i18n-toolsAvec 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.
Mettez à jour une installation existante avec ai-i18n-tools upgrade. La commande affiche la nouvelle version et attend y. --yes ignore l'invite. Une dépendance de projet est mise à jour dans package.json et installée avec npm, pnpm, yarn ou bun. Une installation globale de Node.js utilise l'installation globale de ce gestionnaire de paquets. Un exécutable autonome est remplacé par la version de GitHub Release pour le système d'exploitation et l'architecture actuels après que la somme de contrôle SHA256 corresponde. Voir mise à jour.
Scripts package.json — lorsque npm ou pnpm exécute un script, il préfixe node_modules/.bin à PATH, de sorte que le nom de commande de base fonctionne à l'intérieur des scripts sans modifications du PATH du shell :
"scripts": {
"i18n:extract": "ai-i18n-tools extract",
"i18n:sync": "ai-i18n-tools sync",
"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 modifier 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>.
Compétence d'agent de codage
L'installation du package npm ou de l'exécutable autonome n'enregistre pas la compétence auprès d'un agent. Les méthodes d'installation, les catalogues natifs et les agents qui n'ont pas de dossier de compétences se trouvent sur Compétence d'agent de codage.
Obtenez chaque répertoire de compétence, chacun étant un dossier qui contient SKILL.md, sans cloner ce dépôt :
- Node.js 22.20 ou version ultérieure :
npx skills add wsj-br/ai-i18n-tools --all -yinstalle ces répertoires dans le dossier de compétences de l'agent. - Package déjà installé : copiez
node_modules/ai-i18n-tools/skills/.dans ce dossier. - Pas de Node.js : extrayez
package/skills/du tarball npm pour la version dansai-i18n-tools --version. À partir de la version qui l'ajoute,ai-i18n-tools-skill.zipsur cette version GitHub contient les mêmes répertoires. Les versions publiées avant le zip ne l'incluent pas. Le premier zip contient uniquementai-i18n-tools/.
Les commandes et les dossiers d'agent se trouvent sur Compétence d'agent de codage.
Monorepo cloné
Lors du développement du package ou de l'exécution des exemples d'espace de travail à partir d'un clone complet de ai-i18n-tools :
- Exemples d'espace de travail (
examples/console-app,examples/nextjs-appet les autres packages listés danspnpm-workspace.yaml) — exécutezpnpm installà la racine du dépôt, puiscd examples/<name>. Utilisez les scriptspnpm run i18n:*de l'exemple, ou configurez le PATH (voir Utilisation de la CLI) et exécutezai-i18n-tools …directement. Leoverridesde l'espace de travail lieai-i18n-toolsà votre copie locale. - Racine du dépôt — pnpm ne lie pas le propre
bindu package racine dansnode_modules/.bin. Le.envrcde cette copie ajoutebin/auPATHafin que le wrapperbin/ai-i18n-toolscommité (à côté du shimbin/ai-i18n-tools.mjspublié) fournisse la commande directe aprèsdirenv allow. Sans direnv, utiliseznode bin/ai-i18n-tools.mjs …,./bin/ai-i18n-tools …ou les scriptspnpm i18n:*à la racine (ou un alias de shell /pnpm add -g .). - Fixtures autonomes (
multi-provider,test-markdown) — depuis le dossier de la fixture, utiliseznode ../../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.
Suivant : Démarrage rapide.