从零到 C1 的西班牙语互动学习网站(手机 / 平板 / 电脑自适应,可安装为 PWA)。
English: Oliva is an open-source, Duolingo-style Spanish course for Chinese speakers, from zero to C1 (Spain Spanish with Latin American notes). It runs entirely in the browser — a static React + TypeScript site with no backend; progress stays on the device. Optional AI features use the learner's own Google Gemini API key. Includes listening / speaking / reading / writing practice, grammar with etymology, graded readings, spaced repetition, exams, AI-generated papers from textbook photos, and learning Spanish through songs.
npm install
npm run dev # 开发模式 http://localhost:5173
npm run build # 生产构建到 dist/
npm run preview # 预览生产构建
npm test # 变位引擎、答案判定、课程内容校验src/content/课程内容(每个单元一个 .ts 文件,按级别分目录),content.test.ts会校验全部内容并生成每一课src/lib/conjugate/动词变位引擎(规则 + 不规则表),src/lib/text/音节与重音src/lib/exercises/由单元数据生成课时、单元测试、自选考试src/lib/gemini/Gemini REST 客户端(流式)与提示词src/features/各页面:学习路径、做题器、语法、词书、阅读、复习、考试、设置
| 级别 | 单元 | 说明 |
|---|---|---|
| 起步 | 3 | 字母、发音、重音 |
| A1 | 10 | 自我介绍、家人、吃饭、购物、日常…… |
| A2 | 10 | 过去时、代词、命令式、比较、将来时 |
| B1 | 12 | 虚拟式、关系从句、间接引语、议论连接词 |
| B2 | 12 | 虚拟式过去时、非真实条件、让步、正式语域 |
| C1 | 10 | 名词化、焦点与强调、习语、方言、修辞 |
- 共约 4000 个单词(含每级额外词表),每个词附释义、例句、词源和拉美说法
- 106 篇分级短文,30 个情景对话场景(每级 6 个)
- 入门分级测试、单元测试、级别结业考、自由组合模拟卷
- 间隔重复(FSRS)记单词、错题本
在「设置 → AI 助手」填入自己的 Gemini API Key(只保存在本机浏览器)。
- 不用付费:在 aistudio.google.com/apikey 用 Google 账号免费创建 Key,不需要绑卡。Google AI Pro 会员本身不包含 API,但免费层足够个人学习使用。免费层的输入可能被 Google 用于改进产品。
- 自动选模型:默认自动选择最新的 Flash 模型;模型下线(404)会自动换一个,额度用完(429)会自动重试一次。
- 没有 Key 也能用:所有 AI 按钮都会把问题和上下文复制到剪贴板,并打开 gemini.google.com,用会员账号在官方网页里粘贴提问即可。
- 高音质朗读(可选):开启后用 Gemini TTS 朗读例句,音频缓存在本机(IndexedDB),每句只请求一次;失败时自动换回系统声音。
- 在中国大陆需要代理,或填写兼容 Gemini 接口的中转地址。
「考试 → 拍照出卷」:拍课本或讲义(或从相册多选),在照片上画框选出考查范围,设置五种题型(单词匹配、判断正误、单项选择 A/B/C、填空、听力)的题数(每种最多 50 题)和每题分值,由 Gemini 出一份卷子。
-
填了 API Key 时一次最多 100 个区域:超过 8 个会先分批读图、整理成单词 / 语法 / 例句材料,再按题型分别出题;读失败的部分可以单独重试,已读过的不重复读
-
照片和框选会自动保存在本机,刷新或切走后回来能继续,出完卷后自动清除
-
没有 API Key 时(最多 8 个区域):把框选内容保存成一张图,复制出卷要求到 Gemini 网页版,再把回复粘贴回来
-
出完可以逐题修改、按题型重新生成;做题按分值计分,错题按试卷归入错题本
-
打印 / 存为 PDF(答案页单独一页);导出试卷文件发给朋友,对方「导入试卷」后做同一份
-
照片会发给 Google Gemini 识别,免费 Key 的内容可能被用于改进产品
「阅读」页入口或侧栏「歌曲」:46 首精选西语歌(西班牙流行、拉美流行、唱作人 / 民谣、摇滚 / 经典,A2–C1),每首都核实过官方 YouTube 上传可嵌入、同步歌词时长一致。
- 同步高亮歌词,点词查义(词典没有的词可以 AI 查词),逐句停、单句循环、0.5 / 0.75 倍速、隐藏歌词听写
- 「学这句」:逐词释义、AI 讲解、加入生词本;「跟唱」:听原唱 → 自己唱,语音识别逐词标色,可录音回放
- AI 逐句翻译成中文(没有 Key 时复制到 Gemini 网页版再粘贴回来)
- 歌手页:简介、维基百科摘要、iTunes 上的其它作品(30 秒试听和 YouTube / Spotify / Apple Music 链接)
- 也可以粘贴 YouTube 链接添加任意歌曲;歌词库没有时手动粘贴歌词,跟着音乐点按对齐
歌词不包含在本应用里:播放时从开放歌词库 LRCLIB 获取(或由用户自己粘贴),版权归原作者所有,仅供个人学习。
localhost 只在自己电脑上有效,要让别人打开,需要放到静态托管上。
推荐:Netlify 连接 GitHub,自动部署
仓库里的 netlify.toml 已经写好了构建设置(先跑测试,再执行 npm run build,发布 dist/ 目录,Node 22)。在 Netlify 里把站点连接到这个 GitHub 仓库后,每次推送到 main 分支都会自动构建并上线;测试不通过时不会上线。
手动方式:npm run build 后,把 dist 文件夹拖到 Netlify 项目的 Deploys 页面。
每个人的学习进度和 Gemini Key 只保存在各自的浏览器里,互不影响。
- 代码:MIT
- 课程内容(
src/content/):CC BY-NC-SA 4.0,可以分享和改编,但需要署名、不能商用、改编后以相同许可发布 - 本仓库不包含任何歌词、音频或视频;第三方内容(YouTube、LRCLIB、维基百科、iTunes)的版权归各自所有者
欢迎提 Issue 和 Pull Request:发现读音、拼写、语法讲解或词源的错误,或者想补充内容,都可以直接提出。提交前请运行 npm test(包含内容结构检查和 Hunspell 拼写检查)。