LinguaCafe

LinguaCafe 是一个免费、可自托管的沉浸式阅读和词汇学习工具。它把书籍、文章、字幕、网页及科研文档整理成可交互文本，让学习者在真实语境中查词、标记词汇和短语，并在之后进行复习。

本文介绍当前 main 分支：它保留上游 LinguaCafe v0.14.1 的主要能力，并加入可靠的简体中文界面、完整中文手册、PDF/Markdown/HTML 自动转换、后台整理性能控制，以及面向 FreeLingo 的词汇导出增强。

English README / 英文原文

当前分支的主要增强

简体中文界面

• 界面支持 English 与简体中文切换，选择会写入浏览器存储和 cookie。
• 书库、阅读器、词汇、复习、汉字、登录、用户设置和主要管理页面均已接入 Vue i18n。
• 动态计数、日期、表单校验、错误反馈、空状态和后台任务状态均提供中文文案。
• 服务名、协议字段、语言名称和 HTTP 方法等专有数据保持原样，避免错误翻译。

中文使用手册

应用内手册会根据界面语言读取对应文档。manual/zh/ 包含：

• 首页与手册导航。
• 安装、Docker、备份、字典及外部服务设置。
• 日常使用和主要功能。
• FAQ 与杂项说明。

英文原文仍保留在 manual/ 根目录，缺失本地化页面时服务会安全回退到英文。

原生 PDF、Markdown 和 HTML 上传

书库导入界面新增“PDF / Markdown / HTML”来源，支持：

• .pdf
• .md
• .markdown
• .html
• .htm

文件上传后在 Linux 服务器内自动转换为纯文本，再进入 LinguaCafe 原有的章节拆分、tokenizer 和词汇统计流程。转换使用受限的服务器进程、文件类型检查、大小限制和输出上限。

PDF 只支持包含可提取文本层的文件。扫描版 PDF、图片 PDF 和文本量过低的文件会明确报错，目前不执行 OCR。加密、损坏或不支持编码的文档也会被拒绝。

自适应后台整理性能

导入长文档后，章节分词、词数统计和不重复词整理都在 Linux 后台 worker 中执行。当前分支提供三种模式：

• 稳定：一次处理 1 个章节，锁竞争风险最低。
• 平衡：最多同时处理 2 个章节，可能更快，但数据库压力更高。
• 自动：根据待处理队列、近期失败、服务器负载、数据库活动和最近章节耗时，在 1–2 个并发之间选择。

书库页面会显示：

• 已处理、剩余和失败章节数。
• 当前有效并发和自动决策原因。
• 根据近期样本估计的剩余时间及可信度。
• 预计逻辑 CPU 和 PHP worker 内存上限。

检测到数据库死锁、章节失败或高负载时，自动模式会降到单 worker 并进入安全冷却。章节状态更新也经过前端缓冲，减少大量后台事件导致 Chrome 界面卡顿。

FreeLingo 导出增强

词汇 CSV 导出在原有字段之外增加：

• 项目类型（单词或短语）。
• LinguaCafe 项目 ID。
• 从保存文本中还原的例句。

这些字段让外部 pipeline 可以只选择用户明确标记为学习阶段的单词、搭配、词块或科学术语，再导入 FreeLingo；两个应用仍保持独立数据库和独立复习系统。

上游核心功能

书库和导入

• 按书籍和章节管理阅读材料，可使用封面、列表、详细和表格布局。
• 支持纯文本、文本文件、EPUB、字幕、网站、YouTube 字幕和 Jellyfin 字幕。
• 支持编辑、删除和重新处理书籍或章节。
• 统计总词数、不重复词数、已掌握词、已标记词和新词。

交互式阅读

• 点击或悬停查询单词，查看原形、读音、翻译、词典结果和上下文。
• 标记词汇掌握阶段，保存短语和例句。
• 可调整字体、字号、行高、颜色、词汇标记和阅读器布局。
• 支持章节列表、术语表、快捷键以及适配窄屏的底部词汇面板。

词汇与复习

• 搜索、筛选、编辑、导入和导出单词或短语。
• 按学习阶段、书籍、章节、文本和翻译筛选。
• 使用类似 Leitner 的间隔重复流程复习词汇。
• 支持每日目标、日历、阅读统计、高亮统计和长期进展。
• 可以导出到 Anki 或其他支持 CSV 的工具。

字典和语言工具

• 支持内置或可导入词典，以及 DeepL、LibreTranslate、MyMemory 和自定义 API 字典。
• 日语支持假名/汉字工具，中文支持拼音和相应词典资源。
• 可以安装、卸载和配置不同学习语言的 tokenizer、词典和字体。

支持的学习语言

上游支持 27 种语言：中文、克罗地亚语、捷克语、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、意大利语、日语、韩语、拉丁语、马其顿语、挪威语、波兰语、葡萄牙语、罗马尼亚语、俄语、斯洛文尼亚语、西班牙语、瑞典语、泰语、土耳其语、乌克兰语和威尔士语。

不同语言在分词、读音和词典方面的支持程度并不完全相同，详细信息请参阅上游 Wiki。

技术架构

• Web：Laravel 11、PHP 8.2、Vue 2、Vuetify、Vuex、Vue Router、Vue i18n。
• 数据库：MySQL 8。
• 队列和缓存：Redis、Laravel Horizon。
• 实时更新：Laravel Reverb/WebSocket，默认端口 6001。
• 分词：独立 Python tokenizer 容器。
• 文档转换：Poppler pdftotext 与 Pandoc，运行在 Web/worker 容器中。
• 部署：Docker Compose。

目录结构

LinguaCafe/
├── app/                    # Laravel 控制器、服务、任务和模型
├── database/               # 迁移、种子及本地数据库挂载目录
├── docker/                 # Web 与测试镜像 Dockerfile
├── manual/                 # 英文手册
│   └── zh/                 # 中文手册
├── resources/js/           # Vue 前端和 i18n
├── scripts/                # 验证、冒烟和运维脚本
├── storage/                # 上传、转换结果、封面和运行数据
├── tests/                  # PHPUnit 与文档导入 fixtures
├── docker-compose.yml      # 基础 Compose
├── README.md               # 中文说明
└── README_EN.md            # 上游英文说明

Docker 快速开始

要求：x86-64 Linux、Docker 和 Docker Compose。Apple Silicon 需要按上游安装说明增加平台兼容设置；Raspberry Pi 等其他 Armv8 设备目前不在上游支持范围内。

git clone ssh://git@tmytimidly.com:222/CounterAttack/LinguaCafe.git
cd LinguaCafe
docker compose up -d

默认 Web 地址：

http://localhost:9191
http://<Linux-LAN-IP>:9191

首次打开时创建的第一个用户会成为管理员。

构建当前分支源码

基础 Compose 默认引用发布镜像。若要运行当前 main 分支的中文化和文档导入增强，可创建 docker-compose.local.yml：

services:
  webserver:
    image: linguacafe-webserver:local
    build:
      context: .
      dockerfile: docker/PhpDockerfile

然后执行：

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build

导入科研 PDF、Markdown 或 HTML

在浏览器中：

1. 打开“书库”。
2. 选择“导入内容”。
3. 选择“PDF / Markdown / HTML”。
4. 选择文件、书籍位置和章节拆分参数。
5. 完成导入，随后在书库中观察后台整理进度和预计时间。

正常文本 PDF 会自动处理；扫描型 PDF 请先在外部完成 OCR，再上传生成的 PDF、Markdown、HTML 或纯文本。

数据、端口和安全

• storage/ 保存上传文件、封面、模型和应用数据。
• database/ 是 MySQL 数据目录。
• cache/ 是 Redis 持久目录。
• 停止服务不要使用会删除 volume 或这些目录的命令。
• Web 默认使用 9191，WebSocket 默认使用 6001。
• MySQL、Redis 和 Python tokenizer 不应向 LAN 或公网开放。

上游基础 docker-compose.yml 可能包含 Redis 的主机端口映射。用于局域网或公网部署前，应通过 Compose override 删除该映射，或至少限制到 127.0.0.1。不要公开 3306 或 6379。

当前上游仍以单用户/单服务器使用为主要支持场景。开始正式学习前应先验证备份和恢复流程。

资源占用

内存占用取决于启用的语言模型和词典；启用全部语言时，上游说明可能超过 2 GB。文档整理期间还会使用 PHP worker、Python tokenizer、MySQL 和 Redis。建议在书库的“后台整理性能”中先选择自动模式；若系统还有其他任务或数据库出现锁竞争，选择稳定模式。

测试和验证

PHP 单元测试：

php artisan test

中文界面和资源校验：

npm run test:i18n
python3 scripts/validate-manual-translations.py

文档转换和自适应处理还提供 scripts/ 下的定向测试与冒烟脚本。运行会写入数据库的 E2E 脚本前，请先阅读脚本并使用专用测试账号。

更新和备份

• 更新前备份 MySQL、storage/ 和部署配置。
• 使用 git fetch --all --tags 查看新的稳定 tag，不要默认切换到 beta。
• 比较迁移、Dockerfile、Compose 和依赖变化后，再 rebase 或 cherry-pick 本地修改。
• 不要直接用上游文件覆盖当前 main，否则中文化、文档导入和性能控制修改可能丢失。

完整安装、更新和使用说明也可在应用内中文手册查看。

上游、署名和许可

• 上游项目：simjanos-dev/LinguaCafe
• 上游主页与功能概览：LinguaCafeHome
• 上游 Wiki：LinguaCafe Wiki
• 第三方词典、分词器和字体的完整署名与许可证保留在 README_EN.md 及应用内 Attributions 页面。
• 本项目依据 GNU General Public License v3 发布。