# Reference: translation tone

The register is **editorial-technical Brazilian Portuguese**: the voice of a
native technical writer writing for an audience of engineers, not for casual
readers. It is not academic, not corporate, not marketing. The site teaches
working professionals how to use AI tools, and the Portuguese reads like that —
direct, opinionated, occasionally witty.

These notes are derived from the existing translations in `src/content/**` and
`.agents/snapshots/full-guide-pt.json`. They are not universal truths; they are
the conventions this site already established. If you find a translation that
does not match these notes, the notes are right and that translation needs
review.

## Voice in one paragraph

> Second-person (`você`), imperative verbs (`Use`, `Verifique`, `Selecione`),
> short sentences, no hedging. Acronyms in caps (`SONNET`, `HAIKU`, `CHECK`),
> prose around them in lowercase sentence case. The writer takes a position:
> "use isto", "não faça aquilo". The reader is a colleague being shown a shape,
> not a customer being reassured.

## Person and number

- **Second person, informal `você`.** The English mixes imperative and second
  person; the Portuguese collapses both into `você`. Impersonal "you" (general
  advice) becomes second-person imperative or third-person generic (`o agente`,
  `um worker`) — match the source intent.
  - "Use when …" → `Use quando …` (imperative) **or** `Use em …` (infinitive
    noun phrase, used in `commonSkills/*` field labels).
  - "You do not need …" → `Você não precisa …`.
- **First person plural** ("we / let's") is rare in the corpus. When the English
  uses it, prefer `vamos` for invitations and `nós` only when the English
  clearly means "the project team".

## Imperative vs infinitive

The skill catalog (`commonSkills/*.json`) uses infinitive noun phrases in the
`use` field: "Use when …" → `Use quando …` / `Use em …`. This is a compact
register — the noun phrase stands on its own as a label. The prose body (`copy`,
`rule`, `example`, `caution`) uses full sentences, often imperative: "Stop at
the first rung that holds." → `Pare no primeiro degrau que sustenta.`

Match the source field:

| Field            | Register                  | Verb form        |
| ---------------- | ------------------------- | ---------------- |
| `use`            | compact noun phrase       | infinitive       |
| `rule`           | one imperative sentence   | imperative       |
| `example`        | a worked instance         | declarative past |
| `caution`        | one or two sentences      | imperative       |
| `kind` / `label` | title case in caps        | noun             |
| `tagline`        | short noun phrase         | noun             |
| `copy`           | one or two full sentences | varies           |

## Verb mood and tense

- **Imperative** for instructions: `Pare`, `Use`, `Selecione`, `Consulte`,
  `Mantenha`, `Corte`. Same register as the English.
- **Present indicative** for general truths and current state:
  `É orientação descobrível` ("This is discoverable guidance").
- **Present subjunctive** when the English uses "should" / "may":
  `Siga as instruções para que o sistema funcione`.
- **Past participle** for completed actions in results/evidence:
  `Construído. Testes passaram. Publicado.` (kept as past-tense fragments
  matching the staccato cadence of the English.)

## Sentence cadence

- **Short sentences.** Read the existing translations — they break long English
  sentences at natural joints, not at the original clause boundaries.
  - "Trace claims to owners." (EN, 4 words) → `Leve afirmações até suas fontes.`
    (PT, 5 words)
  - "Reconnect the diff to intent with fresh context and adversarial attention."
    (EN, 11 words, one sentence) →
    `Reconecte o diff à intenção com contexto novo e atenção crítica.` (PT, 9
    words, one sentence — restructured, not literal)
- **Lists of three.** When the English has a three-beat rhythm, preserve it:
  "construção, integração, evidência" / "orquestração, execução, verificação".
- **Avoid nominalizations.** "Give every worker enough context, one
  responsibility, and its own worktree." →
  `Dê a cada worker contexto suficiente, uma responsabilidade e seu próprio worktree.`
  The English is verbs; the Portuguese keeps it verbs.

## Hedging and certainty

- The site does not hedge. "Probably", "usually", "we recommend" are absent from
  the existing copy. If the English has them, translate the certainty away in
  the Portuguese: "Recommended:" → `:` (drop the qualifier), "Should:" → `:` or
  `Esperado:`.
- Numbers and tokens are precise: `8 verificações`, `200 linhas`, `01 / 2026`.
  Do not round.
- "Maybe" / "perhaps" → omit in Portuguese. The reader either needs to know or
  doesn't, and the corpus always opts for "needs to".

## Capitalization

- **Sentence case for prose.** "Strong model for ambiguity." →
  `Modelo forte para ambiguidade.` The Portuguese follows the source's sentence
  case, not Portuguese title case.
- **Title case (ALL CAPS) for tab labels and tags.** `PLAN` / `BUILD` /
  `REVIEW`, `CONTEXTO` / `REVISÃO`, `INSTINTO DE SIMPLIFICAÇÃO`,
  `DISCIPLINA DE CONCLUSÃO`. Match the source field by field; the design system
  depends on the visual weight of caps.
- **Lowercase for tagline noun phrases.** `signal without filler` →
  `sinal sem excesso`. Source is lowercase; target stays lowercase.
- **Acronyms stay all caps.** `SKILL.md` is rendered as `SKILL.md`, not
  `Skill.md`. `AGENTS.md` similarly. `pnpm`, `npm`, `git`, `cli` are lowercase
  by convention.

## Symbol and punctuation rules

- **Arrows.** `→` for in-flow ("observe → trigger → validate"), `↗` for off-page
  links ("format specification ↗"). Keep the spaces.
- **Em dash.** `—` (U+2014, with spaces). The English uses this too; preserve in
  the Portuguese.
- **Center dot.** `·` between list items, e.g.
  `8 skills · 3 agents · 4 enforcement layers` →
  `8 skills · 3 agentes · 4 camadas de enforcement`. The space matters for the
  design grid.
- **Smart quotes.** Never. The legacy HTML uses straight quotes; the Astro build
  keeps them straight; do not introduce curly quotes.
- **`<i></i>` and `<b></b>`** glyphs from the source — copy verbatim. They are
  decorative and the stylesheet depends on them. Do not turn them into `<em>` or
  `<strong>`.
- **`<br>` and `<br />`** — keep the source's exact form (the chapter hero uses
  `<br />` with space; the recall section uses `<br>` without). Visual fidelity
  beats XML purity here.

## What NOT to do (recurring mistakes)

- **Don't be polite at the reader's expense.**
  - "Please select a submission" → `Selecione um envio` (no "por favor").
  - "We hope this helps" → drop it; the site never apologizes.
- **Don't translate product names.**
  - `Opus`, `Sonnet`, `Haiku`, `GPT-5.6`, `Sol`, `Terra`, `Luna`, `Pro`,
    `Flash`, `Flash-Lite` — keep English. The user knows these are model names.
- **Don't gender the reader.** The Portuguese addresses `você` (singular,
  gender-neutral). Avoid `o usuário` when `você` reads better, and never use
  feminine-default forms that imply a specific reader gender.
- **Don't add articles where the source omits them.** English often drops the
  article in tab labels; the Portuguese matches.
  - "From intent to evidence" → `Da intenção à evidência`.
  - "Try the rules lab →" → `Experimente no lab Tiny Tasks →`. (Wait, actually
    this is a full sentence ending with the arrow; the article is preserved
    where the source has it. Match the source.)
- **Don't introduce code-style formatting where the source has prose.**
  - `<i></i>` is _not_ `<em>`. `<b>PLAN</b>` is _not_ `<strong>PLAN</strong>`.
    These have specific visual weight in the stylesheet.
- **Don't reorder facts.** The English leads with X, the Portuguese leads with
  X. Reordering is a content edit, not a translation.

## Reading order: how to absorb this skill

1. Read [`references/glossary.md`](glossary.md) once for the term decisions.
2. Skim 5–10 random translations from `commonSkills/*.json` to feel the voice.
3. Skim `src/content/rules/copy.json` `pt` block — it is the longest prose
   passage and sets the editorial register.
4. Skim `.agents/snapshots/full-guide-pt.json` — it is the shipping Portuguese
   on the largest surface and the longest consistent voice sample.
5. Now propose. Write the first chapter; show it to a human; iterate on the tone
   before continuing to the next chapter.
