Site multilíngue e publicação
Arquitetura
O site usa Astro 7.2.9, saída estática e coleções de conteúdo em tempo de build. As lições canônicas permanecem nos diretórios do currículo. Dicionários de tradução identificados pelo conteúdo fornecem toda a prosa em espanhol e português do Brasil; o inglês usa a fonte canônica.
O gerador cria Markdown temporário, índices de busca, o inventário das fontes e recursos estáticos em site-generated/. O Astro renderiza as páginas finais em dist/. Nenhum dos diretórios é incluído nos commits. Não é necessário um serviço de tradução em tempo de execução, uma API de modelos, Ruby, Jekyll nem um banco de dados.
Política de idiomas e fontes
Todos os documentos de aprendizagem atuais têm rotas /en/, /es/ e /pt-br/. Navegação, busca, títulos dos documentos, rótulos dos diagramas e explicações didáticas usam o idioma selecionado. As âncoras dos títulos permanecem estáveis entre idiomas. Se faltar uma tradução, o build falha em vez de exibir inglês silenciosamente.
Comandos, prompts de exemplo, código-fonte, identificadores e dados exatos mantêm a forma original para que os exercícios sejam reproduzíveis. Licenças, personalizações processadas por ferramentas e documentos históricos são preservados como fontes originais com um aviso localizado. O explorador indexa todos os arquivos-fonte públicos e exclui a saída gerada, o estado local ignorado e as dependências.
Os downloads originais são identificados pelo conteúdo e verificados por SHA-256. As terminações de linha do texto seguem a regra de .gitattributes do repositório; os bytes binários não mudam. O texto-fonte é exibido como texto e nunca é executado como HTML ou JavaScript.
As ilustrações SVG atuais das aventuras e dos labs práticos têm previews gerados no idioma selecionado, incluindo os rótulos visíveis e as descrições acessíveis. A compilação falha se faltarem traduções de mídia. As imagens das lições e o preview do repositório usam essas cópias localizadas; os downloads originais, as capturas de tela e as mídias históricas permanecem inalterados. O diálogo de imagens permite ampliar, rolar e ajustar a imagem no celular.
Arquivos do aluno
O catálogo de downloads leva a 35 ZIPs de exercícios em
assets/lab-kits/. Ao contrário das prévias do código-fonte individual, esses links resolvem para
arquivos de download estáticos em todos os idiomas. Os pacotes contêm recursos do aluno, um instantâneo
da lição, imagens locais, guia de configuração, licenças e manifestos de integridade de arquivos;
diretórios de referência para instrutores e caches locais são excluídos.
Depois de alterar um arquivo-fonte empacotado, uma lição, uma imagem ou um guia de configuração, execute:
npm run build:kits
npm run test:kits
npm run check:kits
Confirme os ZIPs regenerados e o inventário de checksums junto com suas alterações de origem. Os testes do repositório e as compilações do site rejeitam arquivos obsoletos. Os testes do pacote não afirmam que um modelo autenticado, uma sessão em nuvem nem cada adaptação de idioma foi executada.
Verificação local
Use Node.js 24 ou posterior com o arquivo de lock versionado. Instale as dependências apenas após clonar ou alterar os manifestos de dependências.
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
Abra a URL exibida pelo comando de preview, incluindo o caminho base do projeto. Verifique os layouts para desktop e dispositivos móveis, a navegação por teclado, a busca, os controles de tema, a troca de idioma no mesmo documento, as visualizações e os downloads das fontes e os diagramas monocromáticos. Os links estáticos e todos os resultados de busca também são verificados contra a saída renderizada.
Para editar com visualização ao vivo, use npm run dev:site. Alterações no conteúdo canônico ou nas traduções exigem reiniciar esse comando para regenerar a entrada de publicação. Não edite diretamente o Markdown gerado.
Disco de trabalho e limites de recursos
Mantenha o checkout, a saída, o perfil do navegador e os caches de pacotes no disco de trabalho selecionado. SITE_OUTPUT_DIR permite alterar o diretório de saída. TMPDIR, npm_config_cache e XDG_CACHE_HOME controlam os locais temporários e de cache.
O build padrão renderiza uma página por vez e usa um único worker Rust. O wrapper da CLI desativa a telemetria do Astro e limita por padrão o heap do Node a 768 MiB quando NODE_OPTIONS não está definido. Esse é um limite do processo, não uma garantia sobre a memória total da máquina. Não inicie testes de carga, navegadores paralelos nem vários builds em um computador compartilhado.
Publicação
O workflow do Pages instala as dependências fixadas, executa as verificações do repositório, compila o Astro, verifica os tipos dos componentes e valida os links renderizados antes de enviar o artefato estático. O deploy usa o ambiente github-pages. Configure Settings → Pages → Source → GitHub Actions.
Somente pushes para main e execuções manuais fazem deploy; pull requests validam sem publicar. O proprietário do repositório, a origem do site, o caminho base, os idiomas e a versão do Mermaid estão centralizados na configuração do site. Atualize esses valores após transferir o repositório e verifique a URL pública resultante.
As rotas antigas do currículo redirecionam para os equivalentes em inglês, preservando os parâmetros de consulta e os fragmentos dos títulos. O GitHub não garante o redirecionamento a partir do hostname do Pages do proprietário anterior; atualize os favoritos para o endereço atual do site.
Manutenção das traduções
Execute o exportador de traduções com um diretório absoluto no disco de trabalho selecionado. Ele gera pacotes JSON de trabalho delimitados sem chamar um serviço externo. Traduza cada segmento sem alterar destinos de links, trechos de código, estrutura Markdown nem fatos do produto. Salve o resultado revisado em site-locales/es/ e site-locales/pt-br/.
Os IDs dos segmentos derivam do texto-fonte. Editar um parágrafo exige uma nova tradução desse parágrafo. O build valida todos os IDs necessários, os tokens protegidos de código e links, a estrutura dos títulos e os requisitos dos diagramas monocromáticos.