| name | terminology-management |
| description | Use when creating, editing, validating, or enforcing glossary-driven terminology. |
Terminology Management
Overview
Maintain glossary quality and enforce terminology consistency across all translated content.
Core principle: Glossary is the source of truth; validation must run before and after any terminology update.
The Process
Step 1: Load Glossary Baseline
- Load
glossary.json.
- Confirm schema validity:
uv run python scripts/validate_glossary.py
- Create TodoWrite items for candidate generation, decisions, and verification.
Step 2: Generate and Classify Candidates
Run:
uv run python scripts/term_generate.py --min-frequency 2
Then immediately pre-calculate evidence for all candidates in one pass:
uv run python scripts/term_cal_batch.py
This scans the corpus once and caches counts + context for every candidate.
Subsequent term_edit.py calls hit the cache; no re-scanning needed.
Classify each candidate as:
- managed game term
- normal prose (not managed)
If proper_nouns.mode != keep_original, repeated proper nouns (>=2) must be managed.
Step 3: Edit Glossary Safely
For unmanaged terms, evidence is read from cache (populated by term_cal_batch.py):
uv run python scripts/term_edit.py --term "<TERM>" --set-zh "<ZH_TERM>" --status approved --mark-term
To inspect evidence for a single term without editing:
uv run python scripts/term_edit.py --term "<TERM>" --cal
If the corpus changed since the last batch run, re-run term_cal_batch.py to refresh the cache.
Step 4: Validate Usage Across Docs
Run:
uv run python scripts/term_read.py --fail-on-forbidden
Check for:
- missing managed terms
- inconsistent variants
- unintended untranslated residual English terms
Step 5: Apply Fixes and Recheck
- Apply approved replacements where needed.
- Re-run
term_read.py until clean.
Progress Sync Contract (Required)
- Track each term candidate and decision with TodoWrite.
- Mark a term item complete only after
term_read.py is clean for that change.
When to Stop and Ask for Help
Stop when:
- glossary policy conflicts are unresolved
- a term has culturally nuanced ambiguity affecting tone/mechanics
- bulk changes risk unintended semantic shifts
When to Revisit Earlier Steps
Return to Step 2 when:
- corpus changes significantly
- proper noun policy changes
Red Flags
Never:
- bypass glossary schema validation
- leave inconsistent managed terms unresolved
Next Step
Continue with /check-consistency, /translate, or /super-translate.