bazi_translation/SKILL.md

name, description

name

description

bazi-translation

Simplified-Chinese-first BaZi/Four Pillars terminology dictionary and deterministic code/interface naming review workflow, including a Nexa BaZi system contract. Use when translating Chinese BaZi, Four Pillars, Chinese metaphysics, destiny analysis, Heavenly Stem/Earthly Branch, Ten Gods, Five Factors, luck cycle, or favorable-element terms into English; naming code identifiers, classes, files, API fields, database columns, JSON schema fields, prompt variables, UI labels, or documentation; or reviewing code for inconsistent or literal translations such as dayOwner, skyStem, groundBranch, fortuneColumn, useGod, Day_Master, Dominant_Deity, Primary_Favorite_Element, or mixed BaZi vocabulary.

BaZi Translation

Overview

Use this skill to keep BaZi terminology readable and consistent across code, UI labels, comments, docs, schemas, prompt variables, and tests.

The source of truth is simplified Chinese first. Use the approved English display term for user-facing text, and use the approved ASCII code name for identifiers unless an existing project convention is stronger.

Workflow

1. Read references/terms.md when translating or naming a BaZi concept.
2. Read references/naming-rules.md before reviewing code, schemas, APIs, or file names.
3. Run the checker when a local path is available:

python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py <path>

Use --no-fail for exploratory review and --list-approved to print approved code names.

4. For Nexa BaZi code, APIs, JSON schemas, prompt variables, and module keys, read references/nexa-bazi-contract.md, references/nexa-naming-rules.md, and references/nexa-forbidden-names.md, then run:

python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py <path>

Use --no-fail during migration planning and --min-severity error for CI-style blocking checks.

5. Report naming findings as concrete replacements: current name, approved name, reason, severity, and file/line when available.
6. When a concept is not in terms.md or the Nexa contract, do not invent a final translation. Add or propose a row in references/pending-terms.md with context and a provisional English/code name.

Standards

• Treat simplified Chinese as the primary key. Keep traditional Chinese and pinyin as aliases.
• Preserve book-style English for display labels when known, for example Favourable Element.
• Use project-local spelling for code when already established. If there is no project convention, default to American spelling in identifiers, for example favorableElement.
• Prefer established BaZi terms over literal translation: Day Master, Heavenly Stem, Earthly Branch, Luck Pillar.
• Keep Chinese, English display text, and code names separate. Do not force one field to serve all audiences.
• Do not conflate 用神 (Useful God, advanced concept) with 喜用元素 or 有利元素 (Favourable Element, beginner balancing element).
• Do not translate classical terms word by word when the approved table has a domain term.
• For programmer-facing Nexa contracts, prefer deterministic rules over vector/semantic matching. Vector search may help discover candidates, but it must not decide final names.
• In Nexa JSON/API fields, prefer snake_case; reserve PascalCase for type names and camelCase for language-local code when the host language expects it.

Resources

• references/terms.md: approved simplified-Chinese-first dictionary.
• references/naming-rules.md: code naming rules, anti-patterns, and review checklist.
• references/nexa-bazi-contract.md: Nexa BaZi interface and prompt-variable naming contract.
• references/nexa-naming-rules.md: Nexa-specific naming rules for APIs, JSON, module keys, and prompt files.
• references/nexa-forbidden-names.md: deterministic legacy/bad-name table used by the Nexa checker.
• references/pending-terms.md: staging area for terms needing domain review.
• scripts/check_bazi_names.py: scans source files for forbidden or suspicious BaZi translations and suggests approved names.
• scripts/check_nexa_bazi_contract.py: scans Nexa code/docs for mixed interface names and suggests contract names.