Skip to content

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.

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

Executá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:

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

Windows (PowerShell):

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

O 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
PlataformaAtivo
Linux x64ai-i18n-tools-linux-x64.gz
Linux arm64ai-i18n-tools-linux-arm64.gz
macOS arm64ai-i18n-tools-macos-arm64.gz
macOS x64ai-i18n-tools-macos-x64.gz
Windows x64ai-i18n-tools-win-x64.exe.gz
  1. Baixe o ativo que corresponde à máquina, e SHA256SUMS.txt, na página GitHub Releases.
  2. 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 com shasum -a 256 -c -. No Windows, (Get-FileHash -Algorithm SHA256 .\ai-i18n-tools-win-x64.exe.gz).Hash e compare-o com o hash em SHA256SUMS.txt.
  3. 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):

bash
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:

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

Windows (PowerShell). GZipStream faz parte do Windows PowerShell; não há instalação gzip separada:

powershell
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:

bash
# 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 sync

Use 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):

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

Ou 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:

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

Usando 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):

bash
PATH_add node_modules/.bin

Apó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
# bash/zsh — from the project root
export PATH="$PWD/node_modules/.bin:$PATH"
ai-i18n-tools sync
powershell
# Windows PowerShell — from the project root
$env:Path = "$PWD\node_modules\.bin;$env:Path"
ai-i18n-tools sync

Instalação global — instale a CLI uma vez e chame-a de qualquer diretório:

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

Com 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:

json
"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:

  1. Node.js 22.20 ou posterior: npx skills add wsj-br/ai-i18n-tools --all -y instala esses diretórios na pasta de skills do agente.
  2. Pacote já instalado: copie node_modules/ai-i18n-tools/skills/. para essa pasta.
  3. Sem Node.js: extraia package/skills/ do tarball do npm para a versão em ai-i18n-tools --version. A partir do lançamento que o adiciona, ai-i18n-tools-skill.zip nesse 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 apenas ai-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-app e os outros pacotes listados em pnpm-workspace.yaml) — execute pnpm install na raiz do repositório e, em seguida, cd examples/<name>. Use os scripts pnpm run i18n:* do exemplo ou configure o PATH (consulte Como usar a CLI) e execute o ai-i18n-tools … diretamente. Os overrides do workspace vinculam o ai-i18n-tools ao seu checkout local.
  • Raiz do repositório — o pnpm não vincula o bin do próprio pacote raiz ao node_modules/.bin. O .envrc deste checkout adiciona bin/ ao PATH para que o wrapper bin/ai-i18n-tools comitado (ao lado do shim bin/ai-i18n-tools.mjs publicado) forneça o comando diretamente após direnv allow. Sem o direnv, use node bin/ai-i18n-tools.mjs …, ./bin/ai-i18n-tools … ou os scripts pnpm i18n:* da raiz (ou um alias de shell / pnpm add -g .).
  • Fixtures independentes (multi-provider, test-markdown) — na pasta do fixture, use node ../../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.

Lançado sob a Licença MIT.