koe-zukan (声図鑑)

A multilingual animal onomatopoeia search site. Search and compare animal sounds through their onomatopoeia in Japanese, English, Korean and Chinese.

日本語版は README.ja.md を参照してください.

Features

• Animal data and onomatopoeia (4 languages)
• Fuzzy search (covers Japanese names, English names, scientific names and onomatopoeia)
• Filter by class (Birds, Mammals, Insects, Amphibians, Reptiles, Fish and more)
• Switchable display language (日本語 / English / 한국어 / 中文)
• Image references to Wikimedia Commons, sound references to xeno-canto / Macaulay Library
• Fully static site — no backend needed, published on GitHub Pages (https://koe-zukan.semnil.com)

Quick Start

# Install dependencies
pip3 install --user --break-system-packages openpyxl Pillow

# Build (Excel → static site)
python3 scripts/build.py

# Local preview
python3 -m http.server 8080 --directory dist
# Open http://localhost:8080

Project Structure

koe-zukan/
├── .github/workflows/            # Tests and deploy to GitHub Pages, workflow checks, Dependabot auto-merge
├── assets/
│   └── favicon.svg               # Site icon (source of the PWA icons)
├── data/
│   ├── animal-sounds-data.xlsx   # Master data
│   └── no-audio.json             # taxonCodes with no audio in the Macaulay Library
├── scripts/
│   └── build.py                  # Generates JSON + HTML from Excel
├── templates/
│   ├── index.html                # Main page template
│   ├── species.html              # Species page template
│   └── icons.svg                 # SVG sprite of the UI icons
├── tests/                        # pytest and node --test tests
├── docs/                         # Decision records (docs/decisions/)
├── dist/                         # Build output (deployed, not tracked by git)
│   ├── index.html
│   ├── animals.json
│   ├── regions.json
│   └── species/{ID}/index.html
├── AGENTS.md                     # Detailed technical specification
├── README.md
└── README.ja.md

Deploy

Every pull request and every push to master run .github/workflows/deploy.yml, which runs the tests and builds the site with python scripts/build.py; a push to master also deploys dist/ to GitHub Pages. The site is published at https://koe-zukan.semnil.com.

A Dependabot pull request whose update is a patch or minor version is merged automatically once the required checks pass (.github/workflows/dependabot-auto-merge.yml).

Data Editing

The master data is kept in data/animal-sounds-data.xlsx. After editing the Excel file, run python3 scripts/build.py to regenerate dist/.

See AGENTS.md for the details of the data structure.

License

TBD