Integração Nextra

Use init -t ui-nextra e docsOutput.style: "nextra" para sites de documentação Nextra 4 no Next.js App Router. O preset é um alias para doc-system com um localeSubpath vazio e nomes de pastas de localidade BCP-47 preservados (localePathLowercase assume o padrão false, então as pastas permanecem pt-BR, zh-Hans, etc.).

Veja também Documentos e a demonstração executável examples/nextra-docs.

Início rápido

ai-i18n-tools init -t ui-nextra [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm run build       # Next.js build (project-specific script)

Habilite features.translateDocs ao traduzir o conteúdo da página, os rótulos da barra lateral _meta.ts e os módulos do dicionário de temas em uma execução sync.

Layout da página

Nextra 4 com i18n mantém MDX de origem em inglês em uma pasta de localidade (geralmente content/en/). Cópias traduzidas são gravadas em pastas de localidade irmãs:

content/en/index.mdx              →  content/pt-BR/index.mdx
content/en/guide/getting-started.mdx  →  content/zh-Hans/guide/getting-started.mdx

Configure um bloco docs[]:

{
  "contentPaths": ["content/en"],
  "outputDir": "content",
  "docsOutput": {
    "style": "nextra",
    "docsRoot": "content/en",
    "rewriteNextraLinks": true
  }
}

Aponte contentPaths para seus arquivos e diretórios .mdx em inglês. Defina docsRoot para a pasta de localidade em inglês dentro de content/.

Conecte a internacionalização do Nextra: defina i18n.locales e defaultLocale em next.config, e mantenha targetLocales em ai-i18n-tools.config.json alinhado com esses códigos de localidade e os nomes das pastas content/{locale}/.

Strings do tema

O "chrome" do tema Nextra (editLink, placeholder de pesquisa, rodapé e assim por diante) não é extraído do markdown. Crie strings em inglês em um módulo de dicionário TypeScript (por exemplo, app/_dictionaries/en.ts) e traduza-o dentro de translate-docs:

{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "contentPaths": ["content/en"],
      "outputDir": "content",
      "nextraDictionaryPath": "app/_dictionaries/en.ts",
      "docsOutput": {
        "style": "nextra",
        "docsRoot": "content/en"
      }
    }
  ]
}

A ferramenta grava app/_dictionaries/{locale}.ts (modelo padrão: {dir}/{locale}.ts). Carregue o módulo por localidade em app/_dictionaries/get-dictionary.ts e passe as strings traduzidas para <Layout>, <Search>, <Footer> e componentes de tema relacionados.

Não use json[] para strings de dicionário de tema Nextra — esse padrão é apenas para pacotes de localidade de aplicativos não relacionados.

Rótulos da barra lateral (_meta.ts)

Nextra 3+ usa arquivos TypeScript _meta.ts / _meta.tsx para estrutura e títulos da barra lateral. Quando docsOutput.style é "nextra", translate-docs coleta automaticamente _meta.ts, _meta.tsx e _meta.js em docsRoot, traduz literais de string no mapa meta export default { … } e grava arquivos espelhados em content/{locale}/**.

Padrão recomendado: mantenha literais em inglês em linha em content/en/**/_meta.ts (o mesmo que swr-site):

content/en/_meta.ts           English sidebar labels (source)
content/pt-BR/_meta.ts        Translated copy (generated by translate-docs)

Opcional: substitua a coleta com docs[].nextraMetaGlob ou restrinja os nomes de propriedades traduzíveis com docs[].nextraMetaTranslatableKeys (padrão: title, display, breadcrumb).

Não crie sidecars JSON (i18n/meta.en.json) ou arquivos _meta.ts finos que importam JSON traduzido — regenere arquivos _meta de localidade com sync / translate-docs quando o inglês mudar.

Projeto de exemplo

examples/nextra-docs — Fontes em inglês em content/en/, árvores de páginas pt-BR e zh-Hans confirmadas, arquivos _meta.ts embutidos e app/_dictionaries/{locale}.ts. Execute pnpm run dev na porta 3070.

Opcional: t() para app/ React (híbrido)

Padrão: Strings literais de objeto _meta.ts / _meta.tsx são traduzidas dentro de translate-docs — nenhum t() é necessário.

Híbrido opcional: as equipes podem usar adicionalmente t() + translate-ui para o layout app/, componentes MDX personalizados ou rótulos _meta.tsx que vivem apenas dentro de corpos de componentes JSX (além da extração de literais de objeto na v1). Isso não substitui o translate-meta para arquivos meta, a menos que você refatore explicitamente os rótulos da barra lateral em componentes.

Conteúdo	Pipeline padrão	Alternativa opcional
Corpos de página MDX	translate-docs	—
Títulos de objeto _meta.ts / _meta.tsx	translate-docs	refatorar para t() em JSX (híbrido)
Layout app/, _components/	nextraDictionaryPath + dicionário .ts	t() + translate-ui

Exemplo de prompt de agente de IA (copie para o Cursor ou outro agente de codificação ao migrar o layout para t()):

Add i18n to our Nextra 4 app/ layout using ai-i18n-tools translate-ui (optional hybrid).

Context:
- We already translate MDX pages and _meta.ts via translate-docs (default).
- We want t() in app/[lang]/layout.tsx and app/_components/ for labels not covered by nextraDictionaryPath.
- English-as-key: t("Edit this page on GitHub") in source; strings.json + locales/{locale}.json from extract + translate-ui.
- Do not move _meta.ts sidebar labels into t() unless we explicitly ask — translate-docs handles _meta object literals.

Requirements:
1. Wire getRequestConfig / i18n provider for the app router locale param.
2. Replace hard-coded layout strings with t() calls; keep structure and Nextra theme APIs unchanged.
3. Enable features.translateUIStrings, set ui.sourceRoots to app/ (and mdx-components if needed).
4. Do not duplicate dictionary.ts strings that nextraDictionaryPath already translates — pick one approach per string.

After editing: run extract, translate-ui (or sync), verify en + one target locale in dev.

Convenções de link

O Nextra serve rotas com prefixo de localidade via Next.js i18n (/guide/getting-started, /pt-BR/guide/getting-started). Os links na página devem permanecer neutros em relação à localidade (/guide/getting-started) para que o Next.js possa prefixar a localidade ativa automaticamente.

Habilite o normalizador integrado para que translate-docs corrija os links em cada arquivo traduzido automaticamente:

"docsOutput": {
  "style": "nextra",
  "docsRoot": "content/en",
  "rewriteNextraLinks": true
}

rewriteNextraLinks é ativado por padrão quando style é "nextra".

Autor na fonte em inglês	Após o normalizador
[Guide](content/en/guide/getting-started.mdx)	[Guide](/pt-BR/guide/getting-started)
[Guide](/pt-BR/guide/getting-started.mdx)	[Guide](/pt-BR/guide/getting-started)
[Demo](https://github.com/org/repo)	inalterado (URL completa)

Regras de autoria

• Links de documentos entre páginas: use rotas de site neutras em relação à localidade (/guide/…) em MDX em inglês, ou caminhos content/en/… / .mdx relativos e deixe o normalizador reescrevê-los durante sync.
• Arquivos de repositório fora da árvore de conteúdo: use URLs completas.
• Não edite links manualmente em content/<locale>/ — regenere com sync / translate-docs.

Proxy de localidade opcional

O Nextra fornece um proxy de detecção de localidade para sites i18n. Exporte-o de proxy.ts na raiz do seu projeto:

export { proxy } from 'nextra/locales'

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest|_pagefind).*)',
  ],
}

Códigos de localidade do site vs sourceLocale: Nextra e Next.js usam códigos de rota curtos (en, pt-BR, zh-Hans) em next.config, content/{locale}/ e no cookie NEXT_LOCALE. sourceLocale em ai-i18n-tools.config.json pode ser uma tag BCP-47, como en-GB, para qualidade de tradução — essa tag não é uma rota de site. Se o cookie do navegador ou Accept-Language resolver para uma tag fora de i18n.locales (por exemplo, en-GB quando apenas en está configurado), o proxy padrão do Nextra pode redirecionar em loop. A demonstração examples/nextra-docs envolve nextra/locales para redefinir cookies e caminhos inválidos para a localidade padrão do site antes de delegar.

Isso não funciona com exportações estáticas output: 'export'. Consulte Documentos i18n do Nextra.

Consulte também Configuração — docsOutput e Layouts de saída.