Alego Translate Docs

Translating Alego docs

Invocation boundary

Run this extended workflow only when the user explicitly invokes alego-translate-docs by name. Never select or load it for ordinary documentation work, from another skill, or from an inferred translation need; routine translation follows the one-shot, one-pass rule in docs/AGENTS.md.

What this skill is

This skill is guidance, not a translation memory. It is the workflow map for keeping foo.md ↔ foo.zh.md pairs consistent and natural in both languages. Both languages carry equal authority — a change is authored in either one, and that side is the source for that update. You are the translator: the rules below say what must hold, not how to phrase any particular sentence — phrasing judgment is yours, terminology is not.

Triage by change type — this decides everything else

• Update (pair exists, one side edited): follow the update path. It is briefing-driven and deliberately cheap: no guidance-corpus reading, no git archaeology, smallest counterpart edit. Never re-translate a whole document to apply an update — a minimal update preserves the reviewed phrasing of everything that didn't change; a re-translation throws that review away.
• New pair (no counterpart yet): follow the whole-document path.
• Deleted or renamed doc: delete or rename the counterpart and the .i18n.yaml alongside it — the gate reports an incomplete pair otherwise.

Frozen Agent Notes under .agents/notes/archived/ are not translation work. Their complete triplets are sealed by the archive verifier; never update, re-record, or repair either side after archival.

The update path (briefing-driven)

The briefing-driven path matches guidance-corpus quality at a fraction of the cost; the archived briefed-updates Agent Note records the benchmark evidence.

1. Generate the briefing: pnpm run gen-translation-brief <any file of the pair> (no arguments briefs every out-of-sync pair). The briefing maps the change at the narrowest safely aligned granularity — changed Markdown units (paragraph, table row, list item, heading), then whole heading sections, then whole document — and contains the authored side's diff since the last confirmed-consistent state, each changed unit's last-confirmed source, current source, and current counterpart text (with line numbers), the terminology rows the change touches, first-occurrence movement notes, and a digest of the binding update rules.
2. Mechanical-only diff? --apply it. When every change lies inside code fences that the pair shares byte-identically, the briefing says so; pnpm run gen-translation-brief --apply <pair> splices the edited fences into the counterpart and structure-validates the result before writing — no subagent, no hand-editing.
3. Prose diff? Delegate to a subagent, passing the briefing (or the command to generate it). The briefing is the translator's whole working set — the subagent does not re-read the guidance corpus (the rules digest, terminology rows, and each changed unit's three-way context are inline) and does not re-derive the diff. It escalates to the whole-document path's sources of truth only when the briefing leaves a specific decision genuinely unanswerable — an unlisted term with no precedent in the surrounding text, or a whole-document briefing (BOTH sides changed, or neither units nor sections align), which always means reconciling by hand under translation-rules.md.
4. Smallest edit that covers the diff. Preserve the reviewed phrasing of everything the diff does not touch, then verify the changed hunks clause by clause against the source: nothing added, nothing dropped, terminology per the inline rows, code spans verbatim.
5. Record and verify, scoped: pnpm run verify-translation-pairing --write <pair> then pnpm run verify-translation-pairing <pair>. --write names exactly the pairs you confirmed — it refuses to run bare so a bulk re-record is always an explicit --all. The corpus-wide check still runs in doc-sync/CI; do not run it per-update.

The whole-document path (new pairs)

When translations need to be written from scratch, the orchestrating agent does not translate: spawn a subagent to do the translation work. The translator reads the sources of truth below first, then translates the whole file into the other language — section by section for long documents, keeping each section's structure locked to the source as you go rather than fixing structure at the end.

Sources of truth (read, don't re-summarize)

• docs/i18n/README.md — the pairing contract: the three-file pair (foo.md, foo.zh.md, foo.i18n.yaml), the consistency record's per-section hashes, the language-switcher lines, scope, and exclusions.
• docs/i18n/translation-rules.md — how to translate: faithfulness, structure preservation, terminology discipline, typography (MUST/SHOULD levels).
• docs/i18n/terminology.md — the terminology table, binding in both directions. Load it BEFORE translating, not when a term feels uncertain; the terms you don't notice are the ones that drift.
• docs/i18n/translation-prompt.md — the automated pipeline's calibrated machine-consumed template. Agents using this skill do not render it; the terminology table is the only repository file the automated renderer injects, while this skill and translation-rules.md remain binding for agent-authored translations.
• alego-prose-standard — required prose coverage and editorial judgment. Apply it to both sides without adding or dropping source propositions.