Jenkins汉化指南：三步解决中文显示不全问题

搞过一阵子Jenkins的人应该都遇到过这个场景打开系统管理一看菜单栏中文夹着英文有些按钮还拿拼音硬猜比如“New Job”翻译成“新建任务”是运气好翻译成“新工作”就觉得哪里不对。更别提读构建日志时标题是中文的内容却全是英文看着倒也不算累可一旦要给团队内部做培训或者帮非技术同事上手这种半吊子汉化就非常尴尬。这个问题的根源大多数情况不是插件没装而是装错了方向。很多人只装了Locale插件或者只装了汉化包结果一个管语言环境、一个管翻译文本两者各干各的缺一个都会导致“中文显示不全”。我见过团队里有人折腾了一下午在“系统管理→插件管理”里反复卸载安装页面还是中英混杂最后才发现是Locale插件配置里的语言参数写错了或者汉化包版本和Jenkins主版本不匹配。这篇内容我就把完整的解决方案讲清楚用三步走的方式解决Jenkins中文显示不全的问题。顺便会把离线安装、镜像站配置、版本兼容性这些实际工作中躲不掉的坑一并说透。不管是刚接触Jenkins运维的新手还是已经在公司搭过流水线的开发人员按这套姿势操作基本都能一次性解决问题。1. 先说清楚你遇到的“中文不全”到底是什么问题1.1 我见过的几种“半吊子中文”现场先把现象分个类因为很多人说的“中文不全”其实不是同一种情况。第一种是整体界面大部分是英文只有少量中文菜单项、按钮、设置项全是英文。这种通常是你什么都没装或者只装了汉化包但没装Locale插件导致语言包虽然存在但Jenkins不知道该按什么规则去加载它。第二种是界面大部分已经是中文了但某些二级页面、某些新安装的插件设置项还是英文。这个非常常见我也踩过。原因是Jenkins的汉化插件localization-zh-cn本质上是一个翻译资源文件的集合它负责把Jenkins核心和各插件的界面文字翻译成中文。但插件翻译的覆盖范围取决于翻译文件是否齐全加上很多第三方插件在发布时根本没有提供中文翻译那这部分内容就只好以英文显示了。再加上不同插件汉化的优先级不同页面上就会出现中英混合。第三种是整个界面看起来是中文的但系统消息、邮件通知、构建日志里的内容是英文。这其实是两码事界面语言和语言环境不完全是同一个概念。构建日志输出的语言往往取决于构建环境自身配置比如你用的Shell脚本、Gradle构建工具、Node.js等它们各自有自己的语言设置。而邮件通知模板里的英文内容是Jenkins默认模板自带的跟汉化包没有关系。第四种是安装完插件后重启Jenkins界面还是英文。这就不是插件的问题了多半是浏览器缓存、或者Jenkins启动时语言检测规则没生效也有可能是你配置了全局属性里的LANG变量覆盖了中文设置。先定位自己属于哪一种再动手解决问题能少走很多弯路。1.2 Locale插件和汉化包到底各管什么我遇到过不少朋友把这两个东西的概念搞混了。简单拆解一下。Locale插件插件全名是Locale Plugin在Jenkins里负责两件事一是强制指定整个Jenkins的界面语言二是让你能自定义日期时间格式、时区等本地化参数。它本身不提供中文翻译内容只提供一个“语言选择器”和环境变量控制能力。就像你给操作系统设置了中文区域但系统里得有中文字库和语言包才能真正显示中文否则就只能显示一堆方块或者乱码。而汉化包插件全名是Localization: Chinese (Simplified)插件ID是localization-zh-cn才是真正提供中文翻译资源的地方。插件会把Jenkins核心界面、系统管理菜单、任务操作按钮等位置的英文文本通过资源文件替换成中文。用一句话概括Locale插件决定“用哪种语言环境去跑”汉化包决定“有没有中文翻译文本可用”。两个配合起来Jenkins才能完整显示中文。这也解释了为什么只安装汉化包界面还是英文的情况时有发生——因为汉化包的加载有时候依赖于Locale插件设置的语言环境。如果Jenkins把默认语言判定成了英文汉化包里的中文资源就不会被优先使用。2. 准备工作安装插件前必须确认的三件事2.1 确认Jenkins版本与插件兼容性这步别偷懒。Jenkins的插件生态有一个特点插件版本和主版本之间存在兼容矩阵老版本Jenkins装新版本插件或者新版本Jenkins装老版本插件都有可能出问题。具体来说你可以在“系统管理→系统信息”里查看Jenkins版本号。如果是2.319版本之前的老版本Locale插件建议用最新发布版但要留意插件市场里是否标注了“Required Jenkins version”高于你当前的版本。汉化包也一样新版本Jenkins比如2.400之后对Localization插件的资源加载方式有过变化老版本汉化包容易出现翻译不生效的问题。我个人的检查习惯是先记下当前Jenkins主版本号打开插件管理页面找到Locale和Localization: Chinese (Simplified)两个插件查看插件详情页里标注的最低Jenkins版本要求如果当前版本低于要求先去“系统管理→工具”里升级Jenkins主版本再来装插件遵循这个顺序能省掉很多折腾的时间。2.2 网络与镜像源选择装插件最让人头疼的其实是下载速度。Jenkins默认的插件更新中心在国外国内网络环境下经常出现插件下载超时、安装失败、卡在“正在下载”界面一动不动的情况。一个稳妥的办法是先把插件更新中心换成国内镜像。目前国内用得比较多的镜像源有清华源、华为源等这些源会同步Jenkins官方插件仓库的内容。具体操作路径是这样的打开“系统管理→插件管理→高级”选项卡找到“升级站点”这一栏把默认的https://updates.jenkins.io/update-center.json替换成国内镜像地址点击“提交”之后再点击“立即获取最新的更新元数据”按钮等页面左下角提示获取成功再去“可选插件”里搜索插件这里要注意的是镜像源地址和Jenkins主版本需要匹配。不同版本的Jenkins对应的更新中心URL结构可能不同如果镜像配置后仍然获取不到插件列表建议在官方文档里查一下与你当前版本对应的镜像路径再拼接。2.3 备份与升级策略别笑着实见过有人装插件装挂了最后只能恢复快照。插件之间是有依赖关系的比如Locale插件会依赖某些基础库汉化包又会依赖Locale或者其他本地化相关组件这些依赖在安装时会自动下载但如果网络不好或者插件间版本不匹配就可能出现插件冲突轻则功能异常重则系统管理页面加载不出来。所以在动插件之前两个习惯必须养成在“系统管理→工具”里点击“备份”或通过插件市场安装ThinBackup插件做好Jenkins主目录的备份如果Jenkins是跑在Docker容器里的先执行docker commit备份当前容器镜像或者记录好当前docker run启动参数另一个做法是把Jenkins主目录下的plugins目录整体复制一份这样即使插件装坏了直接把旧目录覆盖回去就能还原到装插件之前的状态。这个操作对新手尤其友好不用记复杂的备份命令目录复制就行。3. 三步搞定Locale插件汉化包的正确姿势3.1 第一步安装Locale插件在线/离线两种方式在线安装部分在“系统管理→插件管理→可选插件”页面的搜索框里输入locale会看到名为“Locale”的插件勾选后直接点击“安装”。Jenkins会自动处理依赖并下载安装完成后在“已安装”标签页里能看到它。离线安装适用于完全不能联网的内网环境。思路是先在外网机器上把插件.hpi文件下载好再拷贝到内网服务器上执行安装。具体路径是“系统管理→插件管理→高级”在页面最下方找到“上传插件”区域选择.hpi文件后点击“上传”。上传完成后Jenkins会自动完成安装并提示需要重启。离线安装时有一个细节很多人不知道插件文件也可以手动放到JENKINS_HOME/plugins目录下然后重启Jenkins它会自动加载这些插件。这个方法比上传文件更可控尤其是多个插件需要批量安装的时候。把下载好的locale.hpi和它依赖的插件通常有structs、token-macro等全部放入目录一次性重启就全部生效。3.2 第二步配置Locale插件语言参数插件装好之后需要告诉Jenkins你要使用中文环境。这一步在“系统管理→Locale”里设置。有一个可能要提醒一下有的版本里这个入口是直接显示在“系统管理”下的“Locale”选项有的版本需要先配置全局属性才能看到。我建议两种方式都检查一下。进入Locale设置页面后你会看到两个关键项“Default Language”填入zh_CN“Ignore browser preference and force this language to all users”建议勾选填zh_CN的意思是告诉Jenkins强制使用简体中文而不是根据浏览器请求头自动判断。勾选第二项则是为了防止某些用户浏览器发送了英文的Accept-Language头结果把界面又带回了英文。这里有一个细节需要注意Locale插件设置的语言值不一定是zh_CN如果你想要繁体中文填zh_TW想要英文填en。这个值用的是Java的Locale命名规则下划线前面是语言代码后面是地区代码。填错了比如填成chinese或者cn插件不会报错但语言也不会生效因为Java虚拟机不认识这种写法。配置完成后页面会提示你重启Jenkins。这一步不能跳过Locale插件在启动阶段就会读取这个配置值并设置系统属性不重启的话配置不会生效。3.3 第三步安装并启用中文汉化包Locale插件配置好了只是把语言环境切到了中文接下来还需要安装汉化包才能真正提供中文翻译文本。在“系统管理→插件管理→可选插件”里搜索Localization你会看到两个和中文相关的插件“Localization: Chinese (Simplified)”这是简体中文包“Localization Support”这是国际化支持库你的关注重点应该是简体中文包。安装后汉化包会自动启用并且在重启Jenkins后生效。其中“Localization Support”这个插件也值得一提。它本身不直接提供中文而是提供了一套本地化翻译的基础机制能让第三方插件也通过资源文件来实现界面翻译。简单理解汉化包是“翻译内容”而Localization Support是“翻译框架”。有些老版本的汉化包会依赖它新版本的依赖关系已经弱了很多但为了保证完整汉化我建议一起装上。安装完成后回到“系统管理→Locale”页面确认语言设置仍然是zh_CN然后重启Jenkins。重启后再看首页正常情况下菜单、系统管理、任务列表这些核心界面都会是中文了。4. 实操过程记录从中文不全到完全汉化4.1 实际操作路线图我把自己在一台测试服务器上完整走通的过程记录下来给各位做个参照。那台服务器是Linux环境Jenkins版本是2.414.1以War包方式运行在Tomcat里没有Docker。操作步骤是这样的第一步先确认当前插件状态。在“系统管理→插件管理→已安装”里搜locale确认Locale插件是否已经安装。如果有看版本是否较新如果是一个很老的版本建议先升级。第二步配置国内镜像源。因为那台服务器在国内机房直接连官方更新中心非常不稳定我在“插件管理→高级→升级站点”里把更新中心换成了清华镜像。提交后点“立即获取”大概十几秒就完成了元数据更新。第三步安装Locale插件。在“可选插件”里搜locale找到“Locale”插件勾选后点安装。安装过程很快因为镜像源下载速度不错。第四步配置Locale。在“系统管理→Locale”里填上zh_CN勾选强制语言选项然后点击保存Jenkins提示说需要重启。我选择直接重启服务。第五步重启后安装汉化包。服务启动完成后重新登录在“可选插件”里搜Localization找到“Localization: Chinese (Simplified)”再顺便把“Localization Support”也勾上一起安装。第六步再次重启验证效果。整个过程大概花了15分钟其中大部分时间花在等待重启上。4.2 关键参数与配置说明这里针对刚才操作中几个比较容易出错的参数做一下解释。镜像站地址换完之后注意不是改完就能立即装插件。你需要先点“立即获取最新的更新元数据”让Jenkins从新地址拉取插件列表和版本信息。如果不做这一步系统里缓存还是旧数据搜索出来的插件列表可能没有或者版本信息是旧的。还有一点容易被忽略在“插件管理→高级”里不仅有升级站点设置还有一个“部署插件”区域。这个区域允许你上传.hpi文件但它是属于手动部署通道跟你通过“可选插件”界面安装走的不是同一套流程。手动部署后重启才能生效而且不会自动检查依赖。所以只要你网络没问题优先用在线安装方式依赖关系自动处理。Locale设置里的“Default Language”字段填zh_CN是最稳妥的。有的教程会建议填zh-CNJava的Locale解析器也支持这种带连字符的写法但我实测下来在部分旧版本上会出现不识别的情况。为了防止意外我默认推荐全部用下划线版本。4.3 重启与验证重启Jenkins的方式有很多种系统管理里没有一键重启按钮常见做法是如果你用systemctl管理执行sudo systemctl restart jenkins如果你用Docker执行docker restart 容器名如果你用Tomcat部署War包重启Tomcat即可也可以通过浏览器访问http://你的Jenkins地址/restart这个端点会弹出一个确认页面重启完成后重新登录时注意清除一下浏览器缓存或者按CtrlF5强制刷新。因为浏览器的静态资源缓存可能会让你以为设置没生效实际上页面早就换好了。验证时重点看这几个入口首页左侧菜单如“新建任务”“构建队列”“构建历史”“系统管理”下的各子项“插件管理”“全局工具配置”“凭据”等已有任务的详情页比如“配置”“工作区”“构建记录”这些标签“系统信息”页面是否正常显示如果这四处都已经是中文那核心汉化就是成功的。5. 常见问题与排查实录5.1 常见问题排查表这一节我整理了一张问题列表覆盖了我在处理Jenkins汉化问题时遇到的大多数情况。现象可能原因解决办法安装汉化包后仍然英文没装Locale插件或Locale语言参数未设置检查Locale状态填zh_CN并勾选强制语言某些页面中英文混杂第三方插件本身没有中文翻译资源接受现状或为插件单独寻找社区汉化包重启后又变回英文浏览器缓存强制刷新页面或换无痕窗口验证系统管理里没有Locale菜单Locale插件未安装或版本过老安装/升级Locale插件插件搜索不到汉化包更新站点镜像地址配置错误或缓存未刷新检查升级站点地址点击“立即获取”刷新元数据上传hpi安装失败缺少依赖插件或hpi文件损坏检查插件依赖手动将hpi放入plugins目录后重启中文显示为乱码方块服务器中文字体缺失在系统层安装中文字体如fonts-wqy-microhei里面重点说一下最后一种情况。Jenkins本身是Java应用界面渲染依赖系统字体库。如果你的Linux服务器是最小化安装可能根本没有安装任何中文字体那即使汉化包生效了中文也只会显示成一个个方块。这种问题不在Jenkins配置层面解决而是要给服务器安装字体。在Debian/Ubuntu环境下执行sudo apt install fonts-wqy-microheiCentOS/RHEL环境下用yum install wqy-microhei-fonts。装完后重启Jenkins一般就能正常显示了。5.2 隐藏坑点提醒除了上面表格里的典型问题我再补充几个比较隐蔽的坑。第一个坑是环境变量JAVA_TOOL_OPTIONS或JENKINS_JAVA_OPTIONS里显式设置了-Duser.languageen。如果你用了Tomcat或自定义启动脚本有时候这种全局JVM参数会强制覆盖Locale插件的设置。排查方法是打开“系统管理→系统信息”在系统属性列表里搜索user.language看当前值是不是en。如果是就需要在启动脚本里去掉这个参数或者改成zh_CN。第二个坑是反向代理或Nginx缓存了旧页面内容。如果你是通过Nginx把Jenkins反代到域名访问的清浏览器缓存没用还得清Nginx的proxy_cache。这种情况比较少见但排查起来特别费时间。我自己的做法是在Nginx配置文件里给Jenkins路径单独设置proxy_no_cache或者在调试期间临时加一个版本号参数访问比如/jenkins/?v123绕过缓存。第三个坑是汉化包安装顺序错了。有些人先装汉化包再装Locale插件导致汉化包虽然被安装了但界面语言检测机制一直走默认英文路径。我的建议是严格按照Locale插件→配置语言→安装汉化包→重启这个顺序来操作成功率最高。第四坑如果你公司用的是定制版Jenkins或打包在别的产品里的嵌入版Jenkins插件管理界面可能被隐藏了这种情况下用在线界面安装就行不通了。此时只能走手动部署把.hpi文件放进plugins目录同时要留意插件的依赖项是否都已经装好。6. 关于汉化这件事我最后想多说几句整套步骤其实不复杂网上教程一搜一大把但为什么很多人跟着教程装完还是中英混杂我个人觉得问题出在“只照做不思考”上。很多人看到教程说装汉化包就只装汉化包看到教程说配置Locale就只填一个zh_CN完全没搞清楚每个环节在解决什么问题。于是环境一有差异就立刻抓瞎。在做这套操作时我习惯每完成一步就停下来验证一下。装完Locale插件先去“系统管理”看有没有出现Locale菜单配置完语言参数先不装汉化包直接重启一次查看效果。这样每一步的影响范围都是清晰的即使出问题了也能快速定位到底是哪一步没生效。另外别对“全部汉化”抱有不切实际的期望。只要你还装了第三方插件就一定会遇到英文界面。毕竟插件的翻译工作靠的是社区贡献没有翻译资源的页面保持英文是常态。只要核心界面和常用功能是中文的已经足够支撑日常使用了。有个小技巧我一直用到现在把“系统管理→系统信息”里的user.language和user.country两个值作为验证依据。如果它们分别显示zh和CN那么Locale层的配置就没有问题。以后再有人跟你说Jenkins汉化不生效你先让他把这两个值发过来问题基本就定位了一半。