---
name: translation
description:
  Translate site copy to Brazilian Portuguese in a register and vocabulary that
  match the existing translated collections. Use when adding a new localized
  field, auditing a chapter for missing or identical en/pt pairs, or proposing
  translation candidates for review. Always pair with
  [`../../rules/content-i18n.md`](../../rules/content-i18n.md).
---

# Translation

This site is bilingual EN/PT-BR. The English is editorial; the Portuguese has to
read like a native technical writer, not like a machine. The glossary
([`references/glossary.md`](references/glossary.md)) and tone notes
([`references/tone.md`](references/tone.md)) pin the conventions so any agent —
me, a different LLM, a future you — produces Portuguese that matches what is
already there.

## Before anything

Read [`../../rules/content-i18n.md`](../../rules/content-i18n.md) and
[`../../context/content-i18n.md`](../../context/content-i18n.md). Both are
binding. In particular:

- Both `en` and `pt` are required on every `localized` field. A missing `pt`
  must fail the build.
- These are hand-written translations with deliberate tone. **Copy, do not
  retype.** Retyping introduces drift.
- The site's bilingual contract is client-side: both languages ship in the
  payload, the toggle swaps visibility. Do not propose `/en/` `/pt/` routing
  without a separate decision.

## Audit before you propose

Run the audit script first. It walks `src/content/**` and reports every
`localized` field where `en === pt`:

```bash
node .agents/scripts/audit-translations.mjs
```

The script exits non-zero on any identical pair. That is the list you work from
— chapter, file, field. Touch only what's flagged, and only after a human has
reviewed your proposal for the first chapter (the tone is contagious: if the
first chapter is right, the rest fall into the same voice).

## Propose, do not commit

This skill is **review-first**. The workflow is:

1. Pick the smallest chapter (today: `landing.json`, 30 fields). Read the
   English, read the existing translations in the other collections to absorb
   the voice, then write candidates.
2. Show the diff to a human reviewer. They sign off on tone, terminology, and
   register before you proceed to the next chapter.
3. Only after the reviewer agrees, write the JSON. Re-run the audit; it must
   pass.
4. Repeat for the next chapter.

Auto-committing a translation in bulk is the same failure mode as a content
migration that "passes" by deleting assertions: silent monolingualism. The
review step is the whole point.

## What stays in English

Some terms are kept in English by deliberate convention. Do not translate:

- Code identifiers, file paths, command names, product names (`SKILL.md`,
  `AGENTS.md`, `.agents/skills/`, `git`, `pnpm`, `claude`, `opus`, `sonnet`,
  `haiku`, `gpt-5.6`, `sol`, `terra`, `luna`)
- Product surface nouns that the team has decided to keep: `skill`, `worktree`,
  `worker`, `branch`, `merge`, `commit`, `diff`, `brief`, `gate`, `pipeline`,
  `recall`, `prompt`
- The `<i></i>` and `<b></b>` glyphs that ship in copy — they are decorative and
  the stylesheet depends on them
- Arrows used as connectors (`→`, `↗`) — keep them, the spacing is intentional

The full list is in the glossary.

## What to translate

Everything else, including:

- Section titles, ledes, eyebrows
- Card titles, body copy, call-to-action labels
- Stage / phase labels in prose ("PLAN", "BUILD", "REVIEW" stay uppercase
  English because they are acronyms in the design system; the prose around them
  translates)
- Inline `<em>` emphasis and `<br>` line breaks — the structure is shared, the
  words differ

## Verification

After writing, before committing:

```bash
pnpm run build                     # schema check (both locales present)
node .agents/scripts/audit-translations.mjs   # en !== pt everywhere
pnpm run verify                    # full gate, includes rendered snapshots
```

A rendered snapshot diff in `verify.mjs` catching a new Portuguese string is
expected. Update `.agents/snapshots/*.txt` if the prose really did change and
the snapshot was a stale capture. Do not delete assertions to make it pass.

## What this skill does NOT do

- Migrate content out of legacy `app.js` (that's `content-migration`)
- Wire `lang` state into chapter pages (that's tasks 12 / 13 / 15)
- Edit `src/content/config.ts` (the schema is `verification-engineer`'s scope)
- Touch components, layouts, styles, or the legacy tree
- Translate code, comments inside code blocks, command output, or paths

The chapter's review-desk body (`src/content/reviews/*.md`) is intentionally not
localized — the review desk is an English-only editor by design.