tbcl-syllabus

The 14,452 vocabulary entries from the Taiwan Benchmarks for the Chinese Language (TBCL), packaged as typed JSON for JavaScript and TypeScript. Each entry includes its level and source star marker, Traditional Chinese word, pinyin, bopomofo, band, situation category, frequency values, and dictionary references.

Install

npm install tbcl-syllabus

Usage

The package has a single default export:

import vocabulary from "tbcl-syllabus";

console.log(vocabulary.length); // 14452
console.log(vocabulary[0]);
// [1, [1, false], "愛", "ài", "ㄞˋ", "basic", "核心詞", 535, 681, [["愛", [39542]]]]

The raw JSON is also available through the tbcl-syllabus/vocabulary.json export:

import vocabulary from "tbcl-syllabus/vocabulary.json" with { type: "json" };

Data format

Every entry is a ten-element tuple, matching the ten source columns:

[1, [1, false], "愛", "ài", "ㄞˋ", "basic", "核心詞", 535, 681, [["愛", [39542]]]];

| Position | Type | Meaning | | -------- | ------------------------------------------------------------ | -------------------------------------------------------------- | | 0 | number | Sequence number from the source workbook | | 1 | [level: 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7, starred: boolean] | Normalized TBCL level and whether its source value has a star | | 2 | string | Traditional Chinese word or slash-separated variants | | 3 | string | Pinyin with tone marks | | 4 | string | Bopomofo | | 5 | "basic" \| "advanced" \| "proficient" | Normalized TBCL band | | 6 | string \| null | Situation category supplied by the source | | 7 | number | Written-language frequency value | | 8 | number | Spoken-language frequency value | | 9 | [word: string, ids: number[]][] | Source dictionary lookup words and their numeric reference IDs |

TypeScript infers the corresponding tuple types from the package declaration.

Normalization

The Chinese level wrappers are converted in place without adding a separate column. For example, 第1級 becomes [1, false], while 第1*級 becomes [1, true].

The source bands are normalized as follows:

| Source | Exported value | | ------ | -------------- | | 基礎 | basic | | 進階 | advanced | | 精熟 | proficient |

Numeric labels used by the source to distinguish entries are removed from each word or slash-separated variant. For example, 和1 is exported as 和, and 應該/應1 is exported as 應該/應. Use the sequence number as the unique identifier because the same normalized word can appear in multiple entries.

Dictionary reference IDs are converted from strings to numbers. Situation labels, pinyin, bopomofo, slash-separated variants, and frequency values otherwise preserve the workbook data.

Source and regeneration

The dataset comes from the official TBCL vocabulary data and search system. The repository keeps the source XLSX workbook in data/, and _generate.ts validates its schema while producing the published JSON.

To regenerate and verify vocabulary.json:

vp install
vp run generate
vp check
vp test

The npm tarball includes the generated data and package entry points, but not the source workbook, generator, or tests.

License

MIT