Mantener una lista de recursos multilingüe generada desde archivos de datos, sin editar páginas a mano

## Entender que las páginas de la lista se generan desde archivos de datos Mantienes una base de conocimiento curada cuyas salidas orientadas a personas son **generadas**, no redactadas directamente. Comprende esta separación antes de tocar nada: - La **fuente de verdad** es un conjunto de archivos de datos estructurados: un árbol de categorías/secciones (que define los anclajes y la tabla de contenidos) y un archivo de entradas por sección. - Los **artefactos generados** —los documentos de listado legibles por personas (uno por idioma soportado) y cualquier índice legible por máquina— se producen a partir de esos datos mediante un script generador. Son desechables y se reconstruyen bajo demanda. - Los mismos datos subyacentes también pueden alimentar una interfaz de consulta en tiempo de ejecución para agentes automatizados, por lo que la calidad de los datos tiene consumidores más allá de los documentos renderizados. Normalmente no hay aquí un entorno de ejecución de aplicación, compilación ni suite de pruebas. Todo cambio es una de tres cosas: datos estructurados, scripts de herramientas o documentación. Conserva ese modelo mental: evita el error más común y más dañino, que es editar una salida que será sobrescrita. ## Cambiar los datos y regenerar las páginas en vez de editarlas - **Nunca edites directamente un documento de salida generado.** Las ediciones se pierden en la siguiente regeneración. Para cambiar lo que ve el lector, cambia los datos subyacentes. - Para añadir o modificar un elemento, edita el archivo de entradas de la sección correspondiente. - Para añadir una nueva sección, edita primero el archivo del árbol de categorías/secciones y luego crea el archivo de entradas correspondiente. Después, ejecuta la herramienta de verificación de anclajes para confirmar que no se perdió ningún anclaje referenciado externamente. - Después de cualquier cambio en los datos, ejecuta el generador localmente para actualizar todos los archivos generados antes de confirmar los cambios (commit). La integración continua rechazará un árbol de trabajo que diverja de la salida recién generada, así que regenera, no adivines. - No edites a mano el índice legible por máquina; el generador lo regenera por completo. ## Rellenar los campos de cada entrada y escribir una descripción de una frase Cada entrada es un registro estructurado con campos obligatorios (un id único estable, URL, título, categoría, tipo, nivel de dificultad, conjunto de idiomas, fecha de alta, estado) y campos opcionales que rellena la automatización (URL de archivo, marca de tiempo de última verificación, huella digital del contenido). Respeta los vocabularios controlados para tipo, dificultad, idioma y estado; no inventes valores. Trata el texto libre de descripción que acompaña a una entrada como **texto orientado al público, legible por terceros**: - **Incluye** una única frase factual que describa qué es el recurso, seguida opcionalmente de una línea de autoría. - **Excluye** cualquier información interna: referencias a este proyecto, números de incidencia o de solicitud de cambio, frases como "propuesto originalmente por", o cualquier metadato histórico. El historial de control de versiones ya conserva la atribución; un lector externo no debe poder inferir ninguna relación entre la entrada y este repositorio. - Deja intactos los valores migrados automáticamente, salvo que el original sea incorrecto u obsoleto. - Excluye una entrada del archivado externo únicamente cuando el autor original lo haya solicitado explícitamente (contenido de pago, solicitudes de retirada). ## No cambiar los nombres de enlace de las secciones para no romper enlaces externos Tanto los sitios externos como la tabla de contenidos interna apuntan a anclajes con nombre. Renombrar o eliminar un anclaje existente rompe silenciosamente todos los enlaces entrantes que lo apuntan. - **Nunca renombres ni elimines un anclaje existente.** Añade anclajes nuevos para las secciones nuevas en su lugar. - Un control de integración continua compara el conjunto de anclajes actual con la línea base y hace fallar la compilación si falta alguno de los anclajes base. Trata ese control como una barrera obligatoria, no como una sugerencia. - Dado que el generador ordena las entradas de forma determinista (por fecha de alta y luego por título), nunca reordenes las entradas manualmente en bloque. Para mover una entrada hacia arriba en la lista, cambia su valor de fecha de alta en lugar de reorganizar los registros. ## Escribir código y notas en un idioma principal y elegir las ediciones de cada entrada El contenido redactado por el proyecto se escribe en un idioma principal. Aparecen varios idiomas solo donde el multilingüismo es intrínseco al artefacto: documentos de salida traducidos, anulaciones localizadas de títulos de sección, títulos por entrada que conservan el idioma original del recurso, y frases activadoras pensadas para dispararse ante instrucciones en idiomas distintos del principal. Todo lo demás —código, comentarios, nombres de campos, plantillas, salida de la canalización, etiquetas, mensajes de commit— permanece en el idioma principal. Una misma entrada puede aparecer en varias ediciones de idioma, controlado por su conjunto de idiomas: - Entrada nueva sin indicación de idioma → inclúyela solo en el idioma principal y pregunta al colaborador si también la quiere en otras ediciones. - Recurso específico de una localidad → etiquétalo solo con esa localidad. - Recurso canónico genuinamente transcultural → etiquétalo en los idiomas relevantes, o usa el comodín con moderación. - Nunca fuerces la traducción ni la duplicación de una entrada en todas las ediciones solo para que las estructuras coincidan. Cada edición puede contener entradas que las demás no tienen. ## Incorporar contribuciones sin perder el crédito de quien las envía Las solicitudes entrantes llegan en dos formas y deben trasladarse de manera que el crédito nunca se pierda: - **Propuesta estructurada (sin rama):** traslada la entrada directamente al modelo de datos, regenera, ejecuta los verificadores y confirma el cambio con una línea de coautoría que acredite a quien la envió; esa línea es su único crédito. - **Solicitud de cambio directo (el colaborador editó archivos en su propia rama):** traslada el trabajo *en su rama* para que su cambio se fusione con atribución completa. Nunca enrutes un cambio directo de un colaborador a través de un asistente automatizado que abra su propia solicitud en competencia y cierre la del colaborador; eso destruye su crédito de fusión. Un asistente de codificación automatizado puede servir como **alternativa asíncrona únicamente para propuestas estructuradas**, cuando el mantenedor no está disponible y la cola debe seguir avanzando. No es la vía predeterminada; un humano sigue revisando el resultado antes de fusionarlo. El asistente ahorra escritura, no criterio. ## Revisar cada cambio automáticamente y dejar que el bot de revisión solo aconseje En cada cambio que afecte a los datos o a los scripts generadores, la canalización debe: 1. Ejecutar la validación de esquema y la validación de anclajes. 2. Volver a ejecutar el generador y advertir si el árbol de trabajo diverge de la salida recién generada (señal de que el colaborador olvidó regenerar). 3. Invocar un bot de revisión automatizado que califique cada entrada nueva según una rúbrica publicada, publique un único comentario estructurado y aplique etiquetas consultivas. Diseña el bot de revisión de forma conservadora: detecta el idioma del colaborador de manera determinista (no mediante el modelo) y pásalo como directiva; cuando la llamada al modelo falle, recurre a comprobaciones deterministas de accesibilidad y formato bajo una etiqueta distinta de "revisión fallida". **El bot nunca fusiona automáticamente ni rechaza automáticamente**: aconseja, los humanos deciden. ## No editar nunca páginas a mano y parar a preguntar ante cambios no previstos No hagas lo siguiente: - Editar a mano los documentos de salida generados o el índice legible por máquina. - Renombrar o eliminar anclajes existentes. - Introducir marcado más allá de la lista blanca de etiquetas permitidas del proyecto en las plantillas. - Reordenar entradas existentes en bloque en lugar de ajustar las claves de ordenación. - Editar las guías de contribución, el código de conducta o las definiciones de flujo de trabajo salvo que se solicite explícitamente. - Crear commits o hacer push salvo que se solicite explícitamente. Cuando un cambio entra en un terreno que estas reglas no cubren —una nueva edición de idioma, un nuevo campo de esquema, una nueva taxonomía de secciones—, detente y pregunta en lugar de improvisar. Ajústate al espíritu de la guía de contribución y de la rúbrica de evaluación, y ante la duda, confirma con un humano antes de actuar.