Mantenha uma biblioteca de aulas multilíngue com as traduções em dia com o inglês

## Edite só aulas, artigos e traduções, não o código do aplicativo Você mantém um repositório somente de conteúdo: aulas instrutivas, artigos e suas traduções. O aplicativo de publicação que renderiza esse conteúdo fica em outro lugar e não faz parte deste repositório. Seu trabalho é texto, estrutura e metadados — não código de aplicação. Limites de escopo a respeitar: - Não adicione código-fonte de aplicação, ferramentas de build ou configuração de runtime aqui. Se uma mudança exigir que o site se comporte de forma diferente, diga isso explicitamente e descreva a mudança complementar necessária no aplicativo de publicação, em vez de improvisar uma aqui. - Pequenos scripts de manutenção que reportam sobre o próprio conteúdo (por exemplo, um relatório de status de tradução) são legítimos e devem ser usados antes de editar, em vez de substituídos. - Trate cada arquivo como algo que um tradutor humano precisará seguir depois. Uma mudança conveniente para você, mas que quebra o fluxo de tradução, é uma mudança ruim. - Quando um pedido for ambíguo sobre se ele visa o idioma de origem ou uma tradução, pergunte antes de escrever. Errar o palpite silenciosamente corrompe o rastreamento de desatualização descrito mais adiante. ## Espelhe as pastas em todos os idiomas e altere primeiro o original em inglês A biblioteca usa uma organização previsível e espelhada. Os arquivos de aulas ficam em um diretório de aulas, depois em uma pasta nomeada com o código ISO do idioma, depois em uma pasta de categoria, depois o próprio documento. As publicações do blog ficam em um único diretório de posts e são nomeadas com um prefixo de data seguido de um slug separado por hífens, de modo que a ordem cronológica fique visível apenas pelo nome do arquivo. O conjunto de categorias em cada idioma é fixo e idêntico em todos os idiomas. As categorias comuns são básico, intermediário, avançado, armazenamento, testes, processamento de dados, material específico de framework e um agrupamento diverso. Não crie uma categoria em apenas um idioma; adicione-a em todos ou em nenhum. Um idioma — normalmente o inglês — é a única fonte de verdade. Todos os outros diretórios de idioma contêm traduções dele. Regras que decorrem disso: - Mudanças substanciais são feitas primeiro no idioma de origem e depois propagadas para as traduções. Nunca introduza fatos, exemplos ou seções novas apenas em uma tradução. - Uma tradução só pode ser corrigida isoladamente por motivos de qualidade de tradução: erro de tradução, gramática, tipografia ou convenções locais. - Se você notar um erro em uma tradução que também existe na origem, corrija a origem e trate a tradução como um acompanhamento. ## Suba o número de versão conforme o tamanho da mudança e copie-o nas traduções Todo documento começa com um bloco de metadados estruturado, encerrado por uma linha separadora. O bloco traz, no mínimo, uma string de versão, um título e um resumo curto que sintetiza o documento em uma ou duas frases. Publicações no estilo artigo trazem adicionalmente um nome de autor, um link de autor, marcadores e uma data de publicação. O campo de versão não é decoração — ele é lido por máquina. Uma tradução copia exatamente a versão do documento de origem a partir do qual foi traduzida. As ferramentas então comparam a versão de cada tradução com a versão atual da origem para decidir se essa tradução está atualizada, levemente desatualizada ou muito desatualizada. Aumente a versão da origem de acordo com o tamanho da mudança: - Maior: o documento foi amplamente reescrito. Os tradutores precisam refazer o trabalho. - Menor: frases, parágrafos ou exemplos foram adicionados ou removidos. Os tradutores precisam revisar e corrigir. - Correção: apenas correções ortográficas e tipográficas. As traduções continuam utilizáveis. Nunca aumente uma versão sem fazer a mudança correspondente, e nunca faça uma mudança substancial sem aumentar a versão. Ambos os erros destroem a precisão do relatório de desatualização, que é o único mecanismo que mantém a biblioteca traduzida confiável. Ao editar uma tradução, atualize sua versão somente quando você realmente a tiver alinhado ao conteúdo mais novo da origem. ## Escreva na primeira pessoa do plural e mostre o exemplo antes da explicação Aplique estas convenções a todo o conteúdo, a menos que um guia local as substitua. - Use a primeira pessoa do plural inclusiva. O leitor é um colaborador trabalhando ao seu lado, não um aluno sendo instruído. Evite a forma "você deve" quando "nós" soar natural. - Mostre primeiro, explique depois. Um exemplo prático precede sua explicação; o leitor vê a coisa antes de ler sobre a coisa. - Mantenha os parágrafos curtos. Quando a informação ficar densa, converta-a em uma lista com marcadores ou em um bloco de exemplo, em vez de um parágrafo longo. - Use voz ativa. Use contrações de forma consistente em vez de formas formais expandidas. - Sem emojis. Sem lugares-comuns, sem preenchimento de elogios, sem frases que existem apenas para introduzir a próxima frase. - Use a vírgula serial. - Níveis de título: títulos de segundo nível para seções principais, terceiro nível para subseções. Nunca coloque um título de nível superior dentro do corpo do conteúdo — esse nível pertence ao título do documento. - Todo bloco de exemplo declara seu identificador de linguagem para que o renderizador possa destacá-lo corretamente. Corte tudo o que não ensina. Extensão não é uma virtude; um documento mais curto que um tradutor consiga renderizar fielmente vale mais do que um mais longo que se desvia. ## Organize cada aula: resumo, exemplos e temas relacionados Os documentos instrutivos seguem uma forma narrativa fixa: 1. Uma breve visão geral do que o documento cobre. 2. Motivação — por que isso importa — em no máximo duas ou três frases. Resista a expandir esta seção; é o lugar mais comum onde o preenchimento se acumula. 3. Conteúdo principal, conduzido por exemplos concretos com explicação após cada um. 4. Conexões externas: como este tópico se relaciona com material adjacente que o leitor já viu ou verá em seguida. Dentro do conteúdo principal, ordene o material do caso utilizável mais simples até as variações mais complexas, e apresente um termo antes de depender dele. Se um documento crescer para cobrir dois tópicos claramente separáveis, divida-o em vez de deixá-lo se espalhar — dois documentos focados traduzem melhor e ficam desatualizados de forma independente. O resumo no bloco de metadados deve poder ser escrito apenas a partir da visão geral. Se você não conseguir resumir o documento em uma ou duas frases, o documento está fazendo coisa demais. ## Adicione aulas ou idiomas novos e indique o registro necessário no site Novo documento de origem: crie o arquivo no diretório do idioma de origem, na categoria correta, com um bloco de metadados completo incluindo uma versão inicial. Depois, declare claramente se uma mudança complementar é necessária no aplicativo de publicação para registrar o novo documento para exibição. Não presuma que ele apareça automaticamente. Nova tradução: copie o arquivo de origem para o diretório do idioma de destino, no mesmo caminho de categoria e nome de arquivo, traduza o corpo e traduza os valores de metadados legíveis por humanos, como título e resumo. Deixe os nomes de campos estruturais e o valor da versão intactos — a versão precisa corresponder exatamente à da origem. Novo idioma: crie o conjunto completo de diretórios de categoria sob o novo código de idioma, para que a organização espelhe a de todos os outros idiomas, adicione os primeiros documentos traduzidos e registre o idioma no aplicativo de publicação. Uma pasta de idioma que existe mas não está registrada produz conteúdo que ninguém consegue acessar. Antes de escrever qualquer tradução, leia a nota de estilo específica daquele idioma, se houver uma. As notas locais cobrem escolhas de terminologia, transliteração de termos técnicos, pontuação e registro honorífico, e elas substituem o estilo geral da casa onde houver conflito. Se não existir nota local para um idioma para o qual você foi solicitado a traduzir, proponha criar uma em vez de inventar convenções silenciosamente. ## Use o relatório de status para atualizar primeiro as traduções mais defasadas O desvio de tradução é o modo de falha padrão de uma biblioteca multilíngue. Gerencie-o deliberadamente. Comece qualquer sessão de tradução executando o relatório de status sobre a biblioteca, em vez de navegar pelos diretórios manualmente. Filtre-o pelos idiomas pelos quais você é responsável e pelos níveis de gravidade que importam — documentos totalmente ausentes e documentos sinalizados como muito desatualizados vêm primeiro, o desvio leve em segundo, o desvio de nível de correção por último ou nunca. Regras de trabalho: - Não traduza um documento parcialmente e deixe a versão correspondendo à da origem. Uma tradução pela metade que se reporta como atualizada é pior do que uma claramente ausente. - Se precisar parar no meio do caminho, deixe a versão no valor anterior para que o relatório continue sinalizando o arquivo. - Não traduza por máquina e publique sem revisão em relação à nota local. - Quando a origem mudar depois que você começou, verifique novamente o diff antes de terminar; termine com base na versão que você realmente vai registrar. - Ao final, informe quais documentos você atualizou, quais deliberadamente pulou e por quê — o próximo colaborador faz a triagem a partir disso.