Jenkins插件国际化[编辑 | 编辑源代码]

介绍[编辑 | 编辑源代码]

Jenkins插件国际化（Internationalization，简称i18n）是指通过资源文件与代码解耦的方式，使插件能够支持多语言显示的技术。Jenkins使用Java标准的ResourceBundle机制实现国际化，开发者通过提供不同语言的属性文件（.properties），让界面元素根据用户的语言设置动态切换。

国际化与本地化（Localization，L10n）的区别：

i18n：技术实现（如抽取文本到资源文件）
L10n：针对特定语言的适配（如翻译文本）

核心机制[编辑 | 编辑源代码]

Jenkins国际化系统依赖以下组件：

文件结构[编辑 | 编辑源代码]

标准Maven项目的资源文件路径： ``` src/main/resources/

   ├── index.jelly
   ├── Messages.properties        # 默认语言（英语）
   ├── Messages_zh_CN.properties  # 简体中文
   └── Messages_fr.properties     # 法语

```

实现步骤[编辑 | 编辑源代码]

1. 创建资源文件[编辑 | 编辑源代码]

基础文件示例（Messages.properties）：

greeting=Hello
button.submit=Submit
error.invalid=Invalid input: {0}

中文翻译文件（Messages_zh_CN.properties）：

greeting=你好
button.submit=提交
error.invalid=无效输入: {0}

2. Jelly文件中使用[编辑 | 编辑源代码]

在Jenkins插件的Jelly视图文件中引用：

<l:main-panel>
    <h1>${%greeting}</h1>
    <input type="submit" value="${%button.submit}" />
    <div class="error">${%error.invalid('ABC123')}</div>
</l:main-panel>

3. Java代码中使用[编辑 | 编辑源代码]

通过Messages工具类：

import hudson.plugins.Messages;

public class Example {
    public String getGreeting() {
        return Messages.greeting();  // 自动匹配语言
    }
    
    public String getError(String input) {
        return Messages.error_invalid(input);  // 带参数的示例
    }
}

高级特性[编辑 | 编辑源代码]

动态参数[编辑 | 编辑源代码]

使用 ${0}, {1}$ 等占位符：

build.status=Build {0} is {1}

调用方式：

Messages.build_status("job-123", "FAILED");

复数处理[编辑 | 编辑源代码]

通过条件判断实现：

file.count.0=No files
file.count.1=One file
file.count.2=Two files
file.count.other={0} files

实际案例[编辑 | 编辑源代码]

场景：为Git插件添加法语支持

1. 创建Messages_fr.properties：

git.branch=Branch
git.commit=Commit
git.error=Erreur Git: {0}

2. 验证效果：

最佳实践[编辑 | 编辑源代码]

始终保留默认的Messages.properties（英语）
参数占位符使用{0}格式而非字符串拼接
语言文件编码必须为ISO-8859-1，非ASCII字符需使用Unicode转义（如\u4F60\u597D表示"你好"）
使用工具转换特殊字符：

native2ascii -encoding UTF-8 input.properties output.properties

测试验证[编辑 | 编辑源代码]

通过Jenkins的Locale参数测试不同语言：

mvn hpi:run -Duser.language=zh -Duser.country=CN

常见问题[编辑 | 编辑源代码]

问题	解决方案
文本未翻译	检查文件命名是否规范（如`Messages_zh_CN.properties`）
乱码显示	确保文件编码和Unicode转义正确
参数不生效	检查占位符编号是否从0开始

延伸阅读[编辑 | 编辑源代码]

Java ResourceBundle 官方文档
Jenkins官方国际化指南
Unicode字符转换工具使用说明