Keycloak自定义主题消息编码与俄语本地化问题解决方案咨询

一、解决俄语符号乱码问题 #

Keycloak默认以ISO-8859-1编码加载.properties消息文件，直接写入俄语UTF-8字符会导致乱码，可通过以下两种方式解决：

方法1：转义UTF-8字符 #

使用JDK自带的native2ascii工具，将UTF-8编码的俄语文本转义为ISO-8859-1兼容的转义序列：

native2ascii -encoding UTF-8 message_ru_utf8.properties message_ru.properties

将转义后的message_ru.properties用于后续配置即可。

方法2：配置Keycloak直接读取UTF-8编码文件 #

修改Keycloak服务器配置文件（standalone.xml或domain.xml），找到<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">块，添加消息Provider的编码配置：

<spi name="messages">
    <default-provider>property-file</default-provider>
    <provider name="property-file">
        <properties>
            <property name="encoding" value="UTF-8"/>
        </properties>
    </provider>
</spi>

配置完成后，直接保存UTF-8编码的message_ru.properties即可，无需转义。

二、配置自定义俄语消息 #

方式1：通过主题扩展实现 #

1. 复制Keycloak默认主题（如base或keycloak）到自定义主题目录，例如themes/custom-ru-theme
2. 在custom-ru-theme/messages目录下创建或修改message_ru.properties，添加或覆盖需要的俄语消息（编码需符合上述要求）
3. 登录Keycloak管理控制台，进入目标Realm的Realm设置 → 主题，将登录、账户等主题选项设置为custom-ru-theme
4. 重启Keycloak使配置生效

方式2：通过消息Provider Jar实现 #

1. 创建Maven项目，在src/main/resources/META-INF/services/org.keycloak.messages.MessageProviderFactory文件中写入自定义Provider的全类名：

com.example.RuMessageProviderFactory

2. 编写RuMessageProviderFactory类，继承PropertyFileMessageProviderFactory，指定消息文件路径和编码：

public class RuMessageProviderFactory extends PropertyFileMessageProviderFactory {
    @Override
    protected String getMessagesPrefix() {
        return "messages/message_ru";
    }

    @Override
    protected String getEncoding() {
        return "UTF-8";
    }

    @Override
    public String getId() {
        return "ru-custom-messages";
    }
}

3. 将message_ru.properties放入src/main/resources/messages目录，打包为Jar文件
4. 将Jar文件复制到Keycloak的providers目录，执行kc.sh build（Windows环境为kc.bat build）后重启Keycloak
5. 在管理控制台进入Realm设置 → 本地化，将消息Provider设置为ru-custom-messages

验证配置 #

切换Keycloak界面语言为俄语，检查页面消息是否正常显示且无乱码。

内容的提问来源于stack exchange，提问作者Adi Dasler