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:
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:syncSubstitua 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
pnpm add -D ai-i18n-toolsnpm 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:
- Pelo menos um provedor em
ai-i18n-tools.config.json: um blocoproviders.<name>comtranslationModels, e uma chaveproviderde 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. - A chave de API correspondente em seu ambiente, ou em
.env/.env.localao lado deai-i18n-tools.config.jsonquando 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_KEYcom-P openrouterouOPENAI_API_KEYcom-P openai. Ollama usa um endpoint local e não precisa de chave.
export OPENROUTER_API_KEY=sk-or-v1-your-key-hereextract, 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.
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --applyDepois, 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
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --applyEm 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
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --applyEm 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 site | Template |
|---|---|
| Astro Starlight | ui-starlight |
| Docusaurus | ui-docusaurus |
| VitePress | ui-vitepress |
| Nextra | ui-nextra |
| Fumadocs | ui-fumadocs |
| Site Astro simples | ui-astro-website |
| Páginas HTML simples | ui-plain-html ou docs-plain-html |
ai-i18n-tools init -t ui-vitepress -P openrouterEm 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.
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 openrouterEm 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
- JSON i18next aninhado que permanece como está:
ai-i18n-tools init -t ui-json-bundles -P openrouter, depois JSON. - Diagramas SVG com rótulos de texto: Tradução de SVG.
- Saindo do Intlayer: Migrando do Intlayer.
- Mantendo o Intlayer e apenas preenchendo suas traduções: Traduzindo o Intlayer no local.
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:
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools statusdoctor 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.
{
"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.