ai-for-dummies/.agents/skills/translation/references/tone.md

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 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.