Skip to content

About

从零到 C1 的西班牙语互动学习网站 · A Duolingo-style Spanish course for Chinese speakers, zero to C1 (PWA, React + TypeScript, optional Gemini AI)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Oliva 橄榄西语

从零到 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

在「设置 → 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 拼写检查)。

About

从零到 C1 的西班牙语互动学习网站 · A Duolingo-style Spanish course for Chinese speakers, zero to C1 (PWA, React + TypeScript, optional Gemini AI)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages