# 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.

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/contributing/translating/

## 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/`:

```bash
npm run check:mdx
npm run check:translations
```

5. 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

- [Escrevendo documentação](/docs/contributing/writing-docs)
- [Guia de contribuição](/docs/contributing/guide)
