Internacionalización (i18n)

Esta página documenta cómo el sitio de documentación de Apothem gestiona varios idiomas: la cohorte de locales que declara, el mecanismo hreflang que emite, su renderizado de derecha a izquierda y cómo se conectan al enrutamiento las páginas de cada idioma.

Resumen de la decisiónCopy Anchor Link

• Plataforma: Next.js App Router + Fumadocs. El sitio se compila desde site/. La cohorte de locales se declara en site/lib/i18n.ts, y el mecanismo de enlaces de idioma alternativo reside en site/lib/hreflang.ts.
• Cohorte de locales: doce idiomas. La Cohorte de Desarrollo Moderno de doce locales es la fuente de verdad canónica, con el inglés como locale de origen y cada uno de los once destinos sembrado por máquina a partir del conjunto de páginas en inglés; la revisión humana por locale está en curso, y fallbackLanguage: 'en' cubre cualquier página que un locale aún no haya redactado.
• Enrutamiento por locale: habilitado en toda la cohorte. Cada locale está conectado al enrutamiento y es accesible en su propio prefijo de URL (/es/, /zh-cn/, …); el inglés se sirve en la raíz del sitio.
• Mecanismo hreflang: activo. Cada página emite un conjunto <link rel="alternate"> que cubre cada locale más un respaldo x-default, de modo que los motores de búsqueda ven el grupo completo de idiomas alternativos. Los enlaces se resuelven archivo por archivo a partir del sistema de archivos, así que una página se anuncia en un locale solo cuando ese locale la tiene.
• Renderizado de derecha a izquierda: activo. Las hojas de estilo compartidas usan propiedades CSS lógicas en todas partes, de modo que las páginas en árabe se renderizan correctamente bajo dir="rtl".
• Revisión de las traducciones: seguimiento por página. Las páginas de locale sembradas por máquina se sirven y llevan machineTranslated: true en su frontmatter hasta que una persona las revisa; la marca es metadato de seguimiento de la revisión y la página no la muestra. El inglés es el respaldo para cualquier página que le falte a un locale. Tener revisado el 80 % de las páginas de un locale es un objetivo de revisión, no una condición para publicar.
• Actualidad de las traducciones: seguimiento por página. Cada página de locale registra el texto en inglés a partir del cual se tradujo. Cuando la página en inglés cambia más tarde, la página traducida muestra una nota de una línea con un enlace a la página en inglés, que sigue siendo la autoritativa.

La cohorte de localesCopy Anchor Link

La Cohorte de Desarrollo Moderno declara doce locales. El inglés se sirve en la raíz del sitio; cada uno de los once destinos se siembra por máquina a partir del conjunto de páginas en inglés en su propio prefijo de URL, y fallbackLanguage: 'en' cubre cualquier página aún no redactada.

La cohorte es la única fuente de verdad; las enmiendas a ella pasan por una decisión deliberada, nunca por una edición silenciosa.

Cómo funciona hreflangCopy Anchor Link

site/lib/hreflang.ts construye el mapa alternates.languages que Next.js renderiza en el <head> de cada página. Su construcción respeta una regla: el enlace de idioma alternativo de un locale se emite solo cuando ese locale ha redactado esa página, lo que se resuelve archivo por archivo a partir del sistema de archivos (site/lib/translated-pages.ts). Por tanto, una página totalmente traducida emite el grupo completo:

<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="es" href="https://apothem.ahmedgad.com/es/..." />
<link rel="alternate" hreflang="ar" href="https://apothem.ahmedgad.com/ar/..." dir="rtl" />
<!-- … one per cohort locale … -->
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />

El enlace canonical de la página es siempre su propia URL — nunca apunta a otro locale.

Renderizado de derecha a izquierdaCopy Anchor Link

El árabe es el locale de derecha a izquierda de la cohorte, y el sitio lo renderiza correctamente:

• Solo propiedades CSS lógicas. Las hojas de estilo y los componentes compartidos usan propiedades lógicas (margin-inline-start, padding-inline-end, text-align: start, inset-inline-start) en lugar de propiedades físicas (margin-left, text-align: left). Las propiedades lógicas se invierten automáticamente bajo dir="rtl", de modo que la misma hoja de estilo sirve correctamente para ambas direcciones.
• Atributo de dirección. Las páginas en árabe establecen dir="rtl" en el elemento <html> junto con lang="ar".
• Contenido bidireccional. Las cadenas de dirección mixta — por ejemplo, un comando en inglés dentro de un párrafo en árabe — se envuelven en <bdi> para que la secuencia incrustada de izquierda a derecha se renderice correctamente dentro del flujo de derecha a izquierda.

Añadir o actualizar un localeCopy Anchor Link

La cohorte y el enrutamiento se controlan desde site/lib/i18n.ts:

1. Redacta la página bajo content/docs/<locale>/ reflejando el original en inglés.
2. Registra el texto en inglés que traduce: desde site/, ejecuta node scripts/translation-sources.mjs --stamp <locale>/<path>.mdx, que escribe el hash de la página en inglés en el campo sourceHash del frontmatter de la página del locale.
3. Confirma que el locale figura en ROUTED_LOCALES (los doce locales de la cohorte están enrutados hoy).
4. Su enlace hreflang y sus rutas se resuelven automáticamente a partir del sistema de archivos.

Traducciones desactualizadasCopy Anchor Link

El sourceHash de una página de locale es el hash de la página en inglés a partir de la cual se tradujo, y cubre el frontmatter y la prosa en inglés, pero no las tablas generadas que el generador de referencia reescribe en todos los idiomas a la vez. En el momento de la compilación, el sitio calcula el hash de la página en inglés actual; cuando los dos difieren, la página traducida muestra una nota que indica que la página en inglés ha cambiado desde que se hizo la traducción, con un enlace a ella. Ejecuta node scripts/translation-sources.mjs desde site/ para listar las páginas desactualizadas por locale; después, actualiza cada traducción y séllala como en el paso 2 anterior. Una página que un locale no ha traducido en absoluto se sirve desde el original en inglés, marcada como texto en inglés.

El inglés sigue siendo la fuente de verdad; cada página de locale refleja literalmente la estructura, los enlaces y los ejemplos de código de su contraparte en inglés.