Integração com Fumadocs

Use init -t ui-fumadocs e docsOutput.style: "fumadocs" para sites de documentação Fumadocs 4 no Next.js App Router. O preset é um alias para doc-system com um localeSubpath vazio e códigos de localidade BCP-47 ou curtos preservados (localePathLowercase assume false por padrão).

Consulte também Documentos e a demonstração executável examples/fumadocs-docs (dot parser, porta 3080).

Início rápido

ai-i18n-tools init -t ui-fumadocs [-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.json e as substituições da interface do usuário do Fumadocs em uma única execução de sync.

Layout da página

Fumadocs suporta dois layouts de conteúdo i18n via docsOutput.fumadocsParser. O parser dot é o padrão (Fumadocs integrado e sites de produção como SWR).

Analisador Dot (padrão)

O MDX em inglês reside na raiz da coleção. Cópias traduzidas usam um sufixo de localidade no mesmo diretório:

content/docs/index.mdx                    →  content/docs/index.pt.mdx
content/docs/guide/getting-started.mdx    →  content/docs/guide/getting-started.zh.mdx

{
  "contentPaths": ["content/docs"],
  "outputDir": "content/docs",
  "docsOutput": {
    "style": "fumadocs",
    "docsRoot": "content/docs",
    "fumadocsParser": "dot",
    "rewriteFumadocsLinks": true
  }
}

Alinhe targetLocales com defineI18n().languages em lib/i18n.ts exatamente (o exemplo usa códigos curtos pt e zh).

Dir parser (estilo Nextra)

Para equipes acostumadas a pastas de localidade (content/docs/en/ → content/docs/pt-BR/), defina fumadocsParser como "dir":

content/docs/en/index.mdx           →  content/docs/pt-BR/index.mdx
content/docs/en/guide/foo.mdx       →  content/docs/zh-Hans/guide/foo.mdx

{
  "contentPaths": ["content/docs/en"],
  "outputDir": "content/docs",
  "docsOutput": {
    "style": "fumadocs",
    "docsRoot": "content/docs/en",
    "fumadocsParser": "dir",
    "rewriteFumadocsLinks": true
  }
}

Consulte ai-i18n-tools.config.dir.example.json em examples/fumadocs-docs para uma configuração de diretório de copiar e colar. O modelo mental corresponde à integração Nextra.

Barra lateral (meta.json)

Fumadocs usa arquivos JSON meta.json para a estrutura e títulos da barra lateral. Quando docsOutput.style é "fumadocs", translate-docs coleta meta.json sob docsRoot (ou docs[].fumadocsMetaGlob), traduz valores de string para chaves listadas em docs[].fumadocsMetaTranslatableKeys (padrão: title, description) e escreve as saídas de localidade:

Parser	Fonte em inglês	Saída
dot	content/docs/**/meta.json	content/docs/**/meta.{locale}.json
dir	content/docs/en/**/meta.json	content/docs/{locale}/**/meta.json

Não traduza arrays de slug pages, root, icon, defaultOpen ou outras chaves estruturais — apenas rótulos legíveis por humanos.

Catálogo da UI

O "chrome" do layout do Fumadocs (espaço reservado para pesquisa, nomes de exibição de localidade e outras substituições de defineTranslations / i18n.translations() em lib/layout.shared.ts) não é extraído do markdown. Configure docsOutput.fumadocsUiCatalog para que translate-docs inicialize o catálogo em inglês a partir de sourcePath e traduza o JSON por localidade:

{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "contentPaths": ["content/docs"],
      "outputDir": "content/docs",
      "docsOutput": {
        "style": "fumadocs",
        "docsRoot": "content/docs",
        "fumadocsParser": "dot",
        "fumadocsUiCatalog": {
          "sourcePath": "lib/layout.shared.ts",
          "catalogPath": "lib/i18n/ui.en.json"
        }
      }
    }
  ]
}

• catalogPath — JSON plano em inglês gerado (saída de inicialização). Execute sync novamente quando as substituições em inglês em layout.shared.ts mudarem.
• outputPathTemplate (opcional) — saídas por localidade; padrão: ui.{locale}.json ao lado de catalogPath.

Carregue o JSON por localidade em layout.shared.ts via loadUiCatalog(locale) e mescle com i18nProvider(translations, lang) em seu layout raiz. Consulte examples/fumadocs-docs/lib/layout.shared.ts.

Locais padrão podem ser cobertos por presets @fumadocs/language/* sem custo de LLM; o catálogo traduz sobrescritas de projeto no bloco em inglês apenas.

Não use json[] para strings de interface do usuário Fumadocs — esse pipeline é para bundles de locale de aplicativos não relacionados.

Convenções de link

Fumadocs serve rotas com prefixo de locale via middleware do Next.js (/docs/getting-started, /pt/docs/getting-started). Links dentro da página devem permanecer neutros em relação ao locale (/docs/getting-started) para que o prefixo do locale ativo seja aplicado automaticamente.

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

"docsOutput": {
  "style": "fumadocs",
  "docsRoot": "content/docs",
  "rewriteFumadocsLinks": true
}

rewriteFumadocsLinks é habilitado por padrão quando style é "fumadocs".

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

Regras de autoria

• Links de documentação entre páginas: use rotas de site neutras em local (/docs/…) em MDX em inglês, ou content/docs/… / caminhos relativos .mdx e deixe o normalizador reescrevê-los durante sync.
• Arquivos de repositório fora da árvore de conteúdo: use URLs completas.
• Não edite manualmente links em cópias com sufixo de local (*.pt.mdx) ou árvores content/{locale}/ — regenere com sync / translate-docs.

Veja também Documentos — reescrita de links e Configuração — docsOutput.

Códigos de locale

Mantenha targetLocales em ai-i18n-tools.config.json alinhado com defineI18n().languages no seu aplicativo Fumadocs exatamente. O exemplo de ponto usa códigos curtos (pt, zh); configurações de diretório podem usar pastas BCP-47 (pt-BR, zh-Hans). Não há normalização forçada — códigos não coincidentes produzem caminhos de saída errados ou páginas faltantes.

Múltiplas coleções

Projetos Fumadocs podem definir vários blocos defineDocs em source.config.ts (documentos, blog, exemplos). Adicione um bloco docs[] por coleção que você traduz, cada um com seu próprio contentPaths, outputDir e docsRoot.

Projeto de exemplo

exemplos/fumadocs-docs — MDX em inglês em content/docs/, comprometido pt e zh páginas com sufixo de ponto, meta.json e lib/i18n/ui.{locale}.json. Execute pnpm run dev na porta 3080.

Referências cruzadas

• Configuração — docsOutput
• Layouts de saída
• Integração Docusaurus
• Integração Nextra (modelo mental do analisador de diretório)
• Integração VitePress (padrão de inicialização do catálogo de UI)