O que você vai aprender#
- quais arquivos formam uma tradução, e o que é traduzido;
- como o glossário mantém os termos consistentes;
- como o site mostra uma página que ainda não foi traduzida, e como uma tradução desatualizada é encontrada.
A ideia#
O inglês é a fonte de verdade e o português do Brasil é a única tradução. Toda página em inglês site/content/docs/en/<dir>/<slug>.mdx tem um gêmeo em site/content/docs/pt-br/<dir>/<slug>.mdx. Apenas a prosa é traduzida: código, nomes de comandos e opções, códigos de erro, nomes de campos e identificadores continuam em inglês, e a estrutura e os destinos dos links permanecem idênticos, então um tradutor não consegue quebrar um link. As páginas de referência geradas têm texto em inglês nos dois idiomas e uma nota diz isso em português.
Uma página sem gêmeo em português ainda existe sob a sua URL /pt-br/. Ela mostra o texto em inglês sob um aviso acima do título, diz lang="en" no artigo, aponta o seu link canônico para a página em inglês, leva noindex e oferece um gêmeo em Markdown que começa com > Not translated yet.
Início rápido#
- Copie o arquivo em inglês para o mesmo caminho sob
pt-br/e traduza o front matter (title,description) e a prosa. - Use os termos de
site/content/glossary.json. Ele lista cada termo em inglês e em português, com uma nota quando a escolha não é óbvia. Um termo novo entra no glossário no mesmo pull request. - Mantenha os títulos um a um com a página em inglês, para que as mesmas seções apareçam na mesma ordem. Mantenha todo link, todo bloco de código e toda tabela de comandos inalterados.
- Execute as verificações a partir de
site/:
npm run check:mdx
npm run check:translations- Faça o commit com o cabeçalho
docs(site): translate <section> to pt-BR, e executenpm run last-updated.
Como a defasagem é encontrada#
O npm run check:translations lista cada página em inglês com o seu gêmeo em português e um status. Ele compara as datas de autoria dos commits que tocaram cada arquivo: a página é stale quando o arquivo em inglês mudou depois do gêmeo, missing quando o gêmeo não existe, e ok nos demais casos. As datas vêm do Git, então a verificação precisa do histórico completo.
Um commit que muda a página em inglês mas não o seu significado, como um erro de digitação, uma formatação ou a correção de um link, leva uma linha na sua mensagem para que não torne a tradução desatualizada:
Translation: not-neededA opção strict em site/content/translations.config.json é true, então uma página desatualizada ou ausente é uma falha; o npm run check:translations -- --strict força o mesmo para uma execução.
Erros comuns#
- Traduzir um comando, uma opção ou um código de erro.
E_WORKSPACE_LOCKEDcontinua como está na página em português. - Mudar um título, ou a ordem das seções: a revisão só aceita uma tradução quando os seus títulos coincidem um a um com a página em inglês.
- Escrever um link diferente na página em português. Escreva o mesmo link
/docs/...; o renderizador o reescreve para/pt-br/docs/.... - Usar o rodapé
Translation: not-neededem uma mudança que altera o que a página diz.