Installation

This page installs the CLI and gets the bare ai-i18n-tools command working. Already installed? Go to Quick start.

The published package is ESM-only. Use import or import() in Node.js or your bundler; do not use require('ai-i18n-tools'). The package declares engines.node >=22.16.0; older Node.js versions are unsupported. The npm tarball includes English files under docs/ only; locale-specific copies under translated-docs/ are in the GitHub repository.

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

Standalone executables

GitHub Releases attach a Node.js single-executable build. Python projects run the CLI from that binary, including extract, translate-ui, and suggest-models, with no Node.js install.

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex

The installer detects the system, downloads the matching executable, checks SHA256SUMS.txt, installs the command as ai-i18n-tools (ai-i18n-tools.exe on Windows), and adds the install directory to PATH. The default directory is ~/.local/bin. Open a new terminal if the command is not found yet. Set AI_I18N_VERSION (for example v1.11.0) to pin a release, or AI_I18N_INSTALL_DIR to choose another directory.

The binaries are not notarized or Authenticode-signed. macOS may ask you to approve an unsigned program. Windows SmartScreen may show a warning. The macOS installer clears the quarantine flag after the checksum matches.

Each release also attaches SHA256SUMS.txt, install.sh, install.ps1, and ai-i18n-tools-python-examples.zip (the four Python examples). The npm tarball and the executable do not contain those examples. They stay in the repository as well.

Manual instructions to install ai-i18n-tools executable

Platform	Asset
Linux x64	ai-i18n-tools-linux-x64
Linux arm64	ai-i18n-tools-linux-arm64
macOS arm64	ai-i18n-tools-macos-arm64
macOS x64	ai-i18n-tools-macos-x64
Windows x64	ai-i18n-tools-win-x64.exe

1. Download the asset that matches the machine, and SHA256SUMS.txt, from the GitHub Releases page.
2. Check the checksum. On Linux, grep ' ai-i18n-tools-linux-x64$' SHA256SUMS.txt | sha256sum -c - (use the asset name you downloaded). On macOS, the same line with shasum -a 256 -c -. On Windows, (Get-FileHash -Algorithm SHA256 .\ai-i18n-tools-win-x64.exe).Hash and compare it with the hash in SHA256SUMS.txt.
3. Rename the downloaded file to ai-i18n-tools and put that directory on PATH.

Linux and macOS, using the Linux x64 asset as the example (substitute the asset you downloaded):

mkdir -p "$HOME/.local/bin"
mv ai-i18n-tools-linux-x64 "$HOME/.local/bin/ai-i18n-tools"
chmod +x "$HOME/.local/bin/ai-i18n-tools"

If $HOME/.local/bin is not already on PATH, add this to the shell profile (.bashrc, .bash_profile, .profile, or .zshrc) and open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

Windows (PowerShell), renaming ai-i18n-tools-win-x64.exe to ai-i18n-tools.exe:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.local\bin" | Out-Null
Move-Item -Force .\ai-i18n-tools-win-x64.exe "$env:USERPROFILE\.local\bin\ai-i18n-tools.exe"
$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")
}

Open a new terminal and run ai-i18n-tools --version. The command name is ai-i18n-tools on every platform.

Set the API key for the active provider the same way as an npm install (see below). Then:

ai-i18n-tools init -t ui-python -P cheaperinference
ai-i18n-tools suggest-models --apply
ai-i18n-tools extract
ai-i18n-tools translate-ui

Walkthrough: Add i18n to a Python app. Command reference: suggest-models.

Set the API key

Translation commands (translate-ui, translate-docs, translate-json, translate-svg, sync) require provider configuration in ai-i18n-tools.config.json and an API key for the active provider. Run ai-i18n-tools init -P <provider> to scaffold that preset. Provider presets and API keys: LLM providers. The model list from init is a starting point. Replace it from AI Models with suggest-models or the dashboard Models tab. Ollama is the only built-in preset that needs no API key.

Set the key that matches the provider you pass to init (see the preset table):

# init -P openrouter
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# init -P openai
# export OPENAI_API_KEY=sk-your-key-here

Or create a .env file in the project root:

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

Using the CLI

Install ai-i18n-tools as a dependency or devDependency in your project (see the top of this page). The package declares a bin entry that your package manager links to node_modules/.bin/ai-i18n-tools. That shim (bin/ai-i18n-tools.mjs inside the installed package) loads the compiled CLI.

To type the bare ai-i18n-tools command in an interactive shell, configure one of the options below. Without setup, the shell cannot find the binary even after a local install.

direnv — add to a .envrc in the project root (bash/zsh; see direnv.net):

PATH_add node_modules/.bin

After direnv allow, the bare command is available whenever you cd into the project.

Manual PATH — run these from the project root (the directory that contains node_modules/.bin). Subdirectories keep working afterward as long as you leave that PATH entry in place; re-running the export from a nested folder fails because $PWD no longer points at the project root.

# 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

Global install — install the CLI once and invoke it from any directory:

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

With pnpm, run pnpm setup once per machine (and open a new shell) if global commands are missing — pnpm requires its global bin directory on PATH. A global install uses the globally pinned version. For per-project version pinning, prefer direnv or manual PATH so node_modules/.bin resolves to the project's dependency.

package.json scripts — when npm or pnpm runs a script, it prepends node_modules/.bin to PATH, so the bare command name works inside scripts without shell PATH changes:

"scripts": {
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:dashboard": "ai-i18n-tools dashboard"
}

Then run e.g. pnpm run i18n:sync. See Recommended package.json scripts for the full recommended set.

Alternatives — if you prefer not to adjust PATH: npx ai-i18n-tools … (npm) or pnpm exec ai-i18n-tools … (pnpm). For a zero-install one-off with no package.json entry: npx ai-i18n-tools <cmd> or pnpm dlx ai-i18n-tools <cmd>.

Cloned monorepo

When developing the package or running workspace examples from a full clone of ai-i18n-tools:

• Workspace examples (examples/console-app, examples/nextjs-app, and the other packages listed in pnpm-workspace.yaml) — run pnpm install at the repository root, then cd examples/<name>. Use the example's pnpm run i18n:* scripts, or configure PATH (see Using the CLI) and run bare ai-i18n-tools …. Workspace overrides link ai-i18n-tools to your local checkout.
• Repository root — pnpm does not link the root package's own bin into node_modules/.bin. This checkout's .envrc adds bin/ to PATH so the committed bin/ai-i18n-tools wrapper (beside the published bin/ai-i18n-tools.mjs shim) provides the bare command after direnv allow. Without direnv, use node bin/ai-i18n-tools.mjs …, ./bin/ai-i18n-tools …, or root pnpm i18n:* scripts (or a shell alias / pnpm add -g .).
• Standalone fixtures (multi-provider, test-markdown) — from the fixture folder, use node ../../bin/ai-i18n-tools.mjs ….

Run pnpm run build at the repository root after changing CLI source. See the Development Guide for build steps and optional global-install workarounds.

On Linux, macOS, and WSL, registry installs set the executable bit on the CLI script automatically. On Windows, package managers generate .cmd and .ps1 shims that invoke Node explicitly.

Next: Quick start.