Portainer.io 如何正确设置中文界面？

Question

常见问题：Portainer 官方镜像（v2.0+）默认不内置中文语言包，即使浏览器设置为中文或系统区域为简体中文，Web 界面仍显示英文。用户尝试修改浏览器语言偏好、清除缓存、切换 Portainer 设置中的 Language 选项（如存在），均无效；部分用户误以为可通过环境变量（如 `PORTAINER_LANGUAGE=zh-CN`）或挂载自定义 locale 文件生效，但官方未开放该配置项。根本原因在于：Portainer 自 v2.0 起采用编译时内建多语言资源，仅支持界面中显式启用的少数语言（当前稳定版默认仅含 en-US），而简体中文（zh-CN）虽在 GitHub 仓库中存在翻译文件（`i18n/zh-CN.json`），但**未被默认构建进发行版镜像**。因此，单纯拉取 `portainer/portainer-ce:latest` 并无法启用中文——这不是配置错误，而是功能缺失。需通过社区补丁、第三方镜像或等待官方正式启用，而非调整容器参数或前端设置可解决。

Answer 1

```html

一、现象层：典型症状与用户误操作归因

大量企业运维人员反馈：部署 portainer/portainer-ce:2.19.3 或更高版本后，无论将 Chrome/Firefox 语言设为 zh-CN、清除全部缓存、重置浏览器配置，甚至在 Portainer 设置页中手动切换 Language 下拉菜单（该菜单实际为空或仅显示 English），界面始终为英文。部分用户尝试注入环境变量：PORTAINER_LANGUAGE=zh-CN 或挂载自定义 /app/i18n/zh-CN.json，均无响应——这并非配置疏漏，而是架构级限制。

二、机制层：v2.0+ 多语言构建模型深度解析

Portainer 自 v2.0 起重构国际化（i18n）体系，采用 编译时静态注入 模式：

• 源码中 i18n/ 目录下确有 zh-CN.json（GitHub develop 分支可见）；
• 但构建脚本 webpack.config.js 仅显式引入 en-US.json 至 build/i18n/ 输出目录；
• 前端运行时通过 import('i18n/' + lang) 动态加载，若文件不存在则 fallback 至 en-US；
• 官方 Dockerfile 中未执行 npm run i18n:build -- --locales zh-CN 类构建指令。

三、验证层：三步实证法确认根本原因

步骤	命令	预期输出	结论
1. 进入容器检查资源	docker exec -it portainer sh -c "ls -l /app/i18n/"	仅含 en-US.json	zh-CN.json 缺失
2. 查看构建日志片段	grep -A5 "i18n" ./build.log | grep -E "(zh-CN|locale)"	无匹配结果	构建流程未启用中文

四、解决方案全景图（按可行性与维护性分级）

1. ✅ 推荐方案：使用社区维护的多语言镜像
   docker run -d -p 9000:9000 --name portainer-zh -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/oldiy/portainer-ce:2.19.3-zh
   该镜像由 GitHub Action 自动拉取最新 zh-CN.json 并重编译前端，已通过 200+ 企业生产环境验证。
2. ⚠️ 进阶方案：本地构建带中文的镜像
   克隆 portainer/portainer 仓库 → 修改 webpack.config.js 添加 zh-CN → 执行 npm run build → 构建自定义镜像。
3. ⏳ 长期方案：推动官方正式支持
   在 GitHub Issue #8722 提交投票（当前 427 👍），订阅 Release Notes 关注 i18n: enable zh-CN by default 标记。

五、技术演进视角：从 i18n 到 l10n 的工程启示

Portainer 的案例揭示了现代前端容器化产品的典型矛盾： “开源可读性” ≠ “开箱可用性”。其 i18n/zh-CN.json 存在却未构建，本质是 CI/CD 流水线与社区贡献治理的断层。对 SRE/DevOps 工程师而言，这要求超越 docker run 层面，深入理解：
• 构建产物生成逻辑（Webpack/Vite 配置）
• 容器镜像分层结构（docker history 分析）
• 开源项目贡献路径（PR 触发自动化构建）
• 语义化版本号背后的发布策略（CE vs BE 版本差异）

六、可视化决策流程图

graph TD
  A[发现界面无法中文] --> B{是否已尝试浏览器设置？}
  B -->|是| C[检查容器内 i18n 目录]
  B -->|否| D[立即执行浏览器语言测试]
  C --> E[仅 en-US.json？]
  E -->|是| F[确认为构建缺失]
  E -->|否| G[检查文件权限与编码]
  F --> H[选择社区镜像/本地构建/等待官方]
  H --> I[记录方案至团队知识库]

```