jpn_word_trainer_data/README.md

Japanese Word Trainer Deck Registry

This repository is the public word-deck data registry for the 0.3 package model. It keeps JSON as the source of truth and publishes zip package artifacts that the app can download and verify.

Layout

• registry.json is the root registry file read by the app.
• sources/official/<slug>/ contains editable official deck package JSON.
• sources/custom/<slug>/ contains editable published custom deck package JSON.
• packages/*.zip contains generated app-installable package artifacts.
• scripts/build_packages.py builds packages and refreshes registry checksums.
• scripts/validate_registry.py validates source JSON, packages, and checksums.

Each package zip contains exactly:

manifest.json
words.json
refs.json

Build

Run from the repository root:

python3 scripts/build_packages.py
python3 scripts/validate_registry.py

build_packages.py fills each word contentHash, creates deterministic zip files in packages/, and updates registry.json with wordCount, packageUrl, and sha256.

By default, generatedAt is left unchanged to avoid noisy rebuild diffs. Use --update-generated-at when intentionally publishing a freshly generated registry:

python3 scripts/build_packages.py --update-generated-at

Package Rules

• Stable deck keys use {registryId}:deck:{slug}.
• Stable word keys use {registryId}:word:{slug-or-id}.
• versionCode changes when package content changes.
• contentHash is computed from a word record excluding contentHash.
• refs.json owns deck membership and display order. A ref may point to a word supplied by the same package or to an already installed dependency such as an official deck word.
• The same package shape is used for official, registry custom, imported, and local-exported decks.

Current Decks

• official:deck:jlpt-n5 is a tiny official sample based lightly on the app seed vocabulary. It is not the full JLPT N5 set.
• community:deck:japan-travel-essentials is a cleaned custom deck generated from the user-provided Japan travel CSV, with example sentences added for app-side import and study testing.

This repository is still intentionally small so app migration, import, and checksum handling can be tested before the full public deck corpus is populated.