Skip to content

Organize game terminology and create a cross-language reference glossary #131

@smly

Description

@smly

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

  1. Decide on canonical terms for each concept as used in the RiichiEnv repository (code identifiers, documentation, UI labels).
  2. 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
  3. Document protocol-specific terms (MJAI, Tenhou, Mjsoul) alongside the canonical terms, noting where they diverge.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions