# Bilingual pages

## Write every page twice

The documentation publishes every page in English and in Brazilian Portuguese. English is the source of truth. Write the Portuguese page on top of the finished English page, not in parallel with it. The structure of the Portuguese page follows the English page, and a change to the English page creates matching work on the Portuguese page.

To write or update a Portuguese page, open the English page first. If the English page does not exist, write it first: a Portuguese page written first has no source, and the 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:

```
en:     title:     Create an Object Storage bucket
        permalink: /documentation/guides/application-development/data/create-and-modify-bucket/
        namespace: documentation_products_object_storage_bucket

pt-br:  title:     Criar um bucket do Object Storage
        permalink: /documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket/
        namespace: documentation_products_object_storage_bucket
```

Each frontmatter field follows one of three rules on the Portuguese page:

| Field         | Portuguese page                |
| ------------- | ------------------------------ |
| `title`       | translated                     |
| `description` | translated                     |
| `permalink`   | translated                     |
| `namespace`   | identical to English           |
| `meta_tags`   | conventionally left in 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](/en/documentation/style-guide/conventions/frontmatter/).

## Localize directories and permalinks

Localize directory names and filenames; do not copy the 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:

```
English page:    [Applications](/en/documentation/platform/applications/)
Portuguese page: [Applications](/pt-br/documentacao/plataforma/applications/)
```

A Portuguese page links to an English page only when no Portuguese translation exists. Never send the reader to English when a Portuguese page exists.

## Write English that survives translation

The 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](/en/documentation/style-guide/writing/sentence-structure/) carry over to 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 Portuguese vocabulary lives in [Documentation terminology](/en/documentation/style-guide/writing/terminology/).

## Apply the translation rules

Five rules cover most of the work on a Portuguese page:

- Do not translate generic technical terms: `data center`, `serverless`, `template`, `compliance`, `on-premise`. The strings `edge` and `edge computing` stay untranslated where they already appear, but new text does not introduce them.
- Do not translate product names: **Applications**, **Functions**, **Firewall**, **Azion Platform**, **Azion Marketplace**.
- Apply the substitutions: `aplicação`, not `aplicativo`; `rede distribuída`, not `borda`, when translating existing text; `performance`, not `desempenho`. New Portuguese text that names where the platform runs writes `infraestrutura distribuída`.
- Write titles in sentence case: capitalize the first word and proper nouns only.
- Localize aside labels: `:::note[nota]`, `:::tip[dica]`, `:::caution[Atenção]`. An English label on a Portuguese page is a visible defect.

The full stay-in-English list is in [Documentation terminology](/en/documentation/style-guide/writing/terminology/).

## Use the fixed 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 Portuguese forms:

- `## Prerequisites` becomes `## Pré-requisitos`.
- `## Next steps` becomes `## Próximos passos`.
- `## Related resources` becomes `## 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 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.