TKG Japanese-English Learner's Dictionary

# TKG Japanese-English Learner's Dictionary

This is the repository for a Japanese-English learner's dictionary delivered as a static website. Its production is being supervised by [Tom Gally](https://www.gally.net/about.html). All of the entry-writing and coding is being done by Claude in Claude Code for the Web, with some bug-hunting and improvement-suggesting by ChatGPT and Gemini.

**Live site**: https://www.tkgje.jp/

This dictionary is licensed under Creative Commons Zero v1.0 Universal, and anyone is free to copy the data and code for whatever purpose they like, including commercial uses.

## Overview

This dictionary is designed for learners of Japanese as a second language. It uses an original three-tier vocabulary classification system:
- **Basic tier**: About one thousand fundamental words essential for basic communication
- **Core tier**: About two thousand needed for adult-level communication
- **General tier**: All other vocabulary useful for learners

Dictionary features include:

- **Explanatory definitions** that go beyond simple glosses
- **Natural example sentences** optimized for learning
- **Usage notes** covering grammar, register, and common patterns
- **Furigana support** with toggle to show/hide readings above kanji
- **Kanji index** linking each kanji in headwords to all other entries containing that kanji
- **Multiple interface modes**: Search, Browse, Recent, and Random views
- **Cross-reference linking** with prominent top-of-entry links for homophones, verb pairs, and N/Nする pairs, plus structured "Related Words" boxes for antonyms, keigo, synonyms, and more
- **Inline word links** in example sentences allowing navigation to any word's entry
- **Transitivity and aspect information** for verbs
- **Collocation patterns** showing natural word combinations
- **Keigo (honorific) verb coverage** with usage guidance

Audio readings for example sentences will be added in the future.

## Current Status

- **Over 14,000 entries** across three vocabulary tiers
- **Vocabulary tiers**: Basic (801), Core (1,998), General (the rest) — all new entries are added to general tier
- **Many cross-references** linking related entries
- **Over 50,000 example sentences** with inline word links
- **Claude Code skills** for consistent entry creation and revision
- **Entry tracking system** with `entries_index.json` for current entries and `candidate_words.json` for future additions
- **Automated pipeline** for batch dictionary maintenance tasks
- **Robust build system** with atomic builds, XSS protection, and comprehensive validation
- **CI/CD** with GitHub Actions for validation and automated pipeline runs

## Target Users

Intermediate learners of Japanese who:
- Can read hiragana and katakana fluently
- Know some kanji and are building vocabulary
- Want to understand words fully, not just look them up quickly

## Technology

The dictionary is built as a **completely static website**:
- No server required—just open `index.html` directly in your browser
- No external dependencies—pure HTML, CSS, and JavaScript
- Offline-capable—download and use anywhere

## Site Structure

The dictionary is built as a static HTML site at `docs/`:

- **Individual pages**: Each entry has its own standalone HTML file
- **Lightweight pages**: Each page loads only the content needed
- **Deep linking**: Direct URLs to specific entries

### URL Structure

Entry pages are organized by numeric ID ranges (500 entries per directory):
```
docs/
├── index.html           # Home page
├── search.html          # Search interface
├── browse.html          # Browse by kana row
├── recent.html          # Recently modified entries
├── random.html          # Random word cloud
├── entries/
│   ├── 00000/           # Entries 00000-00499
│   │   ├── 00396_taberu.html
│   │   └── 00499_sakana.html
│   ├── 00500/           # Entries 00500-00999
│   ├── 01000/           # Entries 01000-01499
│   └── ...
└── kanji/               # Kanji index pages
    ├── 00001_teki_mato_target.html
    ├── 00009_jin_hito_person.html
    └── ...              # One page per kanji
```

This numeric range structure allows the dictionary to scale to 10,000+ entries while staying within GitHub's 1,000 files per directory limit.

## Web Interface

The dictionary provides four different ways to explore entries:

### Search Mode
Quick lookup by Japanese, romaji, or English. The traditional dictionary experience for users who know what word they're looking for.

### Browse Mode
Explore entries organized by:
- **Starting Kana**: あ行, か行, さ行, etc.
- **Vocabulary Tier**: Basic (801 fundamental words), Core (1,998 adult-communication words), General (all other vocabulary)

The dictionary uses an original three-tier classification system instead of JLPT levels. All new entries are added to the general tier.

### Recent Mode
View the most recently added or revised entries (up to 250). Each entry shows:
- **NEW**: Newly created entries
- **REVISED**: Updated existing entries
- Date

... (truncated)