El Help Widget sirvió el JSON de error como artículo — paridad EN/ES del corpus de Ayuda rota ~9 semanas (#254)

Cuándo

Detectado y arreglado el 2026-08-23 (commit b58b7fb4, task #254, ronda CreaRack 23-08). Según el propio commit de fix, el corpus llevaba desincronizado ~9 semanas antes de detectarse — no hay fecha exacta de origen documentada, solo la estimación del autor del fix.

Síntomas visibles

El Help Widget de CreaRack Pro, al servir en español un artículo de dos páginas concretas (la página de dispositivos y la de filas de racks), mostraba el JSON de error crudo en lugar del contenido del artículo. Adicionalmente, el panel de categorías mostraba slugs sin traducir (ups, wireless, settings) en vez de etiquetas legibles.

Causa raíz

El corpus de Ayuda mantiene tres fuentes que deben permanecer coherentes entre sí, y no había ningún check automático que lo verificara:

1. Las páginas EN en src/content/wiki/crearack--*.md (fuente canónica).
2. Sus traducciones ES en src/content/wiki-es/crearack--*.md.
3. El mapa src/content/wiki-es/titles.json (título EN → título ES), que le dice al proxy de Ayuda que existe traducción y debe reescribir la ruta a wiki-es/.

Dos páginas EN (crearack--network--device-page, crearack--racks--filas-row) nacieron después de congelar una ronda de traducción y se quedaron sin su .md gemelo en wiki-es/. Cuando el Help Widget en español pedía esos artículos, la reescritura de ruta apuntaba a un fichero que no existía.

Un segundo footgun independiente agravaba el diagnóstico: la página EN crearack--network--auto-provision-wizard.md había perdido su campo title del frontmatter en algún punto del historial, lo que también rompe el emparejamiento título→fichero que usa titles.json. Se restauró el frontmatter recuperándolo del historial de git.

Por separado, CATEGORY_LABELS en functions/api/biblioteca/wiki.ts (ver [[entity—biblioteca—endpoint—wiki]]) no tenía entradas para las categorías ups, wireless y settings — un problema de cobertura distinto (degradación visual, no 404) que arrastraba desde que se crearon páginas de esas categorías sin actualizar el diccionario.

No existía ningún test que verificara ninguna de las dos cosas, así que el drift se acumuló en silencio hasta que alguien lo notó manualmente.

Fix aplicado

Commit b58b7fb4c73cdf5acb0781ed597f1e8676230717:

• Se crearon las 2 traducciones ES que faltaban: src/content/wiki-es/crearack--network--device-page.md y src/content/wiki-es/crearack--racks--filas-row.md.
• Se restauró el frontmatter perdido de src/content/wiki/crearack--network--auto-provision-wizard.md (EN), recuperado del historial de git.
• Se añadieron 3 claves a CATEGORY_LABELS en functions/api/biblioteca/wiki.ts: ups, wireless, settings.
• Se añadió test/help-corpus-parity.test.ts, que fija el contrato en CI con 4 checks: (1) toda página ES tiene su original EN (sin huérfanas), (2) toda entrada de titles.json resuelve a un fichero real en ambos lados (el check que directamente habría cazado este bug), (3) cobertura de traducción como aviso informativo (páginas EN nuevas sin traducir no rompen el build, pero quedan listadas), (4) toda categoría del corpus tiene etiqueta en CATEGORY_LABELS.

Lecciones

• Un mapa de traducción (titles.json) que referencia un fichero es una promesa que puede romperse silenciosamente en cuanto una de las dos fuentes cambia sin la otra — necesita su propio test de coherencia, no basta con revisar el diff a ojo.
• La pérdida de un campo de frontmatter (title) en una página aparentemente no tocada por el cambio en curso puede romper un emparejamiento en un sitio completamente distinto del código; vale la pena que el test de paridad lo cubra explícitamente en vez de asumir que el frontmatter existente es estable.
• Cuando un fallback silente (CATEGORY_LABELS[cat] || cat) evita un crash pero degrada la experiencia visible, sigue mereciendo cobertura de test — el criterio no es “¿revienta?” sino “¿lo notaría un usuario?”.

Preventivos futuros

• test/help-corpus-parity.test.ts corre en CI y falla el build ante cualquier regresión de las cuatro invariantes descritas arriba.
• Página de referencia del endpoint actualizada con la tabla completa de CATEGORY_LABELS: [[entity—biblioteca—endpoint—wiki]].

Véase también

• [[entity—biblioteca—endpoint—wiki]]
• [[feature—core—help-widget-i4]]
• [[entity—core—service—api-help]]
• [[feature—ux—help-widget]]
• [[entity—core—endpoint—api-help-wiki]]