nguyenvanphituoc Translator (harness language gate)
The one job upstream of the whole harness: make the input English, faithfully, once. The harness is English-only end to end — the planner, generator, and judge all assume English and HARD-FAIL on anything else. This skill is the single component that guarantees that assumption holds. It is not a translator that rewrites; it normalizes language while preserving every requirement, number, boundary, and structural element 1:1.
PO writes intake (any language) → TRANSLATOR → <name>.en.md (English) → ba-pitch-analyzer → …
(this skill) + glossary.md + report
Scope is deliberately narrow (simplicity first):
- ✅ Translate input docs (pitch / PRD / requirement / transcript) into English copies.
- ✅ Emit a persisted glossary so domain terms map consistently across docs and runs.
- ✅ Verify the output is English and structurally identical to the source.
- 🚫 Does NOT plan, build, or judge — that is the harness's job.
- 🚫 Does NOT translate harness output back to the PO's language (input-normalization only).
- 🚫 Does NOT summarize, add, drop, or "improve" content — faithful 1:1 only.
What is preserved verbatim vs translated, glossary protocol, verification scan →
references/preservation-rules.md— read it before translating any file.
Workflow Overview
INPUT: doc(s) in any language
│
⏸ GATE T0 │ Detect & Scope ──────► per-file source-language detection; list files to
│ translate; already-English files → skipped (idempotent)
│
▶ Phase 1 │ Glossary ────────────► extract domain terms + proper nouns + do-not-translate
│ tokens; map source→English; reuse existing glossary.md
⏸ GATE T1 │ Glossary Review ──────► PO confirms term mappings; ambiguous terms resolved here
│ (never guessed). lite/auto: auto-proceed on unambiguous.
│
▶ Phase 2 │ Translate ───────────► WRITE <name>.en.md (original untouched): prose → English,
│ glossary applied; frontmatter keys, wikilinks, code, URLs,
│ numbers preserved
│
▶ Phase 3 │ Verify ──────────────► residual-non-English scan + structural diff (heading /
│ link / code-block / list-item counts must match source)
⏸ GATE T2 │ Output Sign-off ──────► confirm clean scan + matching structure, then emit
│ glossary.md + translation-report.md (the .en.md is already
│ written in Phase 2)
✅ Done └─► English intake ready for the harness
GATE T0 — Detect & Scope
Purpose: Decide what needs translating before spending tokens, and stay idempotent.
T0.1 For each input file/path, detect source language (sample headings + body prose,
ignore code blocks / identifiers / URLs).
T0.2 Classify:
already-English → SKIP (no .en.md written; report it as pass-through)
non-English → queue for translation
mixed → queue; flag the English spans to keep verbatim
T0.3 In --check mode: print the classification table and STOP. Write nothing.
(This is the mode tech-lead calls at GATE L0 to decide whether to run a full pass.)
GATE T0 Output:
⏸ GATE T0 — Detect & Scope
Files : [N] (translate: [k] · already-English: [N-k])
Source lang : [vi | mixed | …]
Glossary : [reuse docs/glossary.md | build new]
Mode : [full | --check (detect only)]
Under --check: stop here. Otherwise proceed to Phase 1 (auto) or wait for confirm (interactive).
Phase 1 — Glossary
Goal: One consistent English term per source term, across every doc and every run.
Inconsistent vocabulary is the failure that poisons downstream DDD extraction (the planner
treats two spellings as two concepts). Read references/preservation-rules.md#Glossary first.
1. Reuse: if a glossary.md exists (or --glossary <path> given), load it as the base map.
2. Extract from the source: domain nouns, actor names, status/enum values, screen names,
feature jargon. Propose source→English for each new term.
3. Mark do-not-translate tokens: proper nouns, brand/product names, code identifiers, API
names, env vars, file paths — these pass through verbatim (see preservation-rules).
4. Flag ambiguous terms (one source word → multiple valid English terms) for GATE T1.
Output: draft glossary.md (source term · English · note/do-not-translate flag).
GATE T1 — Glossary Review
Purpose: Lock vocabulary with the PO before it propagates into every translated doc.
Print the new/changed term rows + any ambiguous terms.
Ask (max 2): confirm the English term for each ambiguous entry; any term to force
verbatim (do-not-translate)?
Never guess an ambiguous domain term — a wrong canonical term cascades into the spec.
--auto / --lite: auto-proceed when no term is ambiguous; if any is, still pause (a
wrong term is more expensive than a pause).
Phase 2 — Translate
Goal: Faithful English copy. Read references/preservation-rules.md first.
For each queued file, write <name>.en.md (sibling of the source; original untouched):
- Translate prose values only. Apply the glossary to every domain term.
- PRESERVE verbatim: YAML frontmatter KEYS, [[wikilink]] targets, `code`/```fenced```,
URLs, file paths, numbers, units, appetite/boundary values, do-not-translate tokens.
- Keep document structure 1:1: same headings, same table rows, same list items, same
order. No merging, no reordering, no summarizing.
- Mixed-language source: leave already-English spans as they are.
Faithfulness rule: the .en.md must carry exactly the requirements of the source — nothing
added, nothing dropped, no editorializing. Translation ≠ rewriting.
Phase 3 — Verify
Goal: Prove the output is English and structurally identical before sign-off.
3.1 Residual-non-English scan: scan every .en.md for source-language characters/words
outside code blocks / do-not-translate tokens. Any hit → list file:line, do NOT pass.
3.2 Structural diff vs source: heading count, table-row count, list-item count, wikilink
count, code-block count must match. Mismatch → a requirement was dropped/added → fail.
3.3 Glossary coverage: every extracted term resolved (no "⏳ TBD" left in glossary.md).
A failing scan blocks GATE T2 — emit the residual list and fix before signing off.
GATE T2 — Output Sign-off
⏸ GATE T2 — Output Sign-off
Translated : [k] files → <name>.en.md
Glossary : glossary.md ([t] terms, [a] resolved-ambiguous)
Residual scan: ✅ clean | 🔴 [n] non-English spans → [file:line …]
Structure : ✅ matches source | 🔴 [diff]
On clean → ✅ Intake English-ready: [files]. Point the harness at the .en.md copies.
Under --auto/--unattended: auto-sign-off only if the residual scan is clean; a dirty
scan always stops (never ship half-translated intake to the harness).
Output files
| File | Purpose | Notes |
|---|---|---|
<name>.en.md |
The English copy the harness consumes | One per translated source; original is never overwritten |
glossary.md |
source→English term map | Persisted + reused; the shared vocabulary for this feature |
translation-report.md |
detect table, glossary diff, verification result | Audit trail; what was skipped/flagged |
Destinations (two-root workspace). <name>.en.md is written as a sibling
of its source (or under --out <dir> when given) — when the source already lives under the SHARED root
shapeup/<slug>/shaping/, the copy lands there too. glossary.md is durable
shared vocabulary → write it to shapeup/<slug>/shaping/glossary.md.
translation-report.md is run-trace (audit) → write it to the LOCAL root
.shapeup/<slug>/translation-report.md. When run standalone on loose intake files
(no slug yet), all three default to siblings of the source.
Envelope contract — the domain layer
Orchestrated, this skill is dispatched like every worker: a WorkOrder in (--order <path>,
operation translate), a WorkResult out. The standalone arguments below map 1:1 onto the
payload fields registered for this worker in the central domain registry
(skills/tech-lead/schemas/domain.schema.json, x-payload-by-worker):
| Payload field | Standalone form | Meaning |
|---|---|---|
payload.intake[] |
positional path(s) | Source docs to normalize to English — originals never overwritten |
payload.glossary |
--glossary |
An existing glossary.md to reuse as the base term map |
The WorkResult may carry only files_touched, artifacts, assumptions, deviations
(x-result-by-worker): the .en.md copies, glossary, and verification report return as
artifacts; ambiguous-term resolutions made without a PO land in assumptions.
Invocation
# Translate one intake file → docs/pitch.en.md (+ glossary.md, translation-report.md)
/translator docs/pitch.md
# Translate a folder of intake docs (already-English files are skipped)
/translator docs/intake/
# Reuse / extend an existing glossary for consistent vocabulary across runs
/translator --glossary docs/glossary.md docs/pitch.md
# Detect-only: is this English? print the table and stop (what tech-lead L0 calls)
/translator --check docs/pitch.md
# Headless: skip gates; still HARD-STOPS on a dirty residual scan
/translator --auto docs/pitch.md
Flags
| Flag | Effect |
|---|---|
--check |
Detect source language and report; write nothing, stop at GATE T0 |
--glossary <path> |
Load an existing glossary as the base map (consistency across docs/runs) |
--auto |
Skip T0/T1 confirmation gates; still pauses on ambiguous terms + dirty scan |
--unattended |
Auto-sign-off all gates; stop only on a dirty residual scan or hard error |
--out <dir> |
Write .en.md copies into a target dir instead of beside the source |
Hard Rules (never override without explicit user instruction)
| Rule | Rationale |
|---|---|
Never overwrite the source; always write a .en.md copy |
The PO still needs to read their original |
| Never summarize, add, or drop content — faithful 1:1 | The harness builds exactly what the spec says; drift here is silent scope change |
| Preserve frontmatter keys, wikilink targets, code, URLs, numbers verbatim | Structure is load-bearing for downstream parsing; translating it breaks the spec tree |
| One source term → one English term, via the glossary | Two spellings read as two concepts to the planner's DDD pass |
| Ambiguous term → ask at GATE T1, never guess | A wrong canonical term cascades into every doc and every build round |
| Already-English input → no-op (idempotent) | Re-runs and --check must be safe and cheap |
Dirty residual scan blocks sign-off, even under --auto |
Half-translated intake makes the harness HARD-FAIL mid-run — worse than stopping here |
| Input-normalization only — never translate harness output back | This is the upstream gate; output language is a separate, out-of-scope concern |
Relationship to the harness
TRANSLATOR (this skill) → ba-pitch-analyzer (PLAN) → task-executor (BUILD) → spec-evaluator (JUDGE)
language gate English-only specs English-only code English-only verdict
- The harness is English-only end to end; the downstream skills HARD-FAIL on non-English.
tech-leaddoes not translate — at GATE L0 it runs/translator --check, and if intake is non-English it runs a full/translatorpass first, then orchestrates against the.en.mdcopies. Orchestration and language normalization are separate single-purpose concerns.