如何在 Keycloak 登录页添加多语言切换按钮

Keycloak 19+ 版本中，登录页语言切换功能需通过「Localization」（本地化）选项卡启用，而非旧版的 Theme 设置页面；正确配置后可自动显示语言选择器，支持用户手动切换界面语言。

Keycloak 19+ 版本中，登录页语言切换功能需通过「Localization」（本地化）选项卡启用，而非旧版的 Theme 设置页面；正确配置后可自动显示语言选择器，支持用户手动切换界面语言。

在 Keycloak 管理控制台中，登录页的语言切换按钮（Language Selector）默认不显示，需主动启用并配置支持的语言列表。关键在于：该功能已从旧版的 Realm Settings → Themes 页面迁移至独立的 Localization 选项卡（自 Keycloak 19 起成为标准路径）。

正确操作步骤如下：

1. 登录 Keycloak 管理控制台，进入目标 Realm（如 my-realm）；
2. 左侧菜单选择 Realm Settings → 切换至 Localization 标签页；
3. 开启 Enabled 开关（启用本地化支持）；
4. 在 Supported Locales 区域，点击 + Add locale，添加所需语言（例如：en, zh-CN, fr, de, ja）；
5. （可选）勾选 Display name in its own language 以优化语言名称显示效果；
6. 保存设置。

✅ 启用后，Keycloak 将自动在登录页（/realms/{realm}/login）、注册页、错误页等所有认证流程页面右上角渲染语言切换下拉菜单（无需修改 FreeMarker 模板或主题文件）。

注意事项：

1. 若未看到 Localization 选项卡，请确认 Keycloak 版本 ≥ 19.0（推荐使用 21.x 或更高稳定版）；旧版本（如 17.x）需通过 theme.properties 启用 locale.login 并自定义 login.ftl；
2. 支持的语言代码必须符合 ISO 639-1 标准（如 zh 或 zh-CN），且对应语言包需已内置（Keycloak 默认包含主流语言资源）；
3. 浏览器语言自动匹配逻辑仍有效：若用户浏览器语言在支持列表中，将默认加载对应语言；否则回退至 realm 默认语言（可在 Realm Settings → General → Default Locale 中设置）。

? 小技巧：可通过 URL 参数强制指定语言，便于测试，例如：

https://keycloak.example.com/realms/my-realm/login?lang=zh-CN

该参数会覆盖浏览器语言检测，即时切换界面语言（前提是 zh-CN 已在 Supported Locales 中启用）。

完成上述配置后，刷新登录页即可看到右上角的语言切换控件——简洁、开箱即用、完全由 Keycloak 内置机制驱动，无需侵入式主题开发。