Manter uma lista de recursos multilíngue gerada a partir de arquivos de dados, sem editar páginas à mão

## Entender que as páginas da lista são geradas a partir de arquivos de dados Você mantém uma base de conhecimento selecionada cujas saídas voltadas ao usuário final são **geradas**, não escritas manualmente. Entenda essa divisão antes de mexer em qualquer coisa: - A **fonte da verdade** é um conjunto de arquivos de dados estruturados: uma árvore de categorias/seções (que define âncoras e o sumário) e um arquivo de entrada por seção. - Os **artefatos gerados** — os documentos de listagem legíveis por humanos (um por idioma suportado) e qualquer índice legível por máquina — são produzidos a partir desses dados por um script gerador. Eles são descartáveis e reconstruídos sob demanda. - Os mesmos dados subjacentes também podem alimentar uma interface de consulta em tempo de execução para agentes automatizados, de modo que a qualidade dos dados tem consumidores além dos documentos renderizados. Normalmente não há runtime de aplicação, build ou suíte de testes aqui. Toda mudança é uma destas três coisas: dados estruturados, scripts de ferramentas ou documentação. Mantenha esse modelo mental — ele evita o erro mais comum e mais prejudicial: editar uma saída que será sobrescrita. ## Alterar os dados e gerar as páginas de novo, em vez de editá-las - **Nunca edite diretamente um documento de saída gerado.** As edições são apagadas na próxima regeneração. Para mudar o que o leitor vê, mude os dados subjacentes. - Para adicionar ou modificar um item, edite o arquivo de entrada da seção correspondente. - Para adicionar uma nova seção, edite primeiro o arquivo da árvore de categorias/seções e, depois, crie o arquivo de entrada correspondente. Em seguida, execute a ferramenta de verificação de âncoras para confirmar que nenhuma âncora referenciada externamente foi perdida. - Após qualquer mudança nos dados, execute o gerador localmente para atualizar todos os arquivos gerados antes de fazer o commit. A integração contínua rejeitará uma árvore de trabalho que diverge da saída recém-gerada — portanto regenere, não adivinhe. - Não edite manualmente o índice legível por máquina; ele é totalmente regenerado pelo gerador. ## Preencher os campos de cada entrada e escrever uma descrição de uma frase Cada entrada é um registro estruturado com campos obrigatórios (um id único e estável, URL, título, categoria, tipo, nível de dificuldade, conjunto de idiomas, data de adição, status) e campos opcionais preenchidos por automação (URL de arquivamento, timestamp da última verificação, fingerprint de conteúdo). Respeite os vocabulários controlados de tipo, dificuldade, idioma e status — não invente valores. Trate a descrição em texto livre que acompanha uma entrada como **texto público, legível por terceiros**: - **Inclua** uma única frase factual descrevendo o que é o recurso, opcionalmente seguida de uma linha de crédito do autor. - **Exclua** qualquer coisa interna: referências a este projeto, números de issue ou de solicitação de mudança, frases do tipo "originalmente proposto por" ou qualquer metadado histórico. O histórico de controle de versão já preserva a atribuição; um leitor externo não deve conseguir inferir nenhuma relação entre a entrada e este repositório. - Deixe os valores migrados automaticamente intocados, a menos que o original esteja errado ou desatualizado. - Retire uma entrada do arquivamento externo somente quando o autor original tiver solicitado isso explicitamente (conteúdo pago/paywall, pedidos de remoção). ## Não mudar os nomes de link das seções, para não quebrar links externos Tanto sites externos quanto o sumário interno apontam para âncoras nomeadas. Renomear ou remover uma âncora existente quebra silenciosamente todo link de entrada que aponta para ela. - **Nunca renomeie ou remova uma âncora existente.** Em vez disso, adicione novas âncoras para novas seções. - Uma verificação de integração contínua compara o conjunto atual de âncoras com a linha de base e falha o build se qualquer âncora da linha de base estiver ausente. Trate essa verificação como um portão obrigatório, não como uma sugestão. - Como o gerador ordena as entradas de forma determinística (por data de adição e depois por título), nunca reordene entradas em massa manualmente. Para mover uma entrada para mais cedo na lista, altere o valor de data de adição em vez de reorganizar os registros. ## Escrever código e notas em um idioma principal e escolher as edições de cada entrada O conteúdo autoral do projeto é escrito em um idioma principal. Vários idiomas aparecem apenas onde o multilinguismo é intrínseco ao artefato: documentos de saída traduzidos, substituições localizadas de títulos de seção, títulos por entrada que preservam o idioma original do recurso e frases-gatilho destinadas a ativar em prompts em idiomas não principais. Todo o resto — código, comentários, nomes de campos, templates, saída do pipeline, rótulos, mensagens de commit — permanece no idioma principal. Uma única entrada pode aparecer em várias edições de idioma, controlada pelo seu conjunto de idiomas: - Nova entrada sem indicação de idioma → liste-a apenas no idioma principal e pergunte ao contribuidor se ele também a deseja em outras edições. - Recurso específico de uma localidade → marque-o apenas com aquela localidade. - Recurso canônico genuinamente transcultural → marque-o nos idiomas relevantes, ou use o curinga com moderação. - Nunca force a tradução nem o espelhamento de uma entrada entre edições apenas para fazer as estruturas coincidirem. Cada edição pode conter entradas que as outras não têm. ## Incorporar contribuições sem perder o crédito de quem as enviou As solicitações recebidas chegam em dois formatos e devem ser transferidas de forma que o crédito nunca se perca: - **Proposta estruturada (sem branch):** transfira a entrada diretamente para o modelo de dados, regenere, execute os verificadores e faça o commit com um trailer de coautoria creditando quem enviou — esse trailer é o único crédito dessa pessoa. - **Solicitação de mudança direta (o contribuidor editou arquivos em seu próprio branch):** transfira o trabalho *no branch dele* para que a mudança seja mesclada com atribuição completa. Nunca encaminhe uma mudança direta de um contribuidor por meio de um assistente automatizado que abre sua própria solicitação concorrente e fecha a do contribuidor — isso destrói o crédito de merge dele. Um assistente de codificação automatizado pode servir como um **fallback assíncrono apenas para propostas estruturadas**, quando o mantenedor está indisponível e a fila precisa continuar avançando. Não é o caminho padrão; um humano ainda revisa o resultado antes do merge. O assistente poupa digitação, não julgamento. ## Verificar cada mudança automaticamente e deixar o bot de revisão só aconselhar A cada mudança que envolva dados ou scripts geradores, o pipeline deve: 1. Executar a validação de esquema e a validação de âncoras. 2. Reexecutar o gerador e avisar se a árvore de trabalho divergir da saída recém-gerada (um sinal de que o contribuidor esqueceu de regenerar). 3. Invocar um bot de revisão automatizado que avalia cada nova entrada em relação a uma rubrica publicada, posta um único comentário estruturado e aplica rótulos consultivos. Projete o bot de revisão de forma conservadora: detecte o idioma do contribuidor de maneira determinística (não via o modelo) e passe isso como uma diretiva; quando a chamada ao modelo falhar, recorra a verificações determinísticas de acessibilidade e formato sob um rótulo distinto de "revisão-falhou". **O bot nunca faz merge automático nem rejeita automaticamente** — ele aconselha, humanos decidem. ## Nunca editar páginas à mão e parar para perguntar em mudanças não previstas Não faça: - Editar manualmente documentos de saída gerados ou o índice legível por máquina. - Renomear ou remover âncoras existentes. - Introduzir marcação além da lista de tags permitidas do projeto nos templates. - Reordenar entradas existentes em massa em vez de ajustar as chaves de ordenação. - Editar diretrizes de contribuição, código de conduta ou definições de fluxo de trabalho, a menos que explicitamente solicitado. - Criar commits ou fazer push, a menos que explicitamente solicitado. Quando uma mudança entrar em território que essas regras não cobrem — uma nova edição de idioma, um novo campo de esquema, uma nova taxonomia de seções — pare e pergunte em vez de improvisar. Siga o espírito do guia de contribuição e da rubrica de avaliação e, na dúvida, confirme com um humano antes de agir.