Paperless-ngx 多语言配置:中文 OCR、日期解析与本地化界面的 4 步落地法

Paperless-ngx 多语言配置:中文 OCR、日期解析与本地化界面的 4 步落地法

【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx

如果你用 Paperless-ngx(一个社区维护的开源文档管理系统)归档中文或中英混排的合同、发票,大概率会撞上三个怪现象:扫描件里的中文识别成乱码、文档日期字段是空的、整个界面还停在英文。这篇文章按"症状 → 原因 → 配置"的顺序把这四步讲清楚,照着做完,中文文档就能被读出来、搜得到、日期也能自动填上。

界面还是英文?界面语言是每个用户自己选的

先说结论:界面语言不是用环境变量全局锁死的,而是每个用户各自选。你在 Web 端的个人设置里切语言,后端用 Django 的 i18n(一套界面翻译机制)按用户返回对应文本。

为什么这么设计?因为团队里有人用中文、有人用英文,全局一个LANGUAGE变量满足不了所有人。仓库里 src/locale/ 目录放着 50 多个语言的翻译包,zh_CN就是简体中文。

• 切换路径:右上角头像 → 设置 → 语言,刷新即生效。
• 有人反映切换后还是英文?九成是浏览器缓存,强刷一次再看。
• 个别词条没翻译?去 Crowdin 对应翻译平台看进度,社区在持续补,不需要自己硬改。

中文识别成乱码?先把两个语言变量分清

这里有个容易忽略的坑:PAPERLESS_OCR_LANGUAGE和PAPERLESS_OCR_LANGUAGES长得很像,干的却不是同一件事。

Tesseract 默认只装了eng,中文包不在里面。Docker 部署时,OCR 语言包初始化脚本 会在容器启动时检查PAPERLESS_OCR_LANGUAGES,缺哪个就apt-get装哪个(包名是tesseract-ocr-<lang>),装过的会跳过,不会重复下载。

🔧 这段 compose 配置做三件事:声明识别语言、声明要装的语言包、指定时区:

environment: - PAPERLESS_OCR_LANGUAGE=chi_sim+eng - PAPERLESS_OCR_LANGUAGES=chi_sim eng - PAPERLESS_DATE_PARSER_LANGUAGES=zh+en - PAPERLESS_TIME_ZONE=Asia/Shanghai

改完重启容器,上传一份中文 PDF,看两样东西:正文是否可读、文档"日期"字段是否自动填上。时区那个变量默认是UTC,不填的话所有时间戳都会按 UTC 算,凌晨的归档行为看起来会很怪。

日期字段是空的?dateparser 和 Tesseract 用的是两套语言码

为什么识别对了,日期却是空的?因为日期解析走的是另一条链路:dateparser(一个靠自然语言猜日期的库)不认chi_sim这种 Tesseract 代码,它认zh这种短码。

两套代码对照着记:

好消息是:不填PAPERLESS_DATE_PARSER_LANGUAGES时,Paperless-ngx 会从 OCR 语言自动推导出 dateparser 语言(源码里ocr_to_dateparser_languages干的就是这件事)。推导失败时日志会提醒你手动指定,看到那句 warning 再填也不迟。

• 推导结果和你预期不符(比如文档里写的是英文日期),就显式写上PAPERLESS_DATE_PARSER_LANGUAGES=zh+en。
• 想改专业术语的翻译?别动仓库里的文件——把 src/locale/zh_CN/LC_MESSAGES/django.po 导出到本地,改好再挂载进容器覆盖,仓库本身不用碰。

中英混排文档:识别和搜索一起配

chi_sim+eng这个组合是中英混排的主力。Tesseract 会同时用两种语言包跑一遍,中英文混在一页里也能读出来。

读出来之后还有搜索这一环。全文索引的语言也会跟随PAPERLESS_OCR_LANGUAGE自动推断,影响分词和关键词匹配;有特殊需要才去显式覆盖搜索语言(参考 docs/configuration.md 里的PAPERLESS_SEARCH_LANGUAGE)。

几个实操建议:

1. 别贪多。语言包每加一种,识别耗时和内存都会涨,先只加你文档里真实出现的语言。
2. 扫描质量比语言包更影响准确率。300 DPI 以下的扫描件,换什么包都救不回来,先提升扫描质量。
3. 混排文档的关键词检索,优先搜正文里的固有名词(编号、名称),少搜长句,命中率更高。

上量之前:多语言包对资源的真实开销

先想清楚你真正需要几种语言,再谈性能。大致账目如下:

怎么控制总耗时?关键是别让它并行炸开。OCR 任务在后台任务队列里跑,并发数越大,同一时刻加载的语言包越多,内存峰值越高。文档量大就压低任务并发、把超时放宽,宁可慢一点也别 OOM(内存溢出把容器打挂)。

• 观察手段:看容器内存曲线,每加一种语言大约多吃 100~200 MB,按这个估余量。
• 验证手段:拿一份最复杂的混排文档做基准,记下处理时长,之后每次改配置都比着它测。

三个高频症状,一条命令定位

症状一:日志报语言包缺失。大概率是PAPERLESS_OCR_LANGUAGES没写或写错拼写,启动时没装上。 验证:docker compose exec webserver tesseract --list-langs(服务名按你的 compose 改),列表里没有chi_sim就是没装上。

症状二:界面个别词条还是英文。大概率是翻译包未更新或浏览器缓存。 验证:确认src/locale/zh_CN/LC_MESSAGES/下有编译后的.mo文件,然后强刷浏览器。

症状三:中文日期识别不到,日志有 dateparser warning。大概率是自动推导没覆盖到,需要显式指定。 验证:把PAPERLESS_DATE_PARSER_LANGUAGES=zh+en加上重启,看文档日期是否自动填入。

💡 最后给个动作:今天就上传一份你手头最典型的中文扫描件,按上面的配置跑一遍。正文、日期、搜索三个字段都对上了,你的多语言环境才算真正可用——对不上,再回来对着第六节逐条查。

【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx