bazi_translation/README.md

bazi_translation

Codex skill for BaZi translation and naming review. It keeps BaZi/Four Pillars terms consistent across Chinese source terms, English display labels, and code identifiers.

The skill is simplified-Chinese-first:

• 简体 is the concept key.
• 标准英文 is for UI/docs when an English label is needed.
• 代码名 is for identifiers, API fields, classes, schemas, and tests.

The source PDF is not included in this repository.

This repository also includes a Nexa BaZi contract checker for programmers. It catches mixed API fields, JSON schema names, prompt variables, and module keys such as Day_Master, DayMaster_Stem, Dominant_Deity, and Primary_Favorite_Element.

Install

Clone the repository and copy it into Codex skills:

git clone git@git.aplexlogic.com:fireparty/bazi_translation.git
mkdir -p ~/.codex/skills
rsync -a --delete bazi_translation/ ~/.codex/skills/bazi-translation/

Validate the skill:

python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/bazi-translation

Use In Codex

Invoke the skill by name:

Use $bazi-translation to review BaZi naming in src/bazi.

Typical requests:

Use $bazi-translation to translate these terms into approved English and code names: 日主, 天干, 地支, 大运, 用神.

Use $bazi-translation to review API field names in packages/bazi.

For Nexa:

Use $bazi-translation to review Nexa BaZi API fields, prompt variables, and module keys in nexa_bazi-main.

Use The Generic Checker

Run the local checker against files or directories:

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

Exploratory review without failing the command:

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

List approved code names:

python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py --list-approved

Example output:

src/chart.ts:42: dayOwner -> dayMaster
  zh: 日主; standard_en: Day Master
  line: const dayOwner = chart.dayOwner;

Use The Nexa Contract Checker

Run the Nexa-specific checker against code, JSON, prompt files, or docs:

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

Migration planning mode:

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

CI-style blocking mode, reporting only hard errors:

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

List loaded Nexa rules:

python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py --list-rules

Example output:

5 八字详解/5.7 命理符号/2.命理符号-算法与判定规则.md:14: DayMaster_Stem -> day_master_stem [error]
  concept: 日主天干
  reason: mixed case 不适合接口契约
  line: DayMaster_Stem: "辛"

Severity handling:

• error: do not add in new code; rename or add a compatibility migration.
• warn: likely wrong for new BaZi fields; check whether it is already published.
• review: not automatically unsafe, but it may show cross-system leakage or a published key that needs migration planning.

Core Naming Rules

• Use dayMaster, not dayOwner or dayLord.
• Use heavenlyStem, not skyStem.
• Use earthlyBranch, not groundBranch.
• Use luckPillar, not fortuneColumn.
• Use usefulGod, not useGod.
• Use favorableElement in code by default; keep Favourable Element for book-style display text.
• Keep Useful God separate from Favourable Element.
• For Nexa JSON/API/prompt fields, use snake_case: day_master, day_master_stem, dominant_ten_god, primary_favorite_element.
• Do not use deity for Ten Gods in interfaces. Use ten_god.
• Do not use astrology terms such as astral_event for BaZi branch relationships or daily BaZi events.

Nexa Contract Files

• references/nexa-bazi-contract.md: canonical Nexa BaZi API/JSON/prompt naming contract.
• references/nexa-naming-rules.md: practical naming rules and migration guidance.
• references/nexa-forbidden-names.md: deterministic bad-name table used by the checker.

Files

• SKILL.md: Codex skill trigger and workflow.
• references/terms.md: simplified-Chinese-first dictionary.
• references/naming-rules.md: review rules and anti-patterns.
• references/nexa-bazi-contract.md: Nexa BaZi interface and prompt-variable naming contract.
• references/nexa-naming-rules.md: Nexa-specific naming guidance.
• references/nexa-forbidden-names.md: Nexa forbidden/legacy name table.
• references/pending-terms.md: staging area for terms needing domain review.
• scripts/check_bazi_names.py: source-code naming checker.
• scripts/check_nexa_bazi_contract.py: Nexa BaZi API/JSON/prompt naming checker.