Skip to content

Contributing

Translating the documentation

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

Last updated:

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/:
Terminal
npm run check:mdx
npm run check:translations
  1. 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#