Bilingual pages
Pair the US English and Brazilian Portuguese versions of a page by namespace, with localized permalinks, language-prefixed links, and the translation rules.
Write every page twice
The documentation publishes every page in US English and in Brazilian Portuguese. US English is the source of truth. Write the Brazilian Portuguese page on top of the finished US English page, not in parallel with it. The structure of the Brazilian Portuguese page follows the US English page, and a change to the US English page creates matching work on the Brazilian Portuguese page.
To write or update a Brazilian Portuguese page, open the US English page first. If the US English page does not exist, write it first: a Brazilian Portuguese page written first has no source, and the US English page that follows becomes a translation of a translation.
Pair the versions by namespace
The site pairs the two versions of a page by their namespace field, not by file path. The language switcher depends on this pairing. Both files carry the same value, character for character:
Each frontmatter field follows one of three rules on the Brazilian Portuguese page:
| Field | Brazilian Portuguese page |
|---|---|
title |
translated |
description |
translated |
permalink |
translated |
namespace |
identical to the US English page |
meta_tags |
conventionally left in US English |
A mismatched namespace breaks the language switcher, and the build passes anyway. Nothing warns you, so check the value character for character before the page ships. The rules for each field are in Frontmatter.
Localize directories and permalinks
Localize directory names and filenames; do not copy the US English tree. guides/ becomes guias/, and create-bucket.mdx becomes criar-bucket.mdx. Permalinks follow the same rule: /documentation/products/... becomes /documentacao/produtos/....
Permalinks stay ASCII in both languages. Fold accents instead of encoding them: configuracao, not configuração.
Link with the right language prefix
Internal links are absolute, start with a language prefix, and end with a slash. The same link changes only its prefix between the two versions:
A Brazilian Portuguese page links to a US English page only when no Brazilian Portuguese translation exists. Never send the reader to a US English page when a Brazilian Portuguese page exists.
Write US English that survives translation
The US English page sets the translator’s task. A short sentence translates one to one. A 45-word sentence with three subordinate clauses forces the translator to restructure it, and restructuring is where meaning drifts.
The structural rules in Sentence structure carry over to Brazilian Portuguese unchanged. Sentence caps, one instruction per step, simple tenses, active voice, and short noun clusters all transfer. The vocabulary rules do not carry over; the Brazilian Portuguese vocabulary lives in Documentation terminology.
Apply the translation rules
Six rules cover most of the work on a Brazilian Portuguese page:
- Do not translate generic technical terms:
data center,serverless,template,compliance,on-premise,authoritative DNS. The stringsedgeandedge computingstay untranslated where they already appear, but new text does not introduce them. - Do not translate Platform Resource names or other Azion names: Applications, Functions, Firewall, Azion Platform, Azion Marketplace. The instance keeps the name too:
uma Function,as suas Applications. Never replace a name with a Portuguese description of it:firewall de aplicação webfor Web Application Firewall,gerenciamento de botsfor Bot Manager,armazenamento de objetosfor Object Storage, andfunçõesfor Functions each hide the name the reader looks for. - Apply the substitutions:
aplicação, notaplicativo, only for the customer’s own software, because the instance created in Azion is anApplication;rede distribuída, notborda, when translating existing text;performance, notdesempenho. New Brazilian Portuguese text that names where the platform runs writesinfraestrutura distribuída. - Write the phrase a Portuguese reader uses, not the English sentence word for word:
experimentarambecomesexperienciaramorvivenciaram,nenhum servidor sozinho carrega toda elabecomesnenhum servidor fica sobrecarregado, andnunca consulta uma APIbecomessem a necessidade de consultar uma API. - Write titles in sentence case: capitalize the first word and proper nouns only.
- Localize aside labels:
:::note[nota],:::tip[dica],:::caution[Atenção],:::danger[perigo]. The casing follows the repository usage:nota,dica, andperigoin lowercase,Atençãocapitalized. A US English label on a Brazilian Portuguese page is a visible defect.
The full list of terms that stay in US English is in Documentation terminology.
Use the fixed Brazilian Portuguese forms
Three recurring elements translate the same way on every page. Do not improvise a new form for them.
Three section names have fixed Brazilian Portuguese forms:
## Prerequisitesbecomes## Pré-requisitos.## Next stepsbecomes## Próximos passos.## Related resourcesbecomes## Recursos relacionados.
The standard link sentences have fixed forms, and the verb is consulte:
Para mais informações, consulte [Título](/pt-br/.../).Para <fazer algo>, consulte [Título](/pt-br/.../).
Console UI labels stay as the interface shows them. Do not translate button or field names the Console renders in US English: Save, Workloads Access, + Bucket.
Review every translation
Never ship a machine translation without review. A wrong translation is harder to find and fix than a missing one, because the page looks complete. Use machine translation for a first draft only, and review the draft before it ships.