GitLab 17 如何修改界面显示语言？

Question

在使用 GitLab 17 时，部分用户发现界面语言未随浏览器设置自动切换，仍显示为英文。尽管 GitLab 支持多语言界面（包括简体中文），但默认情况下可能未启用本地化选项。常见问题为：如何手动将 GitLab 17 的 Web 界面语言修改为中文？用户在个人设置中找不到语言选项，或更改后页面语言未生效。该问题通常涉及用户偏好设置路径不明确、系统级语言包缺失，或版本升级后翻译功能配置异常。需确认当前用户是否有权限修改语言设置，并检查 Rails I18n 配置是否正确加载中文语言包。

Answer 1

一、问题现象与初步排查

在使用 GitLab 17 的 Web 界面时，部分用户反馈即使浏览器语言设置为简体中文（zh-CN），GitLab 仍默认显示英文界面。更值得注意的是，部分用户在“用户设置”中无法找到语言切换选项，或即便更改后刷新页面语言仍未生效。

• 浏览器 Accept-Language 已设置为 zh-CN
• GitLab 用户偏好设置中缺少“语言”字段
• 管理员账户也无法在全局设置中看到多语言配置入口
• 页面源码中 lang 属性仍为 en-US

二、用户层级的语言设置路径（前端视角）

GitLab 自 13.0 版本起支持多语言切换，但该功能需满足两个前提：当前用户具有修改偏好权限，且系统已启用国际化（I18n）模块。对于普通用户，语言设置路径如下：

1. 登录 GitLab 账户
2. 点击右上角头像 → 进入 “Preferences”（偏好设置）
3. 查找 “Language” 下拉菜单（通常位于“General”标签页）
4. 选择 “简体中文 (Simplified Chinese)”
5. 点击 “Save Changes”

若上述步骤中未出现“Language”选项，可能原因包括：

可能原因	说明
用户角色权限不足	某些 LDAP/SSO 集成环境下，用户偏好被锁定
界面翻译包未加载	Rails 国际化资源缺失或未编译
功能标志（Feature Flag）关闭	locales 功能可能被禁用
缓存问题	浏览器或 Rails 缓存导致设置未更新

三、系统级配置检查（后端与部署视角）

当多个用户均无法切换语言时，应从系统层面排查。GitLab 使用 Ruby on Rails 的 I18n 框架实现多语言支持，其配置文件位于：

# GitLab 安装目录下的配置文件
/etc/gitlab/gitlab.rb

# 启用中文语言包的关键配置项
gitlab_rails['i18n_available_locales'] = ["en", "zh_CN"]
gitlab_rails['i18n_default_locale'] = "zh_CN"
    

修改后需执行重新配置命令：

sudo gitlab-ctl reconfigure

此操作将触发 Rails 国际化资源的重新加载，并确保 app/assets/javascripts/locale/zh.json 等语言包被正确注入资产管道。

四、深入分析：Rails I18n 加载机制与调试方法

GitLab 的语言切换依赖于 Rails 的 I18n API 和前端 JavaScript 的动态加载机制。可通过以下方式验证中文语言包是否注册：

# 进入 GitLab Rails 控制台
sudo gitlab-rails console

# 执行以下 Ruby 代码
I18n.available_locales
# 输出应包含 :zh_CN

I18n.t('common.save', locale: 'zh_CN')
# 应返回中文翻译如 "保存"
    

若返回英文或报错，则表明语言包未正确安装或 YAML 翻译文件缺失。常见路径为：

• /opt/gitlab/embedded/service/gitlab-rails/config/locales/zh.yml
• /opt/gitlab/embedded/service/gitlab-rails/app/assets/javascripts/locale/zh.json

五、版本升级与翻译功能异常的关联性分析

从 GitLab 16 升级至 17 后，部分实例出现语言包丢失问题，原因在于：

• 升级过程中未保留旧版语言包软链接
• 新的 webpack 构建流程未包含 zh-CN locale bundle
• feature_flags 中 experimental_i18n 被默认关闭

可通过以下命令检查当前启用的功能标志：

sudo gitlab-rake gitlab:features:list

六、Mermaid 流程图：语言设置故障排查路径

graph TD
    A[用户反馈界面为英文] --> B{个人设置是否有语言选项?}
    B -->|是| C[更改语言并保存]
    B -->|否| D[检查 gitlab.rb 中 i18n 配置]
    C --> E[刷新页面语言是否生效?]
    E -->|否| F[清除浏览器缓存 & Rails 缓存]
    D --> G[确认 zh_CN 在 available_locales 中]
    G --> H[执行 reconfigure]
    H --> I[重启 Puma 服务]
    I --> J[验证 I18n.available_locales]
    J --> K[检查前端 locale JS bundle 是否加载]
    K --> L[问题解决]

七、企业级部署中的特殊考量

在大规模企业环境中，语言设置常受以下因素影响：

• 通过 SAML/OAuth 登录的用户，其语言偏好可能由 IdP 强制设定
• 反向代理层（如 Nginx）可能剥离了 Accept-Language 请求头
• Kubernetes 部署中 ConfigMap 未同步最新 locale 配置
• CDN 缓存了英文版静态资源（JS/CSS）

建议在 ingress 层添加以下 header 透传规则：

# Nginx 示例
proxy_set_header Accept-Language $http_accept_language;