Integración de Nextra

Utilice init -t ui-nextra y docsOutput.style: "nextra" para sitios de documentación de Nextra 4 en Next.js App Router. El preajuste es un alias para doc-system con un localeSubpath vacío y los nombres de carpeta de configuración regional BCP-47 conservados (localePathLowercase por defecto es false, por lo que las carpetas permanecen pt-BR, zh-Hans, etc.).

Consulte también Documentos y la demostración ejecutable examples/nextra-docs.

Inicio 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 cuando traduzca el contenido de la página, las etiquetas de la barra lateral de _meta.ts y los módulos del diccionario de temas en una ejecución de sync.

Diseño de página

Nextra 4 con i18n mantiene el MDX de origen en inglés bajo una carpeta de configuración regional (normalmente content/en/). Las copias traducidas se escriben en carpetas de configuración regional hermanas:

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

Configure un bloque docs[]:

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

Apunte contentPaths a sus archivos y directorios .mdx en inglés. Establezca docsRoot en la carpeta de configuración regional en inglés dentro de content/.

Conecte la internacionalización de Nextra: configure i18n.locales y defaultLocale en next.config, y mantenga targetLocales en ai-i18n-tools.config.json alineado con esos códigos de configuración regional y los nombres de carpeta de content/{locale}/.

Cadenas de tema

El "chrome" del tema de Nextra (editLink, marcador de posición de búsqueda, pie de página, etc.) no se extrae de markdown. Cree cadenas en inglés en un módulo de diccionario TypeScript (por ejemplo, app/_dictionaries/en.ts) y tradúzcalo dentro de translate-docs:

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

La herramienta escribe app/_dictionaries/{locale}.ts (plantilla predeterminada: {dir}/{locale}.ts). Cargue el módulo por configuración regional en app/_dictionaries/get-dictionary.ts y pase las cadenas traducidas a <Layout>, <Search>, <Footer> y los componentes de tema relacionados.

No use json[] para las cadenas del diccionario de temas de Nextra; ese patrón es solo para paquetes de configuración regional de aplicaciones no relacionados.

Etiquetas de la barra lateral (_meta.ts)

Nextra 3+ utiliza archivos TypeScript _meta.ts / _meta.tsx para la estructura y los títulos de la barra lateral. Cuando docsOutput.style es "nextra", translate-docs recopila automáticamente _meta.ts, _meta.tsx y _meta.js bajo docsRoot, traduce los literales de cadena en el mapa meta de export default { … } y escribe archivos duplicados bajo content/{locale}/**.

Patrón recomendado: mantenga los literales en inglés en línea en content/en/**/_meta.ts (igual que swr-site):

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

Opcional: anule la recopilación con docs[].nextraMetaGlob o restrinja los nombres de propiedades traducibles con docs[].nextraMetaTranslatableKeys (predeterminado: title, display, breadcrumb).

No cree manualmente sidecars JSON (i18n/meta.en.json) o archivos _meta.ts delgados que importen JSON traducido; regenere los archivos _meta de configuración regional con sync / translate-docs cuando el inglés cambie.

Proyecto de ejemplo

examples/nextra-docs — Fuentes en inglés en content/en/, árboles de páginas pt-BR y zh-Hans confirmados, archivos _meta.ts en línea y app/_dictionaries/{locale}.ts. Ejecute pnpm run dev en el puerto 3070.

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

Predeterminado: Las cadenas literales de objeto _meta.ts / _meta.tsx se traducen dentro de translate-docs — no se requiere t().

Híbrido opcional: los equipos pueden usar adicionalmente t() + translate-ui para el cromo de diseño app/, componentes MDX personalizados o etiquetas _meta.tsx que solo residen dentro de los cuerpos de los componentes JSX (más allá de la extracción de literales de objetos en v1). Esto no reemplaza a translate-meta para los archivos meta a menos que refactorice explícitamente las etiquetas de la barra lateral en componentes.

Contenido	Canalización predeterminada	Alternativa opcional
Cuerpos de página MDX	translate-docs	—
Títulos de objeto _meta.ts / _meta.tsx	translate-docs	refactorizar a t() en JSX (híbrido)
Diseño app/, _components/	nextraDictionaryPath + diccionario .ts	t() + translate-ui

Ejemplo de prompt de agente de IA (copie en Cursor u otro agente de codificación al migrar el cromo de diseño a 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.

Convenciones de enlaces

Nextra sirve rutas con prefijo de configuración regional a través de Next.js i18n (/guide/getting-started, /pt-BR/guide/getting-started). Los enlaces dentro de la página deben permanecer neutrales a la configuración regional (/guide/getting-started) para que Next.js pueda prefijar la configuración regional activa automáticamente.

Habilite el normalizador incorporado para que translate-docs corrija los enlaces en cada archivo traducido automáticamente:

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

rewriteNextraLinks se habilita de forma predeterminada cuando style es "nextra".

Autor en fuente inglesa	Después del normalizador
[Guide](content/en/guide/getting-started.mdx)	[Guide](/es/guide/getting-started)
[Guide](/es/guide/getting-started.mdx)	[Guide](/es/guide/getting-started)
[Demo](https://github.com/org/repo)	sin cambios (URL completa)

Reglas de autoría

• Enlaces de documentos entre páginas: use rutas de sitio neutrales a la configuración regional (/guide/…) en MDX en inglés, o rutas content/en/… / .mdx relativas y deje que el normalizador las reescriba durante sync.
• Archivos de repositorio fuera del árbol de contenido: use URL completas.
• No edite manualmente los enlaces en content/<locale>/ — regenere con sync / translate-docs.

Proxy de configuración regional opcional

Nextra proporciona un proxy de detección de configuración regional para sitios i18n. Exporte desde proxy.ts en la raíz de su proyecto:

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 configuración regional del sitio vs sourceLocale: Nextra y Next.js usan códigos de ruta cortos (en, pt-BR, zh-Hans) en next.config, content/{locale}/ y la cookie NEXT_LOCALE. sourceLocale en ai-i18n-tools.config.json puede ser una etiqueta BCP-47 como en-GB para la calidad de la traducción — esa etiqueta no es una ruta del sitio. Si la cookie del navegador o Accept-Language se resuelve en una etiqueta fuera de i18n.locales (por ejemplo, en-GB cuando solo en está configurado), el proxy estándar de Nextra puede redirigir en un bucle. La demostración examples/nextra-docs envuelve nextra/locales para restablecer las cookies y rutas no válidas a la configuración regional predeterminada del sitio antes de delegar.

Esto no funciona con las exportaciones estáticas de output: 'export'. Consulte Documentación de Nextra i18n.

Consulte también Configuración — docsOutput y Diseños de salida.