Skip to content

Início rápido ​

Esta página guia um projeto de idioma único para seus primeiros arquivos traduzidos. É para um aplicativo JS/TS, um aplicativo Python, um aplicativo .NET, um site ou site de documentação, ou um README de repositório e outros arquivos Markdown. Ela assume:

  • Node.js >=22.16.0, ou o executável autônomo para um projeto Python ou .NET.
  • Uma chave de API para um provedor de LLM, ou uma instalação local do Ollama.
  • O projeto está em controle de versão, para que você possa revisar o que a ferramenta escreve.

Duas coisas diferem entre os projetos: como a ferramenta encontra seu texto e como seu app carrega o resultado. A seção Escolha seu caminho abaixo direciona você para o guia certo para isso.

Exemplos executáveis ​

Prefere ver um projeto finalizado primeiro? Copie um sem clonar o repositório:

bash
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:sync

Substitua console-app por qualquer outro exemplo de Node.js. Os exemplos de Python e .NET não têm package.json; copie-os da mesma forma. Os quatro exemplos de Python também estão em ai-i18n-tools-python-examples.zip na Versão do GitHub, e os dois exemplos de .NET estão em ai-i18n-tools-dotnet-examples.zip. A lista completa, com o que cada um mostra, está na página Exemplos.

Instalar ​

bash
pnpm add -D ai-i18n-tools

npm install --save-dev ai-i18n-tools e yarn add --dev ai-i18n-tools também funcionam. Projetos Python e .NET instalam o executável autônomo e não precisam de Node.js. Linux e 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. Outras opções de instalação: Instalação.

Provedor e chave de API ​

Todo comando que chama um LLM (translate-ui, translate-docs, translate-json, translate-svg e sync) precisa de ambos:

  1. Pelo menos um provedor em ai-i18n-tools.config.json: um bloco providers.<name> com translationModels, e uma chave provider de nível superior quando mais de um provedor é configurado. init -P <provider> estrutura essa predefinição. Para adicionar provedores, consulte Provedores de LLM. Para escolher a lista de modelos, consulte Modelos de IA.
  2. A chave de API correspondente em seu ambiente, ou em .env / .env.local ao lado de ai-i18n-tools.config.json quando nenhuma chave de API do provedor já está definida. Cada predefinição integrada lê uma variável nomeada da tabela de predefinições, por exemplo, OPENROUTER_API_KEY com -P openrouter ou OPENAI_API_KEY com -P openai. Ollama usa um endpoint local e não precisa de chave.
bash
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

extract, status e outros comandos que não chamam o LLM não precisam de nenhum dos dois. Mais sobre arquivos de ambiente e PATH: Instalação.

Escolha seu caminho ​

Identifique o que você tem, execute os comandos no bloco correspondente e depois continue no guia vinculado.

Um app JS/TS ​

Seus botões e mensagens ainda são texto simples no código-fonte, então a ferramenta ainda não tem o que encontrar. Eles precisam primeiro ser envolvidos em t(), e o app precisa de um pequeno arquivo de configuração do i18next.

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --apply

Depois, siga o guia Adicionar i18n a um app JS/TS. Ele aborda a etapa de envolvimento, com um prompt de agente, antes de extract e translate-ui.

Um app Python ​

bash
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --apply

Em seguida, siga Adicionar i18n a um aplicativo Python.

Um aplicativo Django, Flask com catálogos Flask-Babel, ou um aplicativo que já chama gettext mantém essas chamadas. Estruture com ui-python-django, ui-python-flask ou ui-python-gettext em vez disso, e então siga Adicionar i18n a um aplicativo Django / Python gettext.

Um aplicativo .NET ​

bash
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --apply

Em seguida, siga Adicionar i18n a um aplicativo .NET. Um aplicativo que já usa ResourceManager ou IStringLocalizer usa ui-dotnet-resx em vez disso, então Adicionar i18n a um aplicativo .NET ResourceManager. migrate-dotnet-i18n reescreve T($"…") em chamadas {0} numeradas. --wrap audita rótulos XAML e C# não marcados. O relatório lista chaves resx nomeadas, como Resources.LoginButton, como sugestões e não edita essas linhas.

Um site ou site de documentação ​

Escolha o template para seu framework:

Seu siteTemplate
Astro Starlightui-starlight
Docusaurusui-docusaurus
VitePressui-vitepress
Nextraui-nextra
Fumadocsui-fumadocs
Site Astro simplesui-astro-website
Páginas HTML simplesui-plain-html ou docs-plain-html
bash
ai-i18n-tools init -t ui-vitepress -P openrouter

Em seguida, siga Adicionar i18n a um site ou site de documentação. Seu prompt de agente habilita o roteamento i18n do framework. Você executa sync após revisar esse trabalho.

Um README ou documentos Markdown ​

A maioria dos repositórios quer isso junto com o aplicativo: o template padrão ui-markdown já inclui um bloco README simples. Para qualquer outro template, adicione --with-readme. Um repositório apenas com Markdown usa docs-markdown.

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouter

Em seguida, siga Adicionar i18n ao seu README e documentos Markdown. Cole o marcador da lista de idiomas em README.md antes de sync. O caminho do aplicativo, se você tiver um, ainda é Adicionar i18n a um aplicativo JS/TS, Adicionar i18n a um aplicativo Python, ou Adicionar i18n a um aplicativo .NET.

Outros ​

A lista completa de templates, com todas as opções de init, está na Referência de configuração da CLI.

Executar e verificar ​

Quando seu projeto estiver pronto:

bash
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools status

doctor verifica se a configuração, caminhos, provedores e ambiente estão prontos. Ele também verifica IDs de modelo com o provedor, a menos que você passe --local. sync executa cada etapa que sua configuração habilita, em ordem. status mostra o que é traduzido por localidade. Uma primeira execução em um projeto onde a ferramenta não consegue ver texto termina sem erro e não escreve nada útil, então se status não mostrar nenhuma string, volte ao guia para o seu caminho.

suggest-models classifica os modelos de chat do provedor ativo com base em benchmarks publicados. suggest-models --apply substitui translationModels e não altera uiModels e localeModels. A mesma classificação está na guia Modelos do painel. Como a classificação funciona e por que a lista contém mais de um modelo: Modelos de IA. Referência de comando: suggest-models.

Mantenha traduzido ​

Reexecute sync sempre que o texto de origem mudar. Um cache SQLite significa que apenas o texto novo ou alterado vai para o modelo, então as reexecuções são baratas. Executar sync em CI evita que as traduções se desalinhem. ai-i18n-tools dashboard abre o Painel de Tradução para revisar e editar as traduções em cache.

Scripts recomendados para package.json ​

Com o pacote instalado localmente, os scripts resolvem ai-i18n-tools de node_modules/.bin sem configuração extra do shell. Para um shell interativo, configure o PATH primeiro: consulte Como usar a CLI.

json
{
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:status": "ai-i18n-tools status",
  "i18n:statistics": "ai-i18n-tools statistics",
  "i18n:dashboard": "ai-i18n-tools dashboard",
  "i18n:cleanup": "ai-i18n-tools cleanup"
}

Prefira sync em vez de encadear os scripts de tradução individuais. Use os scripts de etapa única apenas quando precisar de uma etapa isoladamente.

Para exibir a saída da CLI e o painel em outro idioma, passe -L <code> ou defina AI_I18N_LANG: consulte Idioma da interface da ferramenta.

Traduzindo mais de um tipo de conteúdo, como strings de aplicativos e um site de documentação juntos? Consulte Como combinar pipelines.

A seguir: o guia para o seu caminho em Escolha seu caminho.

Lançado sob a Licença MIT.