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 Astro Starlight. O preset é um alias para doc-system com um localeSubpath vazio — páginas traduzidas ficam em src/content/docs/<locale>/ ao lado da árvore de origem em inglês.

Início rápido

ai-i18n-tools init -t ui-starlight [-P <provider>]
# 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:

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[]:

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

Aponte contentPaths para seus arquivos e diretórios .md / .mdx em inglês. 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.

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 implementação de referência é examples/astro-website: inglês em /, localidades de destino em /{locale}/.

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

Pipeline	Uso para	Comandos	Saída
HTML da página	Cabeçalhos, parágrafos, rótulos de navegação, arrays embutidos no corpo do template	translate-docs	src/pages/{locale}/index.astro por localidade
Strings de interface (t())	Dados frontmatter, rótulos de abas, arrays compartilhados	extract → translate-ui	public/locales/{locale}.json (fonte em inglês como chave)

Início rápido

ai-i18n-tools init -t ui-astro-website [-P <provider>]
# 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, depois mescle em um bloco docs[] quando você também traduzir o HTML da página:

{
  "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('…') no tempo de compilação procurando o literal da fonte em inglês como a chave — consulte examples/astro-website/src/i18n/t.ts. Você não precisa de ai-i18n-tools/runtime ou i18next para um site estático, a menos que adicione ilhas de cliente que mudam 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

Projeto	Caso de uso	Porta
examples/astro-docs	Documentação Starlight	3050
examples/astro-website	Site 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.