The codebase currently uses a mix of English, Japanese romaji, and abbreviated terms for the same mahjong concepts. This creates confusion for contributors and users. We should establish a canonical set of terms used within the repository and provide a cross-language reference table that includes Japanese, English, and Chinese equivalents.
Background
Examples of inconsistent or mixed terminology in the current codebase:
- Meld/Call terminology:
furo (副露), naki (鳴き), and call / meld are used interchangeably across files. CALL_TYPES in riichienv-ui/src/constants.ts uses chi, pon, daiminkan, kakan, ankan, while Python code also references these via different naming.
- Yaku names:
YAKU_MAP in constants.ts uses English transliterations (e.g., "Menzen Tsumo", "Rinshan Kaihou"), while the Rust/Python Yaku class provides both name (Japanese) and name_en (English).
- Round terminology:
kyoku (局), round, and game are sometimes ambiguous.
- Action terms:
dahai (打牌) vs. discard, tsumo used both for drawing a tile and for a self-draw win.
- Protocol dependency: The MJAI protocol uses specific event type names (e.g.,
dahai, tsumo, hora, reach) that cannot be renamed.
Goals
- Decide on canonical terms for each concept as used in the RiichiEnv repository (code identifiers, documentation, UI labels).
- Create a glossary document (e.g.,
docs/glossary.md) mapping each concept across:
- Canonical term used in the codebase
- Japanese (kanji + romaji)
- English
- Traditional/Simplified Chinese, Pinyin
- Document protocol-specific terms (MJAI, Tenhou, Mjsoul) alongside the canonical terms, noting where they diverge.
- Evaluate Chinese support: As part of this effort, assess how Chinese tile names and game terms could be integrated into the UI and API (e.g., locale-aware yaku names in
YAKU_MAP).
Non-Goals
- Full i18n framework integration is out of scope for this issue. The focus is on establishing the term reference and choosing canonical identifiers. A follow-up issue can address runtime language switching.
- Renaming all existing protocol-dependent identifiers (e.g., MJAI event types) is not intended.
The codebase currently uses a mix of English, Japanese romaji, and abbreviated terms for the same mahjong concepts. This creates confusion for contributors and users. We should establish a canonical set of terms used within the repository and provide a cross-language reference table that includes Japanese, English, and Chinese equivalents.
Background
Examples of inconsistent or mixed terminology in the current codebase:
furo(副露),naki(鳴き), andcall/meldare used interchangeably across files.CALL_TYPESinriichienv-ui/src/constants.tsuseschi,pon,daiminkan,kakan,ankan, while Python code also references these via different naming.YAKU_MAPinconstants.tsuses English transliterations (e.g., "Menzen Tsumo", "Rinshan Kaihou"), while the Rust/PythonYakuclass provides bothname(Japanese) andname_en(English).kyoku(局),round, andgameare sometimes ambiguous.dahai(打牌) vs.discard,tsumoused both for drawing a tile and for a self-draw win.dahai,tsumo,hora,reach) that cannot be renamed.Goals
docs/glossary.md) mapping each concept across:YAKU_MAP).Non-Goals