一篇文章解决springboot+thymeleaf多语言国际化
1.前言
博主最近在写一个多语言的项目，因为之前没实际接触过多语言的设计，所以写这篇文章记录下这次多语言开发的过程。
博主的开发环境是：Springboot1.5.6 + thymeleaf，需要注意的是，springboot 1.x和2.x有比较大的差别。
文章实现的主要功能：
- springboot+thymeleaf最基本的国际化配置
- 自定义配置国际化，区域解析器
- 读取多个分类的国际化文件；
- 后台设置前端页面显示国际化信息的文件
- 利用拦截器和注解自动设置前端页面显示国际化信息的文件
- 前端js中怎么实现国际化
2.springboot+thymeleaf最基本的国际化配置
如果国际化需求不是很复杂，使用简单的配置就能完成，下面的代码展示的就是springboot+thymeleaf最基本的国际化配置。
首先，我们先定义国际化资源文件，就是放每个语言资源的文件。springboot默认就支持国际化的，而且不需要你过多的做什么配置，只需要在 resources/ 下定义国际化配置文件即可，默认的文件名称是messages.properties，其他语言的文件名格式则是messages_国家语言编码.properties，如简体中文是messages_zh_CN.properties、英语是messages_en_US.properties.
各个语言的文件名格式
资源文件中采用键值对格式
配置好国际化资源文件后，我们编写一个配置类WebMvcConfig.java，它继承WebMvcConfigurerAdapter。该类中定义了一个CookieLocaleResolver，采用cookie来控制国际化的语言，同样的也可以定义SessionLocaleResolver，它是将国际化信息放在session中，另外AcceptHeaderLocaleResolver则是将国际化信息放在请求头中传递。下面还设置一个LocaleChangeInterceptor拦截器来拦截国际化语言的变化。
/**
* 基本配置
*
* @author Nelson(mr_caitw @ 163.com)
* @date 2020/7/3 10:24
*/
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
/**
* 配置使用cookie存储国际化相关配置信息
* @return
*/
@Bean
public LocaleResolver localeResolver() {
CookieLocaleResolver clr = new CookieLocaleResolver();
//设置默认语言为繁体中文
clr.setDefaultLocale(Locale.TAIWAN);
//最大有效时间
clr.setCookieMaxAge(3600);
//设置存储的Cookie的name为Language
clr.setCookieName("language");
return clr;
}
/**
* 拦截器配置
*
* @param registry
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
//国际化配置拦截器
registry.addInterceptor(localeChangeInterceptor()).addPathPatterns("/**");
super.addInterceptors(registry);
}
}
就这样最简单国际化后台配置就完成了，下面我们看看页面怎么使用国际化，前端只要使用 th:text="#{多语言key}" 就能完成多语言文字的渲染。我们编写一个hello.html，内容如下：
springboot + thymeleaf国际化!
然后我们启动项目，在浏览器中输入http://localhost/hello。由于我们配置了默认语言是繁体中文（不配置的话默认语言跟随浏览器设置的语言，国内浏览器默认的语言是中文），所以他默认会去messages_zh_TW.properties中找，如果没有就会去messages.properties中找国际化词。
在浏览器中输入http://localhost/hello?locale=en_US，语言就会切到英文。同样的如果url后参数设置为locale=zh_CH，语言就会切到中文。
以上就完成了最简单的多语言的实现，是不是不需要做过多的处理就能完成多语言开发？哈哈哈哈，springboot开发就是这么方便快捷！
在博主的项目里，简单的多语言还不符合我的需求，所以后面我写的是自定义国际化配置，要复杂很多，一起来看看吧！
3.进阶：自定义国际化配置和区域解析器
3.1 配置国际化资源路径
前面我提到过，springboot是默认支持国际化的，默认在 resources/ 下定义国际化配置文件即可，现在我们来自定义资源文件的路径。自定义资源文件路径需要在application.properties中定义。
文件结构
application.properties中的i18n配置
如图，我将多语言的资源文件放到了static下面（至于这里我为什么要放在static下面，后面再解释）。spring.messages.baseFolder定义多语言文件的父路径，也就是基本路径。spring.messages.basename定义每个资源文件所在的目录。到这里我们就配置好了我们自定义的国际化资源文件的位置。
3.2 实现国际化资源文件自动加载
在我们实际项目中肯定不会只有几个国际化信息那么少，通常都是成千上百个的，那我们肯定不能把这么多的国际化信息都放在messages.properties一个文件中，通常都是把国际化信息分类存放在几个文件中。但是当项目大了以后，这些国际化文件也会越来越多，这时候在application.properties文件中一个个的去配置这个文件也是不方便的，所以现在我们实现一个功能自动加载制定目录下所有的国际化文件。
在项目下创建一个类MessageResourceExtension.java继承ResourceBundleMessageSource或者ReloadableResourceBundleMessageSource。并且注入到bean中起名为messageSource，这里我们继承ResourceBundleMessageSource。需要注意的是bean的名字必须是messageSource不能改,因为在初始化ApplicationContext的时候，会查找bean名为'messageSource'的bean。这个过程在AbstractApplicationContext.java中。
/**
* 配置国际化文件自动匹配获取
* @Author Nelson ([email protected])
* @Date 2020/6/28 17:51
*/
@Slf4j
@Component("messageSource")
public class MessageResourceExtension extends ResourceBundleMessageSource {
/**
* 指定的国际化文件目录
*/
@Value(value = "${spring.messages.baseFolder}")
private String baseFolder;
/**
* 父MessageSource指定的国际化文件
*/
@Value(value = "${spring.messages.basename}")
private String basename;
public static String I18N_ATTRIBUTE = "i18n_attribute";
@PostConstruct
public void init() {
log.info("init MessageResourceExtension...");
if (!StringUtils.isEmpty(baseFolder)) {
try {
this.setBasenames(getAllBaseNames(baseFolder));
} catch (IOException e) {
log.error(e.getMessage());
}
}
//设置父MessageSource
ResourceBundleMessageSource parent = new ResourceBundleMessageSource();
//是否是多个目录
if (basename.indexOf(",") > 0) {
parent.setBasenames(basename.split(","));
} else {
parent.setBasename(basename);
}
//设置文件编码
parent.setDefaultEncoding("UTF-8");
this.setParentMessageSource(parent);
}
/**
* 获取国际化资源
* @param code 资源code
* @param locale 语言编码
* @return
*/
@Override
protected String resolveCodeWithoutArguments(String code, Locale locale) {
// 获取request中设置的指定国际化文件名
ServletRequestAttributes attr = (ServletRequestAttributes) RequestContextHolder.currentRequestAttributes();
final String i18File = (String) attr.getAttribute(I18N_ATTRIBUTE, RequestAttributes.SCOPE_REQUEST);
if (!StringUtils.isEmpty(i18File)) {
//获取在basenameSet中匹配的国际化文件名
String basename = "";
String[] baseNameArr = getBasenameSet().toArray(new String[]{});
for (String aBaseNameArr : baseNameArr) {
if (StringUtils.endsWithIgnoreCase(aBaseNameArr, i18File)) {
basename = aBaseNameArr;
break;
}
}
if (!StringUtils.isEmpty(basename)) {
//得到指定的国际化文件资源
ResourceBundle bundle = getResourceBundle(basename, locale);
if (bundle != null) {
return getStringOrNull(bundle, code);
}
}
}
//如果指定i18文件夹中没有该国际化字段,返回null会在ParentMessageSource中查找
return null;
}
/**
* 获取文件夹下所有的国际化文件名
*
* @param folderName 文件夹名
* @return
* @throws IOException
*/
public String[] getAllBaseNames(final String folderName) throws IOException {
URL url = Thread.currentThread().getContextClassLoader()
.getResource(folderName);
if (null == url) {
throw new RuntimeException("无法获取资源文件路径");
}
List baseNames = new ArrayList<>();
if (url.getProtocol().equalsIgnoreCase("file")) {
// 文件夹形式,用File获取资源路径
File file = new File(url.getFile());
if (file.exists() && file.isDirectory()) {
baseNames = Files.walk(file.toPath())
.filter(path -> path.toFile().isFile())
.map(Path::toString)
.map(path -> path.substring(path.indexOf(folderName)))
.map(this::getI18FileName)
.distinct()
.collect(Collectors.toList());
} else {
log.error("指定的baseFile不存在或者不是文件夹");
}
} else if (url.getProtocol().equalsIgnoreCase("jar")) {
// jar包形式，用JarEntry获取资源路径
String jarPath = url.getFile().substring(url.getFile().indexOf(":") + 2, url.getFile().indexOf("!"));
JarFile jarFile = new JarFile(new File(jarPath));
List baseJars = jarFile.stream()
.map(ZipEntry::toString)
.filter(jar -> jar.endsWith(folderName + "/")).collect(Collectors.toList());
jarFile.
if (baseJars.isEmpty()) {
log.info("不存在{}资源文件夹", folderName);
return new String[0];
}
baseNames = jarFile.stream().map(ZipEntry::toString)
.filter(jar -> baseJars.stream().anyMatch(jar::startsWith))
.filter(jar -> jar.endsWith(".properties"))
.map(jar -> jar.substring(jar.indexOf(folderName)))
.map(this::getI18FileName)
.distinct()
.collect(Collectors.toList());
}
return baseNames.toArray(new String[0]);
}
/**
* 把普通文件名转换成国际化文件名
*
* @param filename 文件名
* @return
*/
private String getI18FileName(String filename) {
filename = filename.replace(".properties", "");
for (int i = 0; i < 2; i++) {
int index = filename.lastIndexOf("_");
if (index != -1) {
filename = filename.substring(0, index);
}
}
return filename.replace("\\", "/");
}
}
依次解释一下几个方法。
init()方法上有一个@PostConstruct注解，这会在MessageResourceExtension类被实例化之后自动调用init()方法。这个方法获取到baseFolder目录下所有的国际化文件并设置到basenameSet中。并且设置一个ParentMessageSource，这会在找不到国际化信息的时候，调用父MessageSource来查找国际化信息。getAllBaseNames()方法获取到baseFolder的路径，然后先判断项目的Url形式为文件形式还是jar包形式，如果是文件形式则就以普通文件夹的方式读取，如果是jar包的形式，那么就要用JarEntry来处理文件。两种方式都是获取到该目录下所有的国际化文件的文件名。getI18FileName()方法把文件名转为’i18n/basename/‘格式的国际化资源名。- resolveCodeWithoutArguments
()方法从HttpServletRequest中获取到‘I18N_ATTRIBUTE’(等下再说这个在哪里设置)，这个对应我们想要显示的国际化文件名，然后我们在BasenameSet中查找该文件，再通过getResourceBundle获取到资源，最后再getStringOrNull获取到对应的国际化信息。
所以简单来说就是在MessageResourceExtension被实例化之后，把'i18n'文件夹下的资源文件的名字，加载到Basenames中，然后指定什么时候用哪个分类文件夹下的国际化资源信息。
3.3 自定义国际化区域解析器
定义WebMvcConfig.java，继承WebMvcConfigurerAdapter，使用LocaleChangeInterceptor 拦截器，来拦截语言的变化。我们设置传递语言的参数名为lang，默认是locale。
/**
* 基本配置及静态资源映射
*
* @author Nelson(mr_caitw @ 163.com)
* @date 2020/7/3 10:24
*/
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Autowired
private MessageResourceInterceptor messageResourceInterceptor;
/**
* 配置默认国际化拦截器
* @return
*/
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor lci = new LocaleChangeInterceptor();
lci.setParamName("lang");
return lci;
}
/**
* 拦截器配置
*
* @param registry
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
//国际化配置拦截器
registry.addInterceptor(localeChangeInterceptor()).addPathPatterns("/**");
super.addInterceptors(registry);
}
}
定义MyLocaleResolver.java，并且注入到bean中起名为localeResolver。重写resolveLocale()方法，获取请求路径中国际化参数值，如果不为空，则处理格式后保存到session中。如果没有带国际化参数，则判断session有没有保存，有保存，则使用保存的，也就是之前设置的，避免之后的请求不带国际化参数造成语言显示不对。否则，使用自定义的默认语言，我这里设置的是繁体中文。
/**
* 国际化区域解析器
*
* @author Nelson(mr_caitw @ 163.com)
* @date 2020/6/30 23:15
*/
@Component("localeResolver")
public class MyLocaleResolver implements LocaleResolver {
private static final String I18N_LANG = "lang";
public static final String I18N_LANG_SESSION = "lang_session";
@Override
public Locale resolveLocale(HttpServletRequest request) {
HttpSession session = request.getSession();
//获取系统的默认区域信息
Locale locale = Locale.TAIWAN;
//获取请求信息，国际化的参数值
String lang = request.getParameter(I18N_LANG);
if (!StringUtils.isEmpty(lang)) {
String[] split = lang.split("_");
//接收的第一个参数为：语言代码，国家代码
locale = new Locale(split[0], split[1]);
}else {
//如果没有带国际化参数，则判断session有没有保存，有保存，则使用保存的，也就是之前设置的，避免之后的请求不带国际化参数造成语言显示不对
Locale sessionLocale = (Locale) session.getAttribute(I18N_LANG_SESSION);
if(sessionLocale != null) {
locale = sessionLocale;
}
}
//将国际化语言保存到session
session.setAttribute(I18N_LANG_SESSION, locale);
return locale;
}
@Override
public void setLocale(HttpServletRequest request, HttpServletResponse response, Locale locale) {
}
}
3.4 自定义国际化拦截器和注解，自动设置前端页面显示国际化信息的文件
首先我们创建一个名字叫I18n的注解，名字自己随便取，这个注解可以放在类上或者方法上。
/**
* @author Nelson(mr_caitw @ 163.com)
* @date 2020/6/28 11:55
*/
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented //说明该注解将被包含在javadoc中
public @interface I18n {
/**
* 国际化文件名
*/
String value();
}然后我们定义一个名叫MessageResourceInterceptor.java的拦截器，它继承HandlerInterceptorAdapter。这个拦截器主要功能是识别我们上面定义的注解，根据我们设置的注解去取对应的国际化资源信息。
首先，如果request中已经有'I18N_ATTRIBUTE'，说明在Controller的方法中使用request.setAttribute(MessageResourceExtension.I18N_ATTRIBUTE, "user");指定设置了，就不再判断。然后判断一下进入拦截器的方法上有没有I18n的注解，如果有就设置'I18N_ATTRIBUTE'到request中并退出拦截器，如果没有就继续。再判断进入拦截的类上有没有I18n的注解，如果有就设置'I18N_ATTRIBUTE'到request中并退出拦截器，如果没有就继续。最后假如方法和类上都没有I18n的注解，那我们可以根据Controller名自动设置指定的国际化文件，比如'UserController'那么就会去找'user'的国际化文件。代码如下：
/**
* 国际化拦截器配置
* @Author Nelson ([email protected])
* @Date 2020/6/28 17:51
*/
@Component
public class MessageResourceInterceptor extends HandlerInterceptorAdapter {
@Override
public boolean preHandle(HttpServletRequest req, HttpServletResponse rep, Object handler) {
// 在跳转到该方法先清除request中的国际化信息
req.removeAttribute(MessageResourceExtension.I18N_ATTRIBUTE);
return true;
}
@Override
public void postHandle(HttpServletRequest req, HttpServletResponse rep, Object handler, ModelAndView modelAndView) {
// 在方法中设置i18路径
if (null != req.getAttribute(MessageResourceExtension.I18N_ATTRIBUTE)) {
return;
}
//判断是否HandlerMethod
HandlerMethod method = null;
if (handler instanceof HandlerMethod) {
method = (HandlerMethod) handler;
}
if (null == method) {
return;
}
// 在method注解了i18
I18n i18nMethod = method.getMethodAnnotation(I18n.class);
if (null != i18nMethod) {
req.setAttribute(MessageResourceExtension.I18N_ATTRIBUTE, i18nMethod.value());
return;
}
// 在Controller上注解了i18
I18n i18nController = method.getBeanType().getAnnotation(I18n.class);
if (null != i18nController) {
req.setAttribute(MessageResourceExtension.I18N_ATTRIBUTE, i18nController.value());
return;
}
// 根据Controller名字设置i18
String controller = method.getBeanType().getName();
int index = controller.lastIndexOf(".");
if (index != -1) {
controller = controller.substring(index + 1, controller.length());
}
index = controller.toUpperCase().indexOf("CONTROLLER");
if (index != -1) {
controller = controller.substring(0, index);
}
req.setAttribute(MessageResourceExtension.I18N_ATTRIBUTE, controller);
}
}
现在把拦截器配置到系统中，我们修改之前写的WebMvcConfig.java类。
/**
* 基本配置及静态资源映射
*
* @author Nelson(mr_caitw @ 163.com)
* @date 2020/7/3 10:24
*/
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Autowired
private MessageResourceInterceptor messageResourceInterceptor;
/**
* 配置默认国际化拦截器
* @return
*/
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor lci = new LocaleChangeInterceptor();
lci.setParamName("lang");
return lci;
}
/**
* 拦截器配置
*
* @param registry
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
//国际化配置拦截器
registry.addInterceptor(localeChangeInterceptor()).addPathPatterns("/**");
registry.addInterceptor(messageResourceInterceptor).addPathPatterns("/**");
super.addInterceptors(registry);
}
}
以上我们就做好了所有配置的步骤，那我们怎么使用，怎么指定哪一个分类下的国际化资源呢？我们看下面的代码。
3.5 使用注解指定使用哪个分类下的国际化资源
我们定义一个HelloController.java，使用我们先前定义好的i18n注解来指定使用哪个文件夹下的国际化资源。因为我们之前定义了MessageResourceInterceptor拦截器，他会识别类、方法、接口上的注解，来自动加载指定文件夹分类下的国际化资源。
@Controller
public class HelloController {
@GetMapping("/hello")
public String index() {
return "/hello";
}
//使用@I18n注解指定使用user文件夹下的国际化资源
@I18n("user")
@GetMapping("/user")
public String user() {
return "/user";
}
//使用@I18n注解指定使用event文件夹下的国际化资源
@I18n("event")
@GetMapping("/event")
public String event() {
return "/event";
}
}
至此我们就已经完成了springboot1.x + thymeleaf的国际化。这里我再把一个简单的国际化工具类贴出来。
/**
* 国际化工具
*
* @author Nelson(mr_caitw @ 163.com)
* @date 2020/6/30 11:16
*/
@Slf4j
@Component
public class LocaleMessageUtil {
@Autowired
public static MessageSource messageSource;
/**
* 获取当前语言编码
* @return
*/
public static Locale getLang(){
return LocaleContextHolder.getLocale();
}
/**
* @param code：对应文本配置的key.
* @return 对应地区的语言消息字符串
*/
public static String getMessage(String code) {
return getMessage(code, new Object[]{});
}
public static String getMessage(String code, String defaultMessage) {
return getMessage(code, null, defaultMessage);
}
public static String getMessage(String code, String defaultMessage, Locale locale) {
return getMessage(code, null, defaultMessage, locale);
}
public static String getMessage(String code, Locale locale) {
return getMessage(code, null, "", locale);
}
public static String getMessage(String code, Object[] args) {
return getMessage(code, args, "");
}
public static String getMessage(String code, Object[] args, Locale locale) {
return getMessage(code, args, "", locale);
}
public static String getMessage(String code, Object[] args, String defaultMessage) {
Locale locale = LocaleContextHolder.getLocale();
return getMessage(code, args, defaultMessage, locale);
}
public static String getMessage(String code, Object[] args, String defaultMessage, Locale locale) {
return messageSource.getMessage(code, args, defaultMessage, locale);
}
}
getLang()方法获取当前设置的国际化语言，多个重载的getMessage()方法是获取指定key的国际化值。
4.前端js实现国际化
以上我们实现了后台跟前端页面的国际化功能，可是还有个问题，那我们js中的国际化怎么实现呢？下面我们就来实现以下前端js的国际化。
前端的国际化实现，我们使用jQuery的i18n就可以了。首先我们先下载 jquery-3.1.1.min.js 和 jquery.i18n.properties.js、jquery.i18n.properties.min.js 文件， jquery.i18n.properties.js 我在网上看不同版本貌似差异很大，我最后选择了一个版本，下面我贴出来。
jquery.i18n.properties.min.js
(function(h){function v(a){a.debug&&(f("callbackIfComplete()"),f("totalFiles: "+a.totalFiles),f("filesLoaded: "+a.filesLoaded));a.async&&a.filesLoaded===a.totalFiles&&a.callback&&a.callback()}function n(a,c){c.debug&&f("loadAndParseFiles");null!==a&&0c.length)a.debug&&f("No language supplied. Pulling it from the browser ..."),c=navigator.languages&&0 这里我来解释一下为什么前面我们将国际化资源文件放在static下，现在就体现出来了，因为放在static前端能直接访问，所以前端js跟后台的国际化资源文件可以放在一起使用。当然有的人觉得分开比较好，这里看具体情况和个人喜好了，我是放在一起的。
1. 在页面引入jquery.js和jquery.i18n.properties.js两个文件
2. 在js中初始化国际化配置，这里传入一个语言编码。选择不同语言后调用该初始化方法传入一个语言编码重新初始化国际化配置。如果是刷新页面，则获取session中用户设置的国际化编码进行初始化。
/**
* 初始化前端国际化资源
* @param local 语言编码
*/
function setI18nProperties(local) {
$.i18n.properties({
name: 'messages', // 资源文件名称
path: '/i18n/', // 资源文件所在目录路径
mode: 'map', // Map的方式使用资源文件中的Key
language: local, // 设置的语言
cache: false,
encoding: 'UTF-8',
// callback: function () { // 回调方法
// console.log("回调函数中："+ i18n('login_btn'));
// }
});
}
/**
* 获取国际化资源的方法
* @param msgKey key
* @returns {*}
*/
function i18n(msgKey) {
try {
return $.i18n.prop(msgKey);
} catch (e) {
return msgKey;
}
}
//获取默认语言
const LANG_COUNTRY = [[${#locale.language+'_'+#locale.country}]];
//获取session中用户选择的国际化语言
const LANG = [[${session.lang_session}]];
const USER_LANG = !isEmpty(LANG) ? LANG : LANG_COUNTRY;
/**
* 切换语言
*/
function changeLang(lang, reload){
//改变选中样式
$(".lang-box").find("a.lang-item").removeClass("active");
$("a.lang-item[data-lang="+ lang +"]").addClass("active");
if(!reload) return;
//获取URL参数，修改语言编码
let params = POP.getUrlParam(parent.location.href);
params.lang = lang;
//去除无用属性
delete params.url;
//处理URL参数
let url = parent.location.href;
url = POP.setUrlParam(url, params);
//处理锚点
let anchor = parent.location.hash.replace('#', '');
if(!isEmpty(anchor)){
url += "#" + anchor;
}
gotoPage(url);
}
/**
* 语言切换事件
*/
$(".footer").on("click", ".lang-item", function () {
const lang = $(this).attr("data-lang");
changeLang(lang, true);
setI18nProperties(lang);
});
//页面刷新，从cookie获取语言，选中对应语言。
// const lang = $.cookie("language");
if(!isEmpty(USER_LANG)){
changeLang(USER_LANG);
setI18nProperties(USER_LANG);
}
3. js获取国际化资源并使用只需使用我们刚才定义好的工具方法i18n()，传入一个key就能获取到对应的国际化资源了。
到此，我们前端js中使用国际化也完成了。
5. 最后
上面就是博主近期项目中继承国际化多语言的所有过程了，可能有写的不完美有bug的地方，欢迎大家发现后指正。我的邮箱在上面代码中已经写出来了，有什么更好多做法或想法欢迎评论或者联系我，咱们可以探讨交流共同进步！