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长得很像,干的却不是同一件事。变量管什么中文场景怎么填格式PAPERLESS_OCR_LANGUAGEOCR 引擎(Tesseract,一个开源识别引擎,负责把图片里的文字读出来)实际用哪些语言识别chi_simeng3 字母 ISO 代码,多语言用连PAPERLESS_OCR_LANGUAGES容器启动时额外安装哪些语言包chi_sim eng空格分隔Tesseract 默认只装了eng,中文包不在里面。Docker 部署时,OCR 语言包初始化脚本 会在容器启动时检查PAPERLESS_OCR_LANGUAGES,缺哪个就apt-get装哪个(包名是tesseract-ocr-lang),装过的会跳过,不会重复下载。 这段 compose 配置做三件事:声明识别语言、声明要装的语言包、指定时区:environment: - PAPERLESS_OCR_LANGUAGEchi_simeng - PAPERLESS_OCR_LANGUAGESchi_sim eng - PAPERLESS_DATE_PARSER_LANGUAGESzhen - PAPERLESS_TIME_ZONEAsia/Shanghai改完重启容器,上传一份中文 PDF,看两样东西:正文是否可读、文档日期字段是否自动填上。时区那个变量默认是UTC,不填的话所有时间戳都会按 UTC 算,凌晨的归档行为看起来会很怪。日期字段是空的?dateparser 和 Tesseract 用的是两套语言码为什么识别对了,日期却是空的?因为日期解析走的是另一条链路:dateparser(一个靠自然语言猜日期的库)不认chi_sim这种 Tesseract 代码,它认zh这种短码。两套代码对照着记:Tesseract 写法dateparser 写法对应语言chi_simzh简体中文engen英语jpnja日语好消息是:不填PAPERLESS_DATE_PARSER_LANGUAGES时,Paperless-ngx 会从 OCR 语言自动推导出 dateparser 语言(源码里ocr_to_dateparser_languages干的就是这件事)。推导失败时日志会提醒你手动指定,看到那句 warning 再填也不迟。推导结果和你预期不符(比如文档里写的是英文日期),就显式写上PAPERLESS_DATE_PARSER_LANGUAGESzhen。想改专业术语的翻译?别动仓库里的文件——把 src/locale/zh_CN/LC_MESSAGES/django.po 导出到本地,改好再挂载进容器覆盖,仓库本身不用碰。中英混排文档:识别和搜索一起配chi_simeng这个组合是中英混排的主力。Tesseract 会同时用两种语言包跑一遍,中英文混在一页里也能读出来。读出来之后还有搜索这一环。全文索引的语言也会跟随PAPERLESS_OCR_LANGUAGE自动推断,影响分词和关键词匹配;有特殊需要才去显式覆盖搜索语言(参考 docs/configuration.md 里的PAPERLESS_SEARCH_LANGUAGE)。几个实操建议:别贪多。语言包每加一种,识别耗时和内存都会涨,先只加你文档里真实出现的语言。扫描质量比语言包更影响准确率。300 DPI 以下的扫描件,换什么包都救不回来,先提升扫描质量。混排文档的关键词检索,优先搜正文里的固有名词(编号、名称),少搜长句,命中率更高。上量之前:多语言包对资源的真实开销先想清楚你真正需要几种语言,再谈性能。大致账目如下:语言数量额外磁盘(约)识别耗时适合谁1 种~10 MB基线纯中文或纯英文环境2~3 种~30 MB明显可感中英混排的主流选择5 种以上~100 MB明显变慢多语种归档中心,先压测再上怎么控制总耗时?关键是别让它并行炸开。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_LANGUAGESzhen加上重启,看文档日期是否自动填入。 最后给个动作:今天就上传一份你手头最典型的中文扫描件,按上面的配置跑一遍。正文、日期、搜索三个字段都对上了,你的多语言环境才算真正可用——对不上,再回来对着第六节逐条查。【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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长得很像,干的却不是同一件事。变量管什么中文场景怎么填格式PAPERLESS_OCR_LANGUAGEOCR 引擎(Tesseract,一个开源识别引擎,负责把图片里的文字读出来)实际用哪些语言识别chi_simeng3 字母 ISO 代码,多语言用连PAPERLESS_OCR_LANGUAGES容器启动时额外安装哪些语言包chi_sim eng空格分隔Tesseract 默认只装了eng,中文包不在里面。Docker 部署时,OCR 语言包初始化脚本 会在容器启动时检查PAPERLESS_OCR_LANGUAGES,缺哪个就apt-get装哪个(包名是tesseract-ocr-lang),装过的会跳过,不会重复下载。 这段 compose 配置做三件事:声明识别语言、声明要装的语言包、指定时区:environment: - PAPERLESS_OCR_LANGUAGEchi_simeng - PAPERLESS_OCR_LANGUAGESchi_sim eng - PAPERLESS_DATE_PARSER_LANGUAGESzhen - PAPERLESS_TIME_ZONEAsia/Shanghai改完重启容器,上传一份中文 PDF,看两样东西:正文是否可读、文档日期字段是否自动填上。时区那个变量默认是UTC,不填的话所有时间戳都会按 UTC 算,凌晨的归档行为看起来会很怪。日期字段是空的?dateparser 和 Tesseract 用的是两套语言码为什么识别对了,日期却是空的?因为日期解析走的是另一条链路:dateparser(一个靠自然语言猜日期的库)不认chi_sim这种 Tesseract 代码,它认zh这种短码。两套代码对照着记:Tesseract 写法dateparser 写法对应语言chi_simzh简体中文engen英语jpnja日语好消息是:不填PAPERLESS_DATE_PARSER_LANGUAGES时,Paperless-ngx 会从 OCR 语言自动推导出 dateparser 语言(源码里ocr_to_dateparser_languages干的就是这件事)。推导失败时日志会提醒你手动指定,看到那句 warning 再填也不迟。推导结果和你预期不符(比如文档里写的是英文日期),就显式写上PAPERLESS_DATE_PARSER_LANGUAGESzhen。想改专业术语的翻译?别动仓库里的文件——把 src/locale/zh_CN/LC_MESSAGES/django.po 导出到本地,改好再挂载进容器覆盖,仓库本身不用碰。中英混排文档:识别和搜索一起配chi_simeng这个组合是中英混排的主力。Tesseract 会同时用两种语言包跑一遍,中英文混在一页里也能读出来。读出来之后还有搜索这一环。全文索引的语言也会跟随PAPERLESS_OCR_LANGUAGE自动推断,影响分词和关键词匹配;有特殊需要才去显式覆盖搜索语言(参考 docs/configuration.md 里的PAPERLESS_SEARCH_LANGUAGE)。几个实操建议:别贪多。语言包每加一种,识别耗时和内存都会涨,先只加你文档里真实出现的语言。扫描质量比语言包更影响准确率。300 DPI 以下的扫描件,换什么包都救不回来,先提升扫描质量。混排文档的关键词检索,优先搜正文里的固有名词(编号、名称),少搜长句,命中率更高。上量之前:多语言包对资源的真实开销先想清楚你真正需要几种语言,再谈性能。大致账目如下:语言数量额外磁盘(约)识别耗时适合谁1 种~10 MB基线纯中文或纯英文环境2~3 种~30 MB明显可感中英混排的主流选择5 种以上~100 MB明显变慢多语种归档中心,先压测再上怎么控制总耗时?关键是别让它并行炸开。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_LANGUAGESzhen加上重启,看文档日期是否自动填入。 最后给个动作:今天就上传一份你手头最典型的中文扫描件,按上面的配置跑一遍。正文、日期、搜索三个字段都对上了,你的多语言环境才算真正可用——对不上,再回来对着第六节逐条查。【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考