# Vocabulary sources and licenses

## Japanese: JMdict (CC BY-SA 4.0)

This application uses the **JMdict Japanese-English dictionary**, copyright **James William Breen and the Electronic Dictionary Research and Development Group (EDRDG)**. The dictionary was started by Jim Breen. JMdict is used in conformance with the [EDRDG license](https://www.edrdg.org/edrdg/licence.html).

- [JMdict project and documentation](https://www.edrdg.org/wiki/index.php/JMdict-EDICT_Dictionary_Project)
- [Creative Commons Attribution-ShareAlike 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/)
- [Full license legal code](https://creativecommons.org/licenses/by-sa/4.0/legalcode)
- JSON conversion provided by [scriptin/jmdict-simplified](https://github.com/scriptin/jmdict-simplified), distributed under the original dictionary license.

**`data/japanese.mjs` is an adaptation of JMdict and is distributed under CC BY-SA 4.0.** This does not require the application code to use that license. The adaptation selects common readings and one English dictionary sense, preserves its part of speech and English synonyms, converts kana to Hepburn-style romaji, excludes archaic, dialectal, explicitly vulgar and specialist senses, and assigns approximate practice tiers. Typed English answers also accept equivalents without parenthetical notes or a leading “to”, so “fall” works for “to fall (over, down)”. Reading and spelling restrictions are respected. No endorsement by EDRDG is implied.

The initial snapshot uses JMdict dated **2026-10-26**. Actual upstream URLs, snapshot date and archive SHA-256 hashes are recorded in `data/provenance.json`. Dictionary entries retain upstream entry IDs for review.

Japanese tiers are **practice heuristics, not official JLPT levels**: short common readings with at most one kanji in the source spelling favor the beginner tier; ordinary two-kanji/medium-length words favor intermediate; longer readings and compounds favor advanced. Loanwords can be easier than their assigned tier suggests. Kana and kanji are not displayed during play. The 24 authored beginner starter words remain separately maintained.

## English: WordNet 3.0

English dictionary definitions and synonyms are drawn from **WordNet 3.0**, copyright **2006 by Princeton University. All rights reserved.** Used under its permission to use, copy, modify and distribute the database. The complete required notice and disclaimer are included in [WORDNET-LICENSE.txt](./WORDNET-LICENSE.txt); preserve this file when distributing the application or data.

The source archive is published in the [NLTK data distribution](https://github.com/nltk/nltk_data). `data/english.mjs` selects individual lowercase words, a dictionary sense, its part of speech, and accepted synonyms. Example sentences are omitted. Definitions are not invented or shortened mid-sentence. The 24 authored English starter words remain separately maintained.

English tiers combine **word length and tagged sense frequency** in WordNet: frequent short words favor beginner; moderately frequent words favor intermediate; less frequent/longer words favor advanced. These are approximate teaching tiers, **not CEFR certification**. Ambiguous words are accompanied by their part of speech. Source synset IDs are preserved. Eligible synonyms are accepted in typed recall and excluded as multiple-choice distractors.

## Idioms, jargon and Norwegian words (original content)

`data/idioms-en.mjs`, `data/idioms-ja.mjs`, `data/idioms-no.mjs`, `data/jargon.mjs`, and `data/words-no.mjs` are **original Vocab Voyage content** and are not derived from JMdict, WordNet, or any phrase book or dictionary. The expressions themselves are short, widely used phrases; the plain-language meanings, example sentences, literal translations, example translations, and difficulty tiers were written for this project. No text was copied from third-party idiom lists. Because they contain no JMdict or WordNet text, these files are not covered by the CC BY-SA or WordNet notices above and are distributed with the rest of the application.

Counts: English idioms 86, Japanese idioms 46, Norwegian idioms 56; English jargon 69, Japanese workplace terms 18, Norwegian workplace expressions 18; Norwegian words 130. Japanese is written in Hepburn-style romaji with no kana or kanji. Norwegian is Bokmål. These sets were written by hand and have not been reviewed by native speakers; treat them as a learning aid and correct errors you find. Tiers reflect commonness and how figurative an expression is. Entries whose meanings overlap closely were removed so multiple-choice questions have one clearly best answer.

## Selection, counts and updates

There are **1,224 distinct English words and 1,224 distinct Japanese romaji entries**: 1,200 selected dictionary words plus 24 starters in each language. Each dictionary selection has 400 words per tier. Duplicate romaji (including `oo`/`ou` long-vowel equivalents), duplicate English words, and duplicate canonical definitions within a language are excluded. Japanese dictionary senses can be narrower than an everyday translation; each quiz teaches one selected sense, not every usage of a word.

To keep JMdict current, **refresh at least monthly and before a public release**:

```sh
npm ci
npm run vocab:build
npm test
npm run check
```

The builder downloads the latest common-word English JMdict JSON release and WordNet 3.0, regenerates the bundled modules and provenance, and fails if any tier cannot supply all 400 distinct entries. Review the regenerated sample words and commit the updated data and provenance. Downloads happen only during this maintainer command; the playable app does not contact dictionary services.

For reproducing the initial snapshot from locally cached ZIP archives:

```sh
node tools/build-vocabulary.mjs PATH_TO_WORDNET_ZIP PATH_TO_JMDICT_ZIP
```

The initial pinned JMdict release is `3.6.2+20261026175559`. The build-only ZIP reader (`fflate`) and kana romanizer (`wanakana`) are MIT-licensed development dependencies; neither is loaded by the playable app.