japanese/docs/LEARNER.md

jlearn — 日语学习资料生成器

从权威库（汉字|分段:假名|分段:拼音|分段 格式）生成多维学习资料， 帮助以中文为母语的学习者借助拼音掌握日语汉字读音。

安装

在项目根目录：

pip install -e .

安装后即可使用 jlearn 命令；也可用 python -m pl_japanese.learner.cli 调用。

用法

# 列出所有可生成的资料类型
jlearn list

# 用默认权威库生成全部资料到 ./study_materials
jlearn generate

# 指定权威库和输出目录
jlearn generate --vocab data/db/vocabulary.txt --output-dir study_materials

# 只生成指定类型（逗号分隔）
jlearn generate --only handbook,anki

生成的资料

类型	文件	说明
overview	overview.txt	数据总览：一字多音分布、高频核心字
handbook	kanji_handbook.txt	汉字读音手册：每个单字按读音分组 + 例词
jukujikun	jukujikun.txt	熟字训词表：整词对应一读音、无法拆字的条目
pinyin	pinyin_kana_mapping.txt	拼音→汉字→假名对照表：从母语拼音出发，按汉字分组
pinyin-kana	pinyin_kana_kanji_mapping.txt	拼音→假名→汉字对照表：按假名分组，发现读音规律复用（如 an→あん 在 安/暗/案 中都成立）
rules	phonetic_rules.txt	音读规律：拼音与假名的对应模式统计
anki	anki_deck.txt	Anki 卡片（TSV，正面日文词 / 背面假名+拼音）
html	study_app.html	交互式单页应用：拼音·汉字·假名多维互链查询，可搜索，离线可用

交互式 HTML 应用（推荐）

study_app.html 是一个自包含的单页应用（约 1.4 MB），双击即可在浏览器打开，无需服务器：

• 多维索引 — 拼音、汉字、假名三个入口，互相超链接
• 点击导航 — 点拼音看对应汉字，点汉字看所有读音，点假名看所有汉字，任意跳转
• 音训读标注 — 每个读音标注 [音读]/[训读]，蓝色/橙色区分
• 全文搜索 — 顶部搜索框输入拼音、汉字或假名，直达结果
• 离线分享 — 单文件，发给别人直接用

数据全部内嵌，依赖 Vue 3（从 CDN 加载，首次打开需联网；如需完全离线可自行改为本地 Vue）。

代码结构

• builder.py — StudyDataBuilder：加载权威库，预建高效索引 （(汉字,假名)→拼音 反查、单字/熟字训区分）
• generators.py — 文本类资料生成器 + GENERATORS 注册表 + _classify_reading（音训读判断）
• html_generator.py — 交互式 HTML 单页应用生成器
• cli.py — jlearn 命令行入口

新增一种资料：在 generators.py 写 gen_xxx(builder, out_dir) -> Path， 然后加进 GENERATORS 字典即可，CLI 会自动识别。

Anki 导入

anki_deck.txt 为 TAB 分隔的两列（正面/背面），背面用 <br> 分隔假名与拼音。 在 Anki 中「文件 → 导入」，字段分隔选 Tab，允许 HTML 即可。