Internacionalización

Este sitio está disponible en inglés, alemán, francés y español. Elige el idioma en la cabecera o el menú móvil. Ardo conserva la página, los parámetros de consulta y el fragmento al cambiar de idioma.

Rutas estáticas por idioma

Configura los idiomas en ardo.config.ts o en el plugin Vite ardo():

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Docs",
  i18n: {
    defaultLocale: "en",
    locales: [
      { id: "en", label: "English" },
      { id: "de", label: "Deutsch" },
      { id: "fr", label: "Français" },
      { id: "es", label: "Español" },
    ],
  },
})

Coloca las rutas correspondientes bajo app/routes/en/, app/routes/de/, app/routes/fr/ y app/routes/es/. Mantén los mismos slugs en todos los idiomas. Ardo exige un árbol completo y avisa de las páginas ausentes durante la compilación. No sustituye contenido por otro idioma sin indicarlo.

El despliegue V6 usa /v6/en/, /v6/de/, /v6/fr/ y /v6/es/. Las versiones anteriores de la documentación conservan su idioma y sus URL originales.

Interfaz, búsqueda y metadatos

Usa useArdoLocale() de ardo/runtime para obtener el idioma activo, también durante el renderizado del servidor. Pasa textos localizados a <ArdoRoot labels={...}> para la navegación, búsqueda, avisos, controles de copia y acciones de página. Ardo formatea las fechas de actualización con el idioma de la ruta.

La búsqueda solo carga el índice del idioma activo cuando el lector enfoca el campo o escribe una consulta. El HTML generado contiene el lang correcto, la URL canónica y enlaces a los demás idiomas. Los identificadores del código y las rutas de importación no cambian. La referencia de la API se genera a partir de comentarios en inglés y lo indica en cada interfaz traducida.

Una fuente MDX con Palamedes

Palamedes compila este ejemplo a partir de un único archivo MDX en inglés. Los párrafos y marcadores de texto enriquecido proceden de los catálogos de idioma; el componente React se conserva:

Te damos la bienvenida a Ardo. Este párrafo se traduce con Palamedes a partir de una única fuente MDX.

El compilador nativo de Palamedes extrae los mensajes de cada guía en inglés de docs/app/content/guide/. Durante el build, el sitio aplica las traducciones PO y genera los cuatro árboles antes de que Ardo prepare metadatos, búsqueda y exportaciones Markdown.

Solo se mantienen la fuente MDX inglesa y los catálogos PO. Git ignora las rutas generadas bajo docs/app/routes/<locale>/guide/. El código, los imports, los componentes interactivos y los identificadores ingleses siguen siendo estructurales; se traducen el texto, las etiquetas y el frontmatter.

Contexto de renderizado del servidor

Un sitio puede exportar withRenderContext de app/server.ts para definir un contexto alrededor del renderizado completo de una página. Este módulo solo entra en el bundle del servidor. La resolución de metadatos y los componentes React suspendidos se ejecutan en el mismo contexto:

import type { ArdoServerRenderContext } from "ardo/runtime"
import { createServerI18nScope } from "@palamedes/runtime/server"

const scope = createServerI18nScope()

export async function withRenderContext({ path, render }: ArdoServerRenderContext) {
  const i18n = await loadI18n(path.split("/")[1] ?? "en")
  return scope.run(i18n, render)
}

Aquí loadI18n es el cargador de catálogos del sitio. Usa una instancia inmutable por idioma o una instancia nueva por petición. No actives un idioma mutable para todo el proceso: los renderizados paralelos mezclarían idiomas. En el navegador, Palamedes v2 inicializa su runtime mediante las dependencias de catálogo generadas. El hook del servidor del sitio usa createViteCatalogDelivery() de @palamedes/vite-plugin/delivery para insertar el import map del idioma activo y gestionar fallos de carga de catálogos antes de la hidratación.

Mantener las traducciones

Desde la raíz del repositorio:

pnpm --filter ardo-docs i18n:extract
pnpm --filter ardo-docs i18n:check

La extracción actualiza los mensajes fuente y conserva las traducciones. Edita los catálogos de guías en docs/app/i18n/guides/; la interfaz común y el ejemplo interactivo usan docs/app/i18n/. La auditoría comprueba traducciones ausentes, sintaxis ICU y marcadores de texto enriquecido. El plugin Vite regenera las rutas al editar la fuente o los PO. Compila el sitio y ejecuta los tests de cambio de idioma antes de enviar cambios.