Translator
Skill nguyenvanphituoc/shapeup-sdlc-plugin/skills/translator
Use this skill whenever intake for the harness (pitch, PRD, requirement, transcript, or any spec input) is in a non-English language and must be normalized to English BEFORE planning/building. The single language gate for the planner→generator→judge harness. Triggers on: "translate this pitch", "normalize to English", "this requirement is in Vietnamese", "prepare intake for the harness", "make the spec English", "check if this is English", and Vietnamese "dịch sang tiếng Anh", "chuẩn hoá tiếng Anh", "dịch pitch", "chuyển yêu cầu sang tiếng Anh". Produces faithful English copies (original never overwritten) plus a glossary and verification report. tech-lead auto-invokes it at GATE L0 when intake is non-English; also runs standalone.From its SKILL.md
npx -y skills add nguyenvanphituoc/shapeup-sdlc-plugin --skill translatorAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
12.8 KB, as published. Nobody here has run it
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.
What ships with it: 3 files
9.6 KB alongside SKILL.md
evals/
- trigger-evals.json1.4 KB
references/
- preservation-rules.md5.0 KB
- README.md3.2 KB
Gives 0 of the 12 instructions most docs writing skills give
Counted across 1,951 of the 3,904 authors here whose files we hold, read 2026-09-06
- Use third-person for skill descriptionsin 54 of 1951, across 35 files
- Start descriptions with Use whenin 43 of 1951, across 29 files
- Run baseline scenarios before writing any skillin 40 of 1951, across 26 files
- Use active voicein 40 of 1951, across 36 files
- Map file responsibilities before defining tasksin 36 of 1951, across 29 files
- Use checkbox syntax for tracking stepsin 35 of 1951, across 27 files
- Ask one question at a timein 35 of 1951
- Offer execution options after saving the planin 33 of 1951, across 24 files
- Include complete code in every stepin 33 of 1951, across 27 files
- Design units with clear boundaries and interfacesin 31 of 1951, across 23 files
- Announce the skill usage at the startin 30 of 1951
- Verify agent compliance after adding the skillin 29 of 1951, across 17 files
Said here and by no other author read
- write English copies as .en.md files
- maintain 1:1 structural parity with source
- use a glossary for consistent domain terminology
- scan for residual non-English text
- verify structural counts match the source
- reuse existing glossary files when provided
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.