Ir para o conteúdo

Contribuindo

Traduzindo a documentação

Como as páginas em português do Brasil são escritas, mantidas em dia com as em inglês e verificadas.

Última atualização:

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#

  1. Copie o arquivo em inglês para o mesmo caminho sob pt-br/ e traduza o front matter (title, description) e a prosa.
  2. 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.
  3. 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.
  4. Execute as verificações a partir de site/:
Terminal
npm run check:mdx
npm run check:translations
  1. Faça o commit com o cabeçalho docs(site): translate <section> to pt-BR, e execute npm 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:

Text
Translation: not-needed

A 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_LOCKED continua 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-needed em uma mudança que altera o que a página diz.

Próximos passos#