Sitio multilingüe y publicación
Arquitectura
El sitio usa Astro 7.2.9, salida estática y colecciones de contenido en tiempo de compilación. Las lecciones canónicas permanecen en sus directorios del currículo. Los diccionarios de traducción identificados por su contenido proporcionan toda la prosa en español y portugués de Brasil; el inglés usa la fuente canónica.
El generador crea Markdown temporal, índices de búsqueda, el inventario de fuentes y recursos estáticos en site-generated/. Astro renderiza las páginas finales en dist/. Ninguno de los dos directorios se incluye en los commits. No se necesita un servicio de traducción en tiempo de ejecución, una API de modelos, Ruby, Jekyll ni una base de datos.
Política de idiomas y fuentes
Todos los documentos de aprendizaje actuales tienen rutas /en/, /es/ y /pt-br/. La navegación, la búsqueda, los títulos de documentos, las etiquetas de los diagramas y las explicaciones didácticas usan el idioma seleccionado. Las anclas de los encabezados son estables entre idiomas. Si falta una traducción, la compilación falla en lugar de mostrar inglés silenciosamente.
Los comandos, los prompts de ejemplo, el código fuente, los identificadores y los datos exactos conservan su forma original para que los ejercicios sean reproducibles. Las licencias, las personalizaciones procesadas por herramientas y los documentos históricos se conservan como fuentes originales con un aviso localizado. El explorador indexa todos los archivos fuente públicos y excluye la salida generada, el estado local ignorado y las dependencias.
Las descargas originales se identifican por contenido y se verifican mediante SHA-256. Los finales de línea del texto siguen la regla de .gitattributes del repositorio; los bytes binarios no cambian. El texto fuente se muestra como texto y nunca se ejecuta como HTML o JavaScript.
Las ilustraciones SVG actuales de aventuras y laboratorios prácticos tienen vistas previas generadas en el idioma seleccionado, incluidas las etiquetas visibles y las descripciones accesibles. La compilación falla si faltan traducciones de los recursos multimedia. Las imágenes de las lecciones y la vista previa del repositorio usan estas copias localizadas; las descargas originales, las capturas de pantalla y los recursos históricos se conservan sin cambios. El diálogo de imágenes permite ampliar, desplazar y ajustar la imagen en dispositivos móviles.
Archivos del alumno
El catálogo de descargas enlaza con 35 ZIP de ejercicios en
assets/lab-kits/. A diferencia de las vistas previas del código fuente individual, estos enlaces resuelven a
archivos de descarga estáticos en todos los idiomas. Los paquetes contienen recursos del alumno, una instantánea
de la lección, imágenes locales, guía de configuración, licencias y manifiestos de integridad de archivos;
los directorios de referencia para instructores y las cachés locales están excluidos.
Después de cambiar un archivo fuente empaquetado, una lección, una imagen o una guía de configuración, ejecuta:
npm run build:kits
npm run test:kits
npm run check:kits
Confirma los ZIP regenerados y el inventario de checksums junto con sus cambios de origen. Las pruebas del repositorio y las compilaciones del sitio rechazan archivos obsoletos. Las pruebas del paquete no afirman que se haya ejecutado un modelo autenticado, una sesión en la nube ni cada adaptación de idioma.
Verificación local
Usa Node.js 24 o posterior con el archivo de bloqueo versionado. Instala dependencias solo después de clonar o cambiar los manifiestos de dependencias.
npm ci --ignore-scripts
npm test
npm run build:site
npm run check:astro
npm run check:site:rendered -- dist
npm run preview:site -- --host 127.0.0.1
Abre la URL que imprime el comando de vista previa, incluida la ruta base del proyecto. Comprueba los diseños de escritorio y móvil, la navegación por teclado, la búsqueda, los controles de tema, el cambio de idioma en el mismo documento, las vistas previas y descargas de fuentes y los diagramas monocromáticos. Los enlaces estáticos y todos los resultados de búsqueda también se verifican contra la salida renderizada.
Para editar con vista previa en vivo, usa npm run dev:site. Los cambios en el contenido canónico o las traducciones requieren reiniciar ese comando para regenerar la entrada de publicación. No edites directamente el Markdown generado.
Unidad de trabajo y límites de recursos
Mantén el checkout, la salida, el perfil del navegador y las cachés de paquetes en la unidad de trabajo seleccionada. SITE_OUTPUT_DIR permite cambiar el directorio de salida. TMPDIR, npm_config_cache y XDG_CACHE_HOME controlan las ubicaciones temporales y de caché.
La compilación predeterminada renderiza una página a la vez y usa un único worker de Rust. El envoltorio de la CLI desactiva la telemetría de Astro y limita por defecto el heap de Node a 768 MiB cuando NODE_OPTIONS no está definido. Es un límite del proceso, no una garantía sobre la memoria total del equipo. No inicies pruebas de carga, navegadores paralelos ni varias compilaciones en un equipo compartido.
Publicación
El workflow de Pages instala las dependencias fijadas, ejecuta las comprobaciones del repositorio, compila Astro, comprueba los tipos de los componentes y verifica los enlaces renderizados antes de subir el artefacto estático. El despliegue usa el entorno github-pages. Configura Settings → Pages → Source → GitHub Actions.
Solo los pushes a main y las ejecuciones manuales despliegan; los pull requests validan sin publicar. El propietario del repositorio, el origen del sitio, la ruta base, los idiomas y la versión de Mermaid están centralizados en la configuración del sitio. Actualízalos después de transferir el repositorio y verifica la URL pública resultante.
Las rutas antiguas del currículo redirigen a sus equivalentes en inglés y conservan los parámetros de consulta y los fragmentos de encabezados. GitHub no garantiza la redirección desde el hostname de Pages del propietario anterior; actualiza los marcadores a la dirección actual del sitio.
Mantenimiento de traducciones
Ejecuta el exportador de traducciones con un directorio absoluto en la unidad de trabajo seleccionada. Genera paquetes JSON de trabajo acotados sin llamar a un servicio externo. Traduce cada segmento sin cambiar los destinos de enlaces, los fragmentos de código, la estructura Markdown ni los hechos del producto. Guarda el resultado revisado en site-locales/es/ y site-locales/pt-br/.
Los IDs de segmento derivan del texto fuente. Editar un párrafo requiere una nueva traducción de ese párrafo. La compilación valida todos los IDs necesarios, los tokens protegidos de código y enlaces, la estructura de encabezados y los requisitos de los diagramas monocromáticos.