Paperless-ngx 多语言支持：本地化配置与翻译贡献指南

Paperless-ngx 作为一款开源文档管理系统（Document Management System, DMS），支持全球多语言界面与文档处理能力。本文将详细介绍如何配置系统语言环境、自定义本地化内容，以及参与翻译贡献的完整流程，帮助用户与开发者构建更友好的多语言文档管理体验。

多语言架构概览

Paperless-ngx 的本地化（Localization, L10n）系统采用前后端分离架构，分别处理后端逻辑与前端界面的语言资源：

• 后端本地化：基于 Django 框架的国际化（Internationalization, i18n）系统，使用 Gettext 格式的 .po 文件存储翻译文本，路径为 src/locale/。
• 前端本地化：采用 Angular 的国际化方案，通过 XLIFF 格式的 .xlf 文件管理界面翻译，路径为 src-ui/src/locale/。

系统默认支持英语（en_US），并通过社区贡献扩展至 40+ 种语言，包括中文（zh_CN）、日语（ja_JP）、德语（de_DE）等。完整语言列表可在 src/paperless/settings.py 的 LANGUAGES 配置中查看。

语言文件结构

paperless-ngx/
├── src/
│   └── locale/                # 后端翻译文件
│       ├── en_US/             # 英语源文件
│       ├── zh_CN/             # 中文翻译
│       └── ...
└── src-ui/
    └── src/locale/            # 前端翻译文件
        ├── messages.xlf       # 源语言模板
        ├── messages.zh_CN.xlf # 中文翻译
        └── ...

本地化配置指南

1. 系统语言设置

Docker 部署

通过环境变量 PAPERLESS_LANGUAGE 指定界面语言，例如设置为中文：

# docker-compose.env
PAPERLESS_LANGUAGE=zh_CN

裸金属部署

修改配置文件 paperless.conf：

# paperless.conf
PAPERLESS_LANGUAGE=zh_CN

动态切换语言

管理员可在 Web 界面 设置 > 应用配置 中实时切换系统语言，支持为不同用户保存独立语言偏好。

2. OCR 语言配置

Paperless-ngx 使用 Tesseract OCR 引擎识别多语言文档，需通过环境变量指定支持的语言包：

# docker-compose.env
PAPERLESS_OCR_LANGUAGES=chi_sim eng  # 中文简体 + 英语

支持的语言代码可参考 Tesseract 语言列表。安装额外语言包后，需重启服务使配置生效。

3. 日期与时间格式

通过 PAPERLESS_TIME_ZONE 调整时区，影响文档创建时间、邮件处理等时间显示：

# 中国时区
PAPERLESS_TIME_ZONE=Asia/Shanghai

翻译贡献流程

1. 贡献指南

Paperless-ngx 使用 Crowdin 协作翻译平台，贡献步骤如下：

1. 注册账号：访问 Crowdin 项目页面并登录。
2. 选择语言：在项目主页选择目标语言（如“Chinese Simplified”）。
3. 翻译内容：通过 Web 界面翻译缺失文本，或下载文件离线翻译。
4. 提交审核：翻译完成后提交审核，由语言管理员验证质量。

2. 本地化文件格式

后端 .po 文件示例

# src/locale/zh_CN/LC_MESSAGES/django.po
msgid "Document"
msgstr "文档"

msgid "Correspondent"
msgstr "联系人"

前端 .xlf 文件示例

<!-- src-ui/src/locale/messages.zh_CN.xlf -->
<trans-unit id="dashboard.title">
  <source>Dashboard</source>
  <target>仪表盘</target>
</trans-unit>

3. 手动翻译流程

提取源文本

后端：

cd src/
python manage.py makemessages -l en_US  # 更新英语源文件

前端：

cd src-ui/
ng extract-i18n  # 生成 messages.xlf

编译翻译

后端：

python manage.py compilemessages  # 生成 .mo 二进制文件

前端：

ng build --configuration production  # 编译时嵌入翻译

高级自定义

1. 自定义翻译覆盖

如需修改现有翻译，可直接编辑对应语言文件，例如调整中文“文档类型”的译法：

# src/locale/zh_CN/LC_MESSAGES/django.po
msgid "Document Type"
msgstr "文件类型"  # 自定义翻译

2. 多语言测试

开发环境中可通过以下命令验证翻译完整性：

# 检查未翻译的字符串
python manage.py makemessages -l zh_CN --no-wrap --check

3. 社区翻译进度

通过 Crowdin 统计页面 查看各语言翻译完成度，重点关注：

• 已翻译：已完成翻译的字符串比例
• 已审核：通过质量审核的翻译比例
• 待翻译：新增未翻译的字符串数量

常见问题

Q1: 界面部分文本未翻译？

A1: 可能是翻译未同步至最新版本。可通过以下步骤解决：

1. 确认使用最新版 Paperless-ngx
2. 在 Crowdin 检查对应语言翻译状态
3. 手动更新翻译文件并重启服务

Q2: OCR 无法识别中文文档？

A2: 需确保：

1. 已安装 tesseract-ocr-chi_sim 语言包
2. PAPERLESS_OCR_LANGUAGES 包含 chi_sim
3. 文档清晰度足够（建议分辨率 ≥ 300 DPI）

Q3: 如何贡献新语言？

A3: 联系项目维护者在 Crowdin 平台添加语言，或提交 PR 修改以下文件：

• src/paperless/settings.py 添加语言选项
• src-ui/src/app/services/settings.service.ts 添加前端语言支持

总结

Paperless-ngx 的多语言支持覆盖从界面显示到文档处理的全流程，通过灵活的配置与活跃的社区翻译，满足全球用户的本地化需求。无论是用户配置多语言环境，还是开发者参与翻译贡献，本文档均提供了清晰的操作指南。

如需进一步支持，可参考：

• 官方文档：Localization
• 社区论坛：Paperless-ngx Discussions
• 翻译平台：Crowdin Project

通过共同维护多语言生态，Paperless-ngx 将持续提升全球用户的文档管理体验。

提示：定期同步上游翻译可获取最新语言更新，Docker 用户可通过 docker compose pull 更新镜像。