Paperless-ngx 多语言部署：5 个变量搞定中英日文档识别

Paperless-ngx 多语言部署：5 个变量搞定中英日文档识别

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

中英混排的发票 OCR 出来一长串方块、"2024年3月15日"死活识别不成日期——先别怀疑文档，先查配置，Paperless-ngx 多语言部署说白了就是几个环境变量的事。这套社区维护的开源文档管理系统能把扫描件扫描、索引、归档一条龙做完，下面这五个变量接对之后，界面、OCR、日期解析全都会说中文。

5 分钟先跑起来

已经会用docker compose的话，这一节五分钟内就能见效。在服务的environment:里补上下面几行，重启容器，然后打开页面把右上角界面语言从 English 切成"中文(简体)"：

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

容器启动时，初始化脚本会比对清单里哪些语言包缺失，用apt-get install把对应的tesseract-ocr-*包装上。日志里出现 "Installed package tesseract-ocr-chi_sim" 就说明中文 OCR 到位了。下面逐个变量拆因果。

中文界面仪表盘：切完语言后，按钮、菜单和日期展示全部本地化。

逐个变量拆因果：改了它，到底影响哪一步

界面语言怎么切：Paperless-ngx 中文界面不在环境变量里

界面语言是这套"配置"里唯一没有服务端变量的。后端自带 50 多种语言包（src/locale/下从zh_CN到ja_JP都有django.po），前端语言选择器把选择写进 cookie，后端按 cookie 翻译。所以同一个实例，北京的同事看到中文，东京的同事看到日文，互不干扰。

⚠️ 坑在：别去服务端找一个PAPERLESS_LANGUAGE之类的变量，当前版本不读它，界面语言完全由浏览器决定。

PAPERLESS_OCR_LANGUAGE：Tesseract 默认拿什么语言读文档

Tesseract——Google 开源的 OCR 引擎，负责把图片里的文字变成可检索文本——识别文档时默认用这个变量写的语言，是三位字母代码，默认eng。文档以中文为主就写chi_sim；中英混排发票就写chi_sim+eng，Tesseract 会对不同区域分别挑匹配的语言识别。系统推断日期解析语言、全文索引语言时，也以它为源头。

⚠️ 坑在：代码里没有连字符。Debian 包名叫chi-sim，变量里必须写chi_sim，否则 OCR 直接报找不到语言。

Paperless-ngx 中文 OCR 语言包安装：PAPERLESS_OCR_LANGUAGES 干什么

镜像默认只带英语、德语、意大利语、西班牙语、法语五种语言包。这个变量是空格分隔的列表，容器启动时的初始化脚本会逐个比对已装包，缺什么补什么。比如PAPERLESS_OCR_LANGUAGES=chi_sim装简体中文，PAPERLESS_OCR_LANGUAGES=chi_sim jpn一次装两个。

⚠️ 坑在：分隔符是空格不是加号；而且 rootless 容器没有 apt 权限，这个变量只在普通容器里生效。

日期解析语言配了 zh 还是 zh+en

文档的日期字段靠 dateparser 库（自然语言日期解析工具）提取，语言由PAPERLESS_DATE_PARSER_LANGUAGES指定，格式是 "zh" 或 "zh+en"——注意是加号，和 OCR 的空格分隔正好相反。文档里"2024年3月15日"和 "March 15, 2024" 并存的话，zh+en就对了。留空时系统会尝试从PAPERLESS_OCR_LANGUAGE推断。

⚠️ 坑在：推断失败会退回多语言模式，日期识别率明显下降。以中文文档为主就写明白，别偷懒。

PAPERLESS_TIME_ZONE：时间戳落在哪个时区

这个变量喂给 Django 的时区系统，默认 UTC。团队坐班在北京就配Asia/Shanghai，界面上所有"创建时间""最后修改"都按本地时间展示，凌晨三点不会对着发票上的时间戳发懵。

⚠️ 坑在：它只改展示不改存储。跨时区协作就统一一个值，中途别改。

一封多语言邮件的全流程：跟外企财务专员走一遍

跟着小李走一遍。上午 9:15（Asia/Shanghai），小李的邮箱收到日本合作方发来的邮件，附件是中英文混排的发票 PDF。邮件规则提前配好了：这个发件人的附件自动送入消费目录，小李什么都不用做，后面全由系统接管。

邮件规则配置：指定发件人的附件自动入库，多语言内容也走同一条链路。

消费者接单后，PAPERLESS_OCR_LANGUAGE=chi_sim+eng开始工作：发票上的中文按中文识别，英文条目按英文识别，不会整页糊成一锅粥。"发票日期：2024年3月15日"那一行，靠zh+en被 dateparser 解析进 created 字段。小李还可以给这类文档加一个"发票号"自定义字段，把这类元数据沉淀下来。

自定义字段：给文档补语言之外的元数据维度，方便批量整理和筛选中英混排文件。

小李打开页面时界面语言是"中文(简体)"，搜索框里直接输入"发票"。后端全文索引已经把 OCR 结果里的中文 token 建好索引，这条文档当场命中，卡片上的时间显示"2024年3月15日"，落在北京时区。

搜索结果：中文关键词"发票"命中 OCR 识别出的文档，时间按本地时区展示。

整条链路用到的是三组配置：OCR 语言决定认不认得出，日期语言决定日期字段填不填得上，时区加界面语言决定你打开页面看到什么。

内存只有 2G、4G、8G 时怎么配

• 2G：单语言，PAPERLESS_OCR_LANGUAGE只写chi_sim，别加 eng，日期解析也只留 zh。
• 4G：一主一辅，chi_sim+eng是甜点位，日期解析配zh+en。
• 8G：真有多语归档需求就加上 jpn，但控制并发任务数，别一次灌大批量。

Paperless-ngx 多语言 OCR 故障速查

症状：OCR 出来全是方块或乱码。最可能原因是chi_sim语言包没装上，或者变量写成了chi-sim。进容器执行一条命令验证：

docker compose exec paperless tesseract --list-langs

输出里没有chi_sim就回头检查PAPERLESS_OCR_LANGUAGES是不是空格分隔、容器是不是 rootless。

症状：中文文档日期字段为空或年份不对。最可能原因是 dateparser 不认识中文日期。把PAPERLESS_DATE_PARSER_LANGUAGES显式设为zh+en，重新消费几份文档看 created 字段是否落值。

症状：界面部分文本没翻译。最可能原因是浏览器语言 cookie 还停在英语，或者页面缓存没刷。右上角切换语言后强制刷新；仍然缺词，再去 src/locale/zh_CN/LC_MESSAGES/django.po 里查对应词条是否本来就缺。

配置对了之后你能拿到什么

一套中文文档搜得到、中文日期自动提取、北京和东京同事各看各语言界面的系统。变量细节查 docs/configuration.md，容器部署流程看 docs/setup.md。

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