Instalação
Esta página explica como instalar a CLI e colocar o comando ai-i18n-tools para funcionar. Já o instalou? Acesse o Início rápido.
O pacote publicado é somente ESM. Use import ou import() no Node.js ou no seu empacotador; não use require('ai-i18n-tools'). O pacote declara engines.node >=22.16.0; versões mais antigas do Node.js não são suportadas. O tarball do npm inclui o contexto do consumidor em docs/ai-i18n-tools-context.md e a árvore completa de skills/, não o site de documentação completo; cópias específicas de localidade em translated-docs/ estão no repositório do GitHub.
npm install ai-i18n-tools
# or
pnpm add ai-i18n-tools
# or
yarn add ai-i18n-toolsExecutáveis independentes
Lançamentos do GitHub anexam uma compilação executável única do Node.js. Use esse binário quando o projeto não for executado em Node.js. Projetos Python e .NET executam a mesma CLI a partir dele, incluindo extract, translate-ui e suggest-models, sem instalação do Node.js.
Linux e 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 | iexO instalador detecta o sistema, baixa um arquivo gzip do executável correspondente, verifica SHA256SUMS.txt, o descompacta, instala o comando como ai-i18n-tools (ai-i18n-tools.exe no Windows) e adiciona o diretório de instalação a PATH. Linux e macOS descompactam com gzip. O Windows PowerShell descompacta com o leitor gzip do .NET, que já faz parte do Windows. O diretório padrão é ~/.local/bin. Abra um novo terminal se o comando ainda não for encontrado. Defina AI_I18N_VERSION (por exemplo, v1.11.0) para fixar uma versão, ou AI_I18N_INSTALL_DIR para escolher outro diretório. Uma versão publicada antes dos arquivos gzip ainda tem o executável bruto, e o instalador aceita esse arquivo.
Os binários não são autenticados (notarised) nem assinados com Authenticode. O macOS pode pedir que você aprove um programa não assinado. O Windows SmartScreen pode exibir um aviso. O instalador do macOS limpa o sinalizador de quarentena após a correspondência do checksum.
Cada lançamento também anexa SHA256SUMS.txt, ai-i18n-tools-python-examples.zip (os quatro exemplos Python) e ai-i18n-tools-dotnet-examples.zip (dotnet-console, dotnet-resx e os auxiliares assets/dotnet que esses projetos compilam). Lançamentos publicados antes do arquivo .NET não o incluem. A partir do lançamento que adiciona o arquivo de skill, a mesma página inclui ai-i18n-tools-skill.zip, cada diretório de skill do coding-agent. Lançamentos publicados antes desse zip de skill não o incluem, e o primeiro zip de skill contém apenas ai-i18n-tools/. install.sh e install.ps1 permanecem na raiz do repositório, e os comandos acima os baixam de lá. O tarball npm e o executável não contêm os arquivos de exemplo ou o zip de skill. Os exemplos permanecem no repositório. Os diretórios de skill estão dentro do tarball npm. Consulte Skill do coding-agent.
Instruções para instalar manualmente o executável ai-i18n-tools
| Plataforma | Ativo |
|---|---|
| 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 |
- Baixe o ativo que corresponde à máquina, e
SHA256SUMS.txt, na página GitHub Releases. - Verifique o checksum do arquivo gzip. No Linux,
grep ' ai-i18n-tools-linux-x64.gz$' SHA256SUMS.txt | sha256sum -c -(use o nome do ativo que você baixou). No macOS, a mesma linha comshasum -a 256 -c -. No Windows,(Get-FileHash -Algorithm SHA256 .\ai-i18n-tools-win-x64.exe.gz).Hashe compare-o com o hash emSHA256SUMS.txt. - Descompacte o arquivo e coloque o comando em
PATH.
Linux e macOS, usando o recurso do Linux x64 como exemplo (substitua pelo recurso que você baixou):
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"Se $HOME/.local/bin ainda não estiver em PATH, adicione isto ao perfil do seu shell (.bashrc, .bash_profile, .profile ou .zshrc) e abra um novo terminal:
export PATH="$HOME/.local/bin:$PATH"Windows (PowerShell). GZipStream faz parte do Windows PowerShell; não há instalação gzip separada:
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")
}Abra um novo terminal e execute ai-i18n-tools --version. O nome do comando é ai-i18n-tools em todas as plataformas.
Defina a chave de API para o provedor ativo da mesma forma que uma instalação npm (veja abaixo). Em seguida, escolha o modelo init para o projeto e traduza. Um projeto Python usa -t ui-python. Um projeto .NET usa -t ui-dotnet. Um aplicativo que já carrega strings com ResourceManager ou IStringLocalizer usa -t ui-dotnet-resx. Execute uma linha 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 syncUse init apenas para uma nova configuração: ele sobrescreve o arquivo de configuração selecionado. Para projetos existentes, edite a configuração em vez disso. sync lida com todos os pipelines de tradução configurados/habilitados, incluindo a extração da interface do usuário.
Passo a passo: Adicionar i18n a um aplicativo Python, Adicionar i18n a um aplicativo .NET e Adicionar i18n a um aplicativo .NET ResourceManager. Referência de comando: suggest-models.
Definir a chave de API
Os comandos de tradução (translate-ui, translate-docs, translate-json, translate-svg, sync) exigem a configuração do provedor em ai-i18n-tools.config.json e uma chave de API para o provedor ativo. Execute ai-i18n-tools init -P <provider> para gerar essa predefinição. Predefinições de provedor e chaves de API: Provedores de LLM. A lista de modelos de init é um ponto de partida. Substitua-a por modelos de Modelos de IA usando suggest-models ou a aba Modelos do painel. Ollama é a única predefinição integrada que não precisa de chave de API.
Defina a chave que corresponde ao provedor que você passa para init (consulte a tabela de predefinições):
# init -P openrouter
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# init -P openai
# export OPENAI_API_KEY=sk-your-key-hereOu crie um arquivo .env ou .env.local ao lado de ai-i18n-tools.config.json. Esses arquivos são lidos apenas quando nenhuma chave de API do provedor já está definida:
OPENROUTER_API_KEY=sk-or-v1-your-key-hereUsando a CLI
Instale ai-i18n-tools como uma dependency ou devDependency em seu projeto (consulte o topo desta página). Se o código do aplicativo importar ai-i18n-tools/runtime, mantenha-o disponível no ambiente de tempo de execução/compilação de produção; uma CLI global ou binário autônomo não pode satisfazer essa importação. O pacote declara uma entrada bin que seu gerenciador de pacotes vincula a node_modules/.bin/ai-i18n-tools. Esse shim (bin/ai-i18n-tools.mjs dentro do pacote instalado) carrega a CLI compilada.
Para digitar o comando ai-i18n-tools em um shell interativo, configure uma das opções abaixo. Sem configuração, o shell não consegue encontrar o binário mesmo após uma instalação local.
direnv — adicione a um .envrc na raiz do projeto (bash/zsh; consulte direnv.net):
PATH_add node_modules/.binApós direnv allow, o comando simples estará disponível sempre que você cd no projeto.
PATH manual — execute estes comandos na raiz do projeto (o diretório que contém node_modules/.bin). Os subdiretórios continuarão funcionando desde que você mantenha essa entrada PATH; executar novamente a exportação de uma pasta aninhada falhará porque $PWD não apontará mais para a raiz do projeto.
# 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 syncInstalação global — instale a CLI uma vez e chame-a de qualquer diretório:
npm install -g ai-i18n-tools
# or
pnpm add -g ai-i18n-toolsCom pnpm, execute pnpm setup uma vez por máquina (e abra um novo shell) se os comandos globais estiverem faltando — pnpm requer seu diretório bin global em PATH. Uma instalação global usa a versão globalmente fixada. Para fixação de versão por projeto, prefira direnv ou PATH manual para que node_modules/.bin seja resolvido para a dependência do projeto.
Atualize uma instalação existente com ai-i18n-tools upgrade. O comando exibe a nova versão e aguarda por y. --yes ignora o prompt. Uma dependência de projeto é atualizada em package.json e instalada com npm, pnpm, yarn ou bun. Uma instalação global do Node.js usa a instalação global desse gerenciador de pacotes. Um executável autônomo é substituído pela compilação do GitHub Release para o sistema operacional e arquitetura atuais depois que o checksum SHA256 corresponde. Consulte upgrade.
Scripts do package.json — quando o npm ou pnpm executa um script, ele anexa node_modules/.bin ao início de PATH, de modo que o nome simples do comando funcione dentro dos scripts sem alterações no PATH do shell:
"scripts": {
"i18n:extract": "ai-i18n-tools extract",
"i18n:sync": "ai-i18n-tools sync",
"i18n:dashboard": "ai-i18n-tools dashboard"
}Em seguida, execute, por exemplo, pnpm run i18n:sync. Consulte Scripts recomendados para package.json para ver o conjunto completo recomendado.
Alternativas — se você preferir não ajustar o PATH: npx ai-i18n-tools … (npm) ou pnpm exec ai-i18n-tools … (pnpm). Para uma execução única sem instalação e sem entrada no package.json: npx ai-i18n-tools <cmd> ou pnpm dlx ai-i18n-tools <cmd>.
Skill do agente de codificação
A instalação do pacote npm ou do executável autônomo não registra a skill com um agente. Os métodos de instalação, catálogos nativos e agentes que não possuem pasta de skill estão em Skill do agente de codificação.
Obtenha cada diretório de skill, cada um uma pasta que contém SKILL.md, sem clonar este repositório:
- Node.js 22.20 ou posterior:
npx skills add wsj-br/ai-i18n-tools --all -yinstala esses diretórios na pasta de skills do agente. - Pacote já instalado: copie
node_modules/ai-i18n-tools/skills/.para essa pasta. - Sem Node.js: extraia
package/skills/do tarball do npm para a versão emai-i18n-tools --version. A partir do lançamento que o adiciona,ai-i18n-tools-skill.zipnesse Lançamento do GitHub contém os mesmos diretórios. Lançamentos publicados antes do zip não o incluem. O primeiro zip contém apenasai-i18n-tools/.
Comandos e as pastas do agente estão em Skill do agente de codificação.
Monorepo clonado
Ao desenvolver o pacote ou executar exemplos do workspace a partir de um clone completo de ai-i18n-tools:
- Exemplos do workspace (
examples/console-app,examples/nextjs-appe os outros pacotes listados empnpm-workspace.yaml) — executepnpm installna raiz do repositório e, em seguida,cd examples/<name>. Use os scriptspnpm run i18n:*do exemplo ou configure o PATH (consulte Como usar a CLI) e execute oai-i18n-tools …diretamente. Osoverridesdo workspace vinculam oai-i18n-toolsao seu checkout local. - Raiz do repositório — o pnpm não vincula o
bindo próprio pacote raiz aonode_modules/.bin. O.envrcdeste checkout adicionabin/aoPATHpara que o wrapperbin/ai-i18n-toolscomitado (ao lado do shimbin/ai-i18n-tools.mjspublicado) forneça o comando diretamente apósdirenv allow. Sem o direnv, usenode bin/ai-i18n-tools.mjs …,./bin/ai-i18n-tools …ou os scriptspnpm i18n:*da raiz (ou um alias de shell /pnpm add -g .). - Fixtures independentes (
multi-provider,test-markdown) — na pasta do fixture, usenode ../../bin/ai-i18n-tools.mjs ….
Execute pnpm run build na raiz do repositório após alterar a origem da CLI. Consulte o Guia de Desenvolvimento para etapas de construção e soluções alternativas de instalação global opcionais.
No Linux, macOS e WSL, as instalações do registro definem automaticamente o bit executável no script CLI. No Windows, os gerenciadores de pacotes geram .cmd e .ps1 shims que invocam o Node explicitamente.
A seguir: Início rápido.