# Translating the documentation

> How the Brazilian Portuguese pages are written, kept in step with the English ones and checked.

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

## You will learn

- which files make a translation, and what is translated;
- how the glossary keeps terms consistent;
- how the site shows a page that is not translated yet, and how a stale translation is found.

## The idea

English is the source of truth and Brazilian Portuguese is the only translation. Every English page `site/content/docs/en/<dir>/<slug>.mdx` has a twin at `site/content/docs/pt-br/<dir>/<slug>.mdx`. Only prose is translated: code, command and flag names, error codes, field names and identifiers stay in English, and the structure and the link targets stay identical, so a translator cannot break a link. The generated reference pages have English text in both languages and a note says so in Portuguese.

A page with no Portuguese twin still exists under its `/pt-br/` URL. It shows the English text under a notice above the title, says `lang="en"` on the article, points its canonical link to the English page, carries `noindex` and offers a Markdown twin that begins with `> Not translated yet`.

## Quick start

1. Copy the English file to the same path under `pt-br/` and translate the front matter (`title`, `description`) and the prose.
2. Use the terms of `site/content/glossary.json`. It lists each term in English and in Portuguese, with a note when the choice is not obvious. A new term goes in the glossary in the same pull request.
3. Keep the headings one to one with the English page, so that the same sections appear in the same order. Keep every link, every code block and every table of commands unchanged.
4. Run the checks from `site/`:

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

5. Commit with the header `docs(site): translate <section> to pt-BR`, and run `npm run last-updated`.

## How staleness is found

`npm run check:translations` lists each English page with its Portuguese twin and a status. It compares the **author dates** of the commits that touched each file: the page is `stale` when the English file changed after the twin, `missing` when the twin does not exist, and `ok` otherwise. Dates come from Git, so the check needs the full history.

A commit that changes the English page but not its meaning, such as a typo, formatting or a link fix, carries a line in its message so that it does not make the translation stale:

```text
Translation: not-needed
```

The flag `strict` in `site/content/translations.config.json` is `true`, so a stale or missing page is a failure; `npm run check:translations -- --strict` forces the same for one run.

## Common mistakes

- Translating a command, a flag or an error code. `E_WORKSPACE_LOCKED` stays as it is in the Portuguese page.
- Changing a heading, or the order of the sections: the review accepts a translation only when its headings match the English page one to one.
- Writing a different link in the Portuguese page. Write the same `/docs/...` link; the renderer rewrites it to `/pt-br/docs/...`.
- Using the footer `Translation: not-needed` on a change that does alter what the page says.

## Next steps

- [Writing documentation](/docs/contributing/writing-docs)
- [Contributing guide](/docs/contributing/guide)
