Skip to content

Integração Astro ​

Use ai-i18n-tools com Astro em duas configurações comuns: sites de documentação Astro Starlight e sites de marketing ou aplicativos Astro simples. Ambos usam Documentos (translate-docs) para o conteúdo da página; sites Astro simples geralmente combinam isso com strings de UI (extract / translate-ui) para strings t() em frontmatter e dados compartilhados.

Consulte também strings da UI, Documentos e os exemplos executáveis abaixo.

Astro Starlight ​

Use init -t ui-starlight e docsOutput.style: "astro-starlight" para sites de documentação do Astro Starlight. A predefinição é um alias para doc-system com um localeSubpath vazio — as páginas traduzidas ficam em src/content/docs/<locale>/ ao lado da árvore de localidade de origem. sourceLocale pode ser qualquer idioma.

Início rápido ​

bash
ai-i18n-tools init -t ui-starlight -P cheaperinference
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm dev             # Starlight dev server (project-specific script)

Layout da página ​

Markdown e MDX em inglês ficam na raiz do conteúdo do Starlight (geralmente src/content/docs/). Cópias traduzidas são escritas ao lado da árvore de origem:

text
src/content/docs/quick-start.md     →  src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx    →  src/content/docs/fr/guide/setup.mdx

Configure um bloco docs[]:

json
{
  "contentPaths": ["src/content/docs/"],
  "outputDir": "src/content/docs",
  "docsOutput": {
    "style": "astro-starlight",
    "docsRoot": "src/content/docs"
  }
}

Aponte contentPaths para os arquivos e diretórios .md / .mdx escritos em sourceLocale. Esse pode ser qualquer idioma. Defina docsRoot para a mesma pasta que o Starlight usa como sua raiz de conteúdo.

As substituições da UI do Starlight podem usar src/content/i18n/en.json com jsonPathTemplate em um bloco docs[] separado quando necessário — consulte Documentos — inicializar para documentação.

O Starlight fornece strings de UI integradas para muitos idiomas (rótulos de navegação, placeholder de pesquisa, sumário e assim por diante). Não há um pipeline separado de shell/tema para configurar — use translate-docs apenas para o conteúdo da página. Para outros frameworks, consulte Tradução do shell do Framework.

labels explícitos da barra lateral, o title do site e social[].label em astro.config.mjs são literais em inglês que esta ferramenta não traduz. Prefira entradas slug para que o rótulo venha do frontmatter traduzido da página (title). Um grupo ou um link externo que precisa de seu próprio texto usa o mapa translations por localidade do Starlight (label para a localidade padrão, translations['pt-BR'] para as outras). social[].label não tem um campo de traduções no esquema atual do Starlight; ele permanece como está escrito. Consulte a barra lateral do Starlight e examples/astro-docs/astro.config.mjs, que usa entradas slug.

Habilitar i18n em um site existente ​

A configuração inicial utiliza o prompt em Adicionar i18n a um site ou site de documentação. A lista de verificação abaixo é o mesmo trabalho feito manualmente.

  • locales na configuração do Starlight, incluindo uma entrada root quando o inglês não deve ter prefixo (label e o lang obrigatório).
  • defaultLocale: 'root' quando o idioma padrão é essa localidade raiz. Omita defaultLocale somente se o padrão do Starlight já corresponder.
  • As páginas em inglês permanecem em src/content/docs/; translate-docs grava em src/content/docs/<locale>/.
  • targetLocales alinhado com as chaves de localidade não raiz (atenção às maiúsculas e minúsculas: as chaves de diretório do Starlight geralmente são minúsculas, como pt-br).

Projeto de exemplo ​

examples/astro-docs — fontes em inglês em src/content/docs/, traduções commitadas em src/content/docs/<locale>/, localidade RTL (ar) e tradução orientada por glossário. Execute pnpm dev na porta 3050.

Astro simples (sites de marketing e aplicativos) ​

Para sites estáticos de marketing ou aplicativos Astro (não Starlight), combine Roteamento i18n integrado do Astro com ai-i18n-tools. A configuração inicial utiliza o prompt em Adicionar i18n a um site ou site de documentação. A implementação de referência é examples/astro-website: Inglês em /, locales de destino em /{locale}/.

A maioria das equipes usa um híbrido de dois pipelines na mesma página:

PipelineUso paraComandosSaída
HTML da páginaCabeçalhos, parágrafos, rótulos de navegação, arrays embutidos no corpo do templatetranslate-docssrc/pages/{locale}/index.astro por localidade
Strings da UI (t())Dados do frontmatter, rótulos de abas, arrays compartilhadosextract → translate-uipublic/locales/{locale}.json (string do idioma de origem como chave)

Início rápido ​

bash
ai-i18n-tools init -t ui-astro-website -P ollama
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm dev

Estruture a extração da UI com init -t ui-astro-website -P ollama, depois mescle em um bloco docs[] quando você também traduzir o HTML da página:

json
{
  "features": {
    "translateUIStrings": true,
    "translateDocs": true
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "public/locales/strings.json",
    "flatOutputDir": "public/locales/"
  },
  "docs": [{
    "contentPaths": ["src/pages/index.astro"],
    "outputDir": "src/pages",
    "docsOutput": {
      "style": "astro-starlight",
      "docsRoot": "src/pages"
    },
    "addFrontmatter": false
  }]
}

Mantenha três listas alinhadas ao adicionar ou remover um idioma: targetLocales em ai-i18n-tools.config.json, i18n.locales em astro.config.mjs (Astro usa códigos de rota em minúsculas, como pt-br), e ui-languages.json (via generate-ui-languages). Os nomes de arquivo do pacote plano usam o casing da configuração (pt-BR.json); mapeie a rota pt-br do Astro para esse arquivo através do campo code do seu manifesto.

Resolva t('…') em tempo de compilação procurando o literal do idioma de origem como a chave — consulte examples/astro-website/src/i18n/t.ts. sourceLocale pode ser qualquer idioma. O exemplo usa inglês. Você não precisa de ai-i18n-tools/runtime ou i18next para um site estático, a menos que você adicione ilhas de cliente que trocam de idioma após o carregamento.

Projeto de exemplo ​

examples/astro-website — página de destino híbrida com HTML via translate-docs e rótulos de guia de captura de tela via t() + translate-ui.

Projetos de exemplo ​

ProjetoCaso de usoPorta
examples/astro-docsDocumentação Starlight3050
examples/astro-websiteSite de marketing Astro simples (HTML + híbrido t())(ver README)

Compare examples/astro-docs com examples/docusaurus-docs — conteúdo de tutorial semelhante, estilo de saída do Docusaurus em vez de Starlight.

Lançado sob a Licença MIT.