Installation
Diese Seite installiert die CLI und sorgt dafür, dass der reine Befehl ai-i18n-tools funktioniert. Bereits installiert? Gehen Sie zu Schnellstart.
Das veröffentlichte Paket ist nur ESM. Verwenden Sie import oder import() in Node.js oder Ihrem Bundler; verwenden Sie nicht require('ai-i18n-tools'). Das Paket deklariert engines.node >=22.16.0; ältere Node.js-Versionen werden nicht unterstützt. Das npm-Tarball enthält den Consumer-Kontext unter docs/ai-i18n-tools-context.md und den vollständigen skills/-Baum, nicht die vollständige Dokumentationsseite; lokalspezifische Kopien unter translated-docs/ befinden sich im GitHub-Repository.
npm install ai-i18n-tools
# or
pnpm add ai-i18n-tools
# or
yarn add ai-i18n-toolsEigenständige ausführbare Dateien
GitHub Releases stellen einen Node.js-Einzel-Executable-Build bereit. Verwenden Sie diese Binärdatei, wenn das Projekt nicht auf Node.js läuft. Python- und .NET-Projekte führen dieselbe CLI von dort aus, einschließlich extract, translate-ui und suggest-models, ohne Node.js-Installation.
Linux und 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 | iexDer Installer erkennt das System, lädt ein gzip-Archiv der passenden ausführbaren Datei herunter, prüft SHA256SUMS.txt, entpackt es, installiert den Befehl als ai-i18n-tools (ai-i18n-tools.exe unter Windows) und fügt das Installationsverzeichnis zu PATH hinzu. Linux und macOS entpacken mit gzip. Windows PowerShell entpackt mit dem .NET-gzip-Reader, der bereits Teil von Windows ist. Das Standardverzeichnis ist ~/.local/bin. Öffnen Sie ein neues Terminal, falls der Befehl noch nicht gefunden wird. Legen Sie AI_I18N_VERSION fest (zum Beispiel v1.11.0), um eine Version festzulegen, oder AI_I18N_INSTALL_DIR, um ein anderes Verzeichnis zu wählen. Eine Version, die vor den gzip-Archiven veröffentlicht wurde, enthält noch die rohe ausführbare Datei, und der Installer akzeptiert diese Datei.
Die Binärdateien sind nicht notariell beglaubigt oder Authenticode-signiert. macOS fordert Sie möglicherweise auf, ein unsigniertes Programm zu genehmigen. Windows SmartScreen zeigt möglicherweise eine Warnung an. Der macOS-Installer löscht das Quarantäne-Flag, nachdem die Prüfsumme übereinstimmt.
Jede Version enthält auch SHA256SUMS.txt, ai-i18n-tools-python-examples.zip (die vier Python-Beispiele) und ai-i18n-tools-dotnet-examples.zip (dotnet-console, dotnet-resx und die assets/dotnet-Helfer, die diese Projekte kompilieren). Versionen, die vor dem .NET-Archiv veröffentlicht wurden, enthalten es nicht. Ab der Version, die das Skill-Archiv hinzufügt, enthält dieselbe Seite ai-i18n-tools-skill.zip, jedes Coding-Agent-Skill-Verzeichnis. Versionen, die vor diesem Skill-Zip veröffentlicht wurden, enthalten es nicht, und das erste Skill-Zip enthält nur ai-i18n-tools/. install.sh und install.ps1 bleiben im Repository-Stammverzeichnis, und die oben genannten Befehle laden sie von dort herunter. Das npm-Tarball und die ausführbare Datei enthalten die Beispielarchive oder das Skill-Zip nicht. Die Beispiele bleiben im Repository. Die Skill-Verzeichnisse befinden sich im npm-Tarball. Siehe Coding-Agent-Skill.
Manuelle Anweisungen zur Installation der ausführbaren Datei ai-i18n-tools
| Plattform | Asset |
|---|---|
| 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 |
- Laden Sie das Asset, das zu Ihrem Computer passt, und
SHA256SUMS.txtvon der Seite GitHub Releases herunter. - Überprüfen Sie die Prüfsumme des gzip-Archivs. Unter Linux,
grep ' ai-i18n-tools-linux-x64.gz$' SHA256SUMS.txt | sha256sum -c -(verwenden Sie den Namen des heruntergeladenen Assets). Unter macOS, die gleiche Zeile mitshasum -a 256 -c -. Unter Windows,(Get-FileHash -Algorithm SHA256 .\ai-i18n-tools-win-x64.exe.gz).Hashund vergleichen Sie es mit dem Hash inSHA256SUMS.txt. - Entpacken Sie das Archiv und legen Sie den Befehl auf
PATHab.
Linux und macOS, am Beispiel des Linux x64 Assets (ersetzen Sie das von Ihnen heruntergeladene Asset):
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"Wenn $HOME/.local/bin noch nicht in PATH enthalten ist, fügen Sie dies zum Shell-Profil (.bashrc, .bash_profile, .profile oder .zshrc) hinzu und öffnen Sie ein neues Terminal:
export PATH="$HOME/.local/bin:$PATH"Windows (PowerShell). GZipStream ist Teil von Windows PowerShell; es gibt keine separate gzip-Installation:
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")
}Öffnen Sie ein neues Terminal und führen Sie ai-i18n-tools --version aus. Der Befehlsname ist ai-i18n-tools auf jeder Plattform.
Legen Sie den API-Schlüssel für den aktiven Anbieter auf die gleiche Weise fest wie bei einer npm-Installation (siehe unten). Wählen Sie dann die init-Vorlage für das Projekt aus und übersetzen Sie. Ein Python-Projekt verwendet -t ui-python. Ein .NET-Projekt verwendet -t ui-dotnet. Eine App, die bereits Zeichenfolgen mit ResourceManager oder IStringLocalizer lädt, verwendet -t ui-dotnet-resx. Führen Sie eine init-Zeile aus:
# 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 syncVerwenden Sie init nur für eine neue Konfiguration: Es überschreibt die ausgewählte Konfigurationsdatei. Für bestehende Projekte bearbeiten Sie stattdessen die Konfiguration. sync verarbeitet alle konfigurierten/aktivierten Übersetzungs-Pipelines, einschließlich der UI-Extraktion.
Anleitungen: i18n zu einer Python-App hinzufügen, i18n zu einer .NET-App hinzufügen und i18n zu einer .NET-ResourceManager-App hinzufügen. Befehlsreferenz: suggest-models.
API-Schlüssel festlegen
Übersetzungsbefehle (translate-ui, translate-docs, translate-json, translate-svg, sync) erfordern eine Anbieterkonfiguration in ai-i18n-tools.config.json und einen API-Schlüssel für den aktiven Anbieter. Führen Sie ai-i18n-tools init -P <provider> aus, um diese Voreinstellung einzurichten. Anbietervoreinstellungen und API-Schlüssel: LLM-Anbieter. Die Modellliste aus init ist ein Ausgangspunkt. Ersetzen Sie sie mit suggest-models aus KI-Modelle oder über den Tab Modelle im Dashboard. Ollama ist die einzige integrierte Voreinstellung, die keinen API-Schlüssel benötigt.
Legen Sie den Schlüssel fest, der dem Anbieter entspricht, den Sie an init übergeben (siehe die Preset-Tabelle):
# init -P openrouter
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# init -P openai
# export OPENAI_API_KEY=sk-your-key-hereOder erstellen Sie eine .env- oder .env.local-Datei neben ai-i18n-tools.config.json. Diese Dateien werden nur gelesen, wenn noch kein Anbieter-API-Schlüssel festgelegt ist:
OPENROUTER_API_KEY=sk-or-v1-your-key-hereVerwendung der CLI
Installieren Sie ai-i18n-tools als Abhängigkeit oder devDependency in Ihrem Projekt (siehe Anfang dieser Seite). Wenn Anwendungscode ai-i18n-tools/runtime importiert, halten Sie es in der Produktionslaufzeit-/Build-Umgebung verfügbar; eine globale CLI oder eine eigenständige Binärdatei kann diesen Import nicht erfüllen. Das Paket deklariert einen bin-Eintrag, den Ihr Paketmanager mit node_modules/.bin/ai-i18n-tools verknüpft. Dieser Shim (bin/ai-i18n-tools.mjs innerhalb des installierten Pakets) lädt die kompilierte CLI.
Um den reinen Befehl ai-i18n-tools in einer interaktiven Shell einzugeben, konfigurieren Sie eine der folgenden Optionen. Ohne Einrichtung kann die Shell die Binärdatei auch nach einer lokalen Installation nicht finden.
direnv — fügen Sie dies einer .envrc im Projekt-Root hinzu (bash/zsh; siehe direnv.net):
PATH_add node_modules/.binNach direnv allow ist der reine Befehl verfügbar, wann immer Sie sich in das Projekt cd.
Manueller PATH — führen Sie diese Befehle vom Projekt-Root aus (dem Verzeichnis, das node_modules/.bin enthält). Unterverzeichnisse funktionieren danach weiterhin, solange Sie den PATH-Eintrag beibehalten; ein erneutes Ausführen des Exports aus einem verschachtelten Ordner schlägt fehl, da $PWD nicht mehr auf das Projekt-Root verweist.
# 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 syncGlobale Installation — installieren Sie die CLI einmal und rufen Sie sie von jedem Verzeichnis aus auf:
npm install -g ai-i18n-tools
# or
pnpm add -g ai-i18n-toolsFühren Sie bei pnpm pnpm setup einmal pro Maschine aus (und öffnen Sie eine neue Shell), wenn globale Befehle fehlen – pnpm benötigt sein globales Bin-Verzeichnis auf PATH. Eine globale Installation verwendet die global festgelegte Version. Für die projektbezogene Versionsfestlegung bevorzugen Sie direnv oder den manuellen PATH, damit node_modules/.bin auf die Abhängigkeit des Projekts verweist.
Aktualisieren Sie eine bestehende Installation mit ai-i18n-tools upgrade. Der Befehl gibt die neue Version aus und wartet auf y. --yes überspringt die Eingabeaufforderung. Eine Projekt-Abhängigkeit wird in package.json aktualisiert und mit npm, pnpm, yarn oder bun installiert. Eine globale Node.js-Installation verwendet die globale Installation des jeweiligen Paketmanagers. Eine eigenständige ausführbare Datei wird durch den GitHub Release Build für das aktuelle Betriebssystem und die Architektur ersetzt, nachdem die SHA256-Prüfsumme übereinstimmt. Siehe Upgrade.
package.json-Skripte — wenn npm oder pnpm ein Skript ausführt, stellt es node_modules/.bin vor PATH, sodass der reine Befehlsname innerhalb von Skripten ohne Änderungen am Shell-PATH funktioniert:
"scripts": {
"i18n:extract": "ai-i18n-tools extract",
"i18n:sync": "ai-i18n-tools sync",
"i18n:dashboard": "ai-i18n-tools dashboard"
}Führen Sie dann z. B. pnpm run i18n:sync aus. Die vollständige empfohlene Sammlung finden Sie unter Empfohlene package.json-Skripte.
Alternativen – falls Sie PATH nicht anpassen möchten: npx ai-i18n-tools … (npm) oder pnpm exec ai-i18n-tools … (pnpm). Für eine einmalige Ausführung ohne Installation und ohne package.json-Eintrag: npx ai-i18n-tools <cmd> oder pnpm dlx ai-i18n-tools <cmd>.
Coding-Agent-Skill
Die Installation des npm-Pakets oder der eigenständigen ausführbaren Datei registriert den Skill nicht bei einem Agenten. Die Installationsmethoden, nativen Kataloge und Agenten, die keinen Skill-Ordner haben, finden Sie unter Coding-Agent-Skill.
Beziehen Sie jedes Skill-Verzeichnis, jedes ein Ordner, der SKILL.md enthält, ohne dieses Repository zu klonen:
- Node.js 22.20 oder neuer:
npx skills add wsj-br/ai-i18n-tools --all -yinstalliert diese Verzeichnisse in den Skill-Ordner des Agenten. - Paket bereits installiert: Kopieren Sie
node_modules/ai-i18n-tools/skills/.in diesen Ordner. - Kein Node.js: Extrahieren Sie
package/skills/aus dem npm-Tarball für die Version inai-i18n-tools --version. Ab der Veröffentlichung, die es hinzufügt, enthältai-i18n-tools-skill.zipauf diesem GitHub Release dieselben Verzeichnisse. Veröffentlichungen, die vor dem Zip veröffentlicht wurden, enthalten es nicht. Das erste Zip enthält nurai-i18n-tools/.
Befehle und die Agenten-Ordner finden Sie unter Coding-Agent-Skill.
Geklontes Monorepo
Beim Entwickeln des Pakets oder Ausführen von Workspace-Beispielen aus einem vollständigen Klon von ai-i18n-tools:
- Workspace-Beispiele (
examples/console-app,examples/nextjs-appund die anderen Pakete, die inpnpm-workspace.yamlaufgeführt sind) – führen Siepnpm installim Repository-Stammverzeichnis aus, danncd examples/<name>. Verwenden Sie diepnpm run i18n:*-Skripte des Beispiels, oder konfigurieren Sie PATH (siehe Verwenden der CLI) und führen Sieai-i18n-tools …direkt aus. Workspaceoverridesverlinktai-i18n-toolsmit Ihrem lokalen Checkout. - Repository-Stammverzeichnis – pnpm verlinkt das eigene
bindes Stammverzeichnis-Pakets nicht innode_modules/.bin. Das.envrcdieses Checkouts fügtbin/zuPATHhinzu, sodass der committetebin/ai-i18n-tools-Wrapper (neben dem veröffentlichtenbin/ai-i18n-tools.mjs-Shim) den direkten Befehl nachdirenv allowbereitstellt. Ohne direnv verwenden Sienode bin/ai-i18n-tools.mjs …,./bin/ai-i18n-tools …oder diepnpm i18n:*-Skripte im Stammverzeichnis (oder einen Shell-Alias /pnpm add -g .). - Eigenständige Fixtures (
multi-provider,test-markdown) – verwenden Sie aus dem Fixture-Ordnernode ../../bin/ai-i18n-tools.mjs ….
Führen Sie pnpm run build im Repository-Stammverzeichnis aus, nachdem Sie die CLI-Quelle geändert haben. Siehe den Entwicklungsleitfaden für Build-Schritte und optionale Workarounds für die globale Installation.
Unter Linux, macOS und WSL setzen Registry-Installationen automatisch das Ausführbar-Bit für das CLI-Skript. Unter Windows erzeugen Paketmanager .cmd- und .ps1-Shims, die Node explizit aufrufen.
Weiter: Schnellstart.