Adicionar i18n a um site ou site de documentação
Esta página é para um site de documentação (Markdown ou MDX) ou um site de marketing ou estático (um site Astro ou HTML puro) em um único idioma. A ferramenta traduz o conteúdo da sua página com os modelos do seu provedor de LLM e grava uma cópia localizada por idioma. O framework do seu site serve essas cópias e fornece o seletor de idiomas.
Para um aplicativo cujas strings de UI residem em chamadas t(), use Adicionar i18n a um aplicativo JS/TS ou Adicionar i18n a um aplicativo Python em vez disso.
O que você tem?
| Seu site | Modelo de inicialização | Comece aqui |
|---|---|---|
| Astro Starlight ou Astro puro | ui-starlight / strings de UI híbridas | Astro |
| Docusaurus | ui-docusaurus | Docusaurus |
| VitePress | ui-vitepress | VitePress |
| Nextra 4 (Next.js App Router) | ui-nextra | Nextra |
| Fumadocs 4 (Next.js App Router) | ui-fumadocs | Fumadocs |
| Páginas HTML simples | ui-plain-html ou docs-plain-html | Aplicativos HTML simples |
| Nenhum framework de site, apenas um README e arquivos Markdown | docs-markdown, ou qualquer template mais --with-readme | Adicionar i18n ao seu README e documentos Markdown |
Prompts do agente
- Astro Starlight: apenas observações. Arquivos
t()do Astro: prompt de JS/TS (pule o i18next). - Docusaurus: apenas observações (
<Translate>é a própria API do Docusaurus). - VitePress: prompt de catálogo de temas.
- Nextra: prompt de dicionário e prompt
t()híbrido. - Fumadocs: prompt de catálogo de UI.
- Arquivos README e Markdown: prompt de README.
Etapas
A mesma estrutura funciona para todos os frameworks; os detalhes estão no guia do framework referenciado acima.
- Instale a CLI e defina a chave de API: Instalação, Provedor e chave de API.
- Faça o scaffold:
ai-i18n-tools init -t <template> -P <provider>. - Defina
sourceLocale,targetLocalesedocs[].contentPaths(as páginas e pastas escritas no seu idioma de origem).sourceLocalepode ser qualquer idioma. O guia do framework mostra odocsOutput.stylecorreto. - Habilite o i18n do seu próprio framework para que ele sirva e vincule as páginas localizadas. Cada guia tem uma seção "Habilitar i18n em um site existente": VitePress, Docusaurus, Nextra, Fumadocs, Astro.
- Execute
ai-i18n-tools sync(outranslate-docs), depois compile o site. - Verifique uma rota localizada no navegador. O menu suspenso de localidade do próprio framework é o seletor. Para um arquivo markdown simples, como um README, adicione uma linha de links com languageListBlock.
O que é traduzido
Os corpos das páginas sempre passam pelo pipeline de Documentos. O chrome do framework (navegação, barra lateral, rótulos de tema) é tratado na mesma execução quando o framework oferece suporte, e não através do pipeline de JSON separado.
| Framework | Strings do shell e do tema | Como |
|---|---|---|
| Docusaurus | catálogo write-translations ({ message, description }) | docs[].docusaurusCatalogDir mais translate-docs |
| VitePress | Catálogo de tema, navegação e barra lateral | docsOutput.vitepressThemeCatalog mais translate-docs |
| Nextra | Rótulos da barra lateral _meta.ts | Automático com style: "nextra" |
| Nextra | Dicionário de tema .ts | docs[].nextraDictionaryPath |
| Fumadocs | Rótulos da barra lateral meta.json | Automático com style: "fumadocs" |
| Fumadocs | Catálogo de substituições da UI | docsOutput.fumadocsUiCatalog |
| Astro Starlight | Strings de UI integradas em várias localidades | Apenas páginas |
Imagens e capturas de tela não são traduzidas por translate-docs. Para arquivos específicos da localidade, consulte Imagens e capturas de tela.
HTML simples
Duas opções, dependendo de como a página deve se comportar:
- Uma página que alterna o idioma no navegador: marque o texto com atributos
data-i18n*e use o runtime de strings da UI (ui-plain-html). Consulte Aplicativos HTML simples. - Um arquivo HTML traduzido por localidade: use o pipeline de documentos (
docs-plain-html). Consulte Páginas HTML.
Um arquivo pertence a um caminho.
Não é o seu caso?
- Strings da UI do aplicativo: Adicionar i18n a um aplicativo JS/TS ou Adicionar i18n a um aplicativo Python.
- Um README de repositório ao lado do site, ou arquivos Markdown sem um framework de site: Adicionar i18n ao seu README e documentos Markdown.
init … --with-readmeadiciona esse bloco ao lado de um modelo de site. - JSON de localidade aninhado e independente: JSON.
- Tradução de strings de um site e de um aplicativo: Combinação de pipelines.
Referência para as opções compartilhadas e diferenças por framework: Integrações.