Java SpringBoot 国际化

i18n 国际化

在开发中,国际化(Internationalization),也叫本地化,指的是一个网站(或应用)可以支持多种不同的语言,即可以根据用户所在的语言类型和国家/地区,显示不同的文字。能够让不同国家,不同语种的用户方便使用,提高用户体验性。
实现国际化,比较简单的实现方案就是根据不同的国家和语言开发不同的程序,分别用相应的语言文字显示,例如Oracle英文官网地址:https://www.oracle.com/index.html,中文官网地址:https://www.oracle.com/cn/index.html
一般比较大型的公司会使用这种根据不同的国家和语言开发不同的程序的形式实现国家化,其一人家公司有资源投入开发,其二可以根据不同国家,不同语种用户习惯开发更加符合当地人的布局样式,交互等。
还有另外一种国家化实现方案,就是开发一套程序,可以根据用户所在区域显示不同的语言文字,但是网站/应用的布局样式等不会发生很大变化。这个方案也是要将的i18n国际化实现,i18n其实就是英文单词Internationalization(国际化)的缩写,i和n代表单词首尾字母,18代表中间的18个字母。

i18n 实现

在Java中,通过java.util.Locale类表示本地化对象,它通过语言类型和国家/地区等元素来确定创建一个本地化对象 。Locale对象表示具体的地理,时区,语言,政治等。
可以通过以下方法,获取本地系统的语言,国家等信息;以及获取代表指定地区的语言,国家信息Local对象。当然也可以调用 Locale.getAvailableLocales() 方法查看所有可用的Local对象。

  1. import java.util.Locale;
  2. public class LocalTest {
  3. public static void main(String[] args) {
  4. Locale defaultLocale = Locale.getDefault();
  5. Locale chinaLocale = Locale.CHINA;
  6. Locale usLocale = Locale.US;
  7. Locale usLocale1 = new Locale("en", "US");
  8. System.out.println(defaultLocale);
  9. System.out.println(defaultLocale.getLanguage());
  10. System.out.println(defaultLocale.getCountry());
  11. System.out.println(chinaLocale);
  12. System.out.println(usLocale);
  13. System.out.println(usLocale1);
  14. }
  15. }
  16. // 输出结果
  17. zh_CN
  18. zh
  19. CN
  20. zh_CN
  21. en_US
  22. en_US

一般会将不同的语言的属性值存放在不同的配置文件中,ResourceBundle类可以根据指定的baseNameLocal对象,就可以找到相应的配置文件,从而读取到相应的语言文字,从而构建出ResourceBundle对象,然后可以通过ResourceBundle.getString(key)就可以取得key在不同地域的语言文字了。
Properties配置文件命名规则:baseName_local.properties
假如baseName为i18n,则相应的配置文件应该命名为如下:

  • 中文的配置文件:i18n_zh_CN.properties
  • 英文的配置文件:i18n_en_US.properties

然后在两个配置文件中,存放着键值对,对应不同的语言文字

  1. # i18n_zh_CN.properties文件中
  2. userName=Fcant
  3. # i18n_en_US.properties文件中
  4. userName=Peel

通过如下方式,就可以获取相应语言环境下的信息了,如下:

  1. Locale chinaLocale = Locale.CHINA;
  2. ResourceBundle resourceBundle = ResourceBundle.getBundle("i18n", chinaLocale);
  3. String userName = resourceBundle.getString("userName");
  4. System.out.println(userName);
  5. Locale usLocale = Locale.US;
  6. resourceBundle = ResourceBundle.getBundle("i18n", usLocale);
  7. userName = resourceBundle.getString("userName");
  8. System.out.println(userName);
  9. // 输出结果
  10. Fcant
  11. Peel

对于不同地域语言环境的用户,是如何处理国际化呢?其实原理很简单,假设客户端发送一个请求到服务端,在请求头中设置了键值对,“Accept-Language”:“zh-CN”,根据这个信息,可以构建出一个代表这个区域的本地化对象Locale,根据配置文件的baseName和Locale对象就可以知道读取哪个配置文件的属性,将要显示的文字格式化处理,最终返回给客户端进行显示。

SpringBoot 集成 i18n

在SpringBoot中,会使用到一个MessageSource接口,用于访问国际化信息,此接口定义了几个重载的方法。code即国际化资源的属性名(键);args即传递给格式化字符串中占位符的运行时参数值;local即本地化对象;resolvable封装了国际化资源属性名,参数,默认信息等。

  • String getMessage(String code, @Nullable Object[] args, @Nullable String defaultMessage, Locale locale)
  • String getMessage(String code, @Nullable Object[] args, Locale locale)
  • String getMessage(MessageSourceResolvable resolvable, Locale locale)

SpringBoot提供了国际化信息自动配置类MessageSourceAutoConfiguration,它可以生成MessageSource接口的实现类ResourceBundleMessageSource,注入到Spring容器中。MessageSource配置生效依靠ResourceBundleCondition条件,从环境变量中读取spring.messages.basename的值(默认值messages),这个值就是MessageSource对应的资源文件名称,资源文件扩展名是.properties,然后通过PathMatchingResourcePatternResolverclasspath*:目录下读取对应的资源文件,如果能正常读取到资源文件,则加载配置类。源码如下:

  1. package org.springframework.boot.autoconfigure.context;
  2. @Configuration
  3. @ConditionalOnMissingBean(value = MessageSource.class, search = SearchStrategy.CURRENT)
  4. @AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
  5. @Conditional(ResourceBundleCondition.class)
  6. @EnableConfigurationProperties
  7. public class MessageSourceAutoConfiguration {
  8. private static final Resource[] NO_RESOURCES = {};
  9. // 我们可以在application.properties文件中修改spring.messages前缀的默认值,比如修改basename的值
  10. @Bean
  11. @ConfigurationProperties(prefix = "spring.messages")
  12. public MessageSourceProperties messageSourceProperties() {
  13. return new MessageSourceProperties();
  14. }
  15. // 生成ResourceBundleMessageSource实例,注入容器中
  16. @Bean
  17. public MessageSource messageSource(MessageSourceProperties properties) {
  18. ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
  19. if (StringUtils.hasText(properties.getBasename())) {
  20. messageSource.setBasenames(StringUtils
  21. .commaDelimitedListToStringArray(StringUtils.trimAllWhitespace(properties.getBasename())));
  22. }
  23. if (properties.getEncoding() != null) {
  24. messageSource.setDefaultEncoding(properties.getEncoding().name());
  25. }
  26. messageSource.setFallbackToSystemLocale(properties.isFallbackToSystemLocale());
  27. Duration cacheDuration = properties.getCacheDuration();
  28. if (cacheDuration != null) {
  29. messageSource.setCacheMillis(cacheDuration.toMillis());
  30. }
  31. messageSource.setAlwaysUseMessageFormat(properties.isAlwaysUseMessageFormat());
  32. messageSource.setUseCodeAsDefaultMessage(properties.isUseCodeAsDefaultMessage());
  33. return messageSource;
  34. }
  35. protected static class ResourceBundleCondition extends SpringBootCondition {
  36. private static ConcurrentReferenceHashMap<String, ConditionOutcome> cache = new ConcurrentReferenceHashMap<>();
  37. @Override
  38. public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) {
  39. String basename = context.getEnvironment().getProperty("spring.messages.basename", "messages");
  40. ConditionOutcome outcome = cache.get(basename);
  41. if (outcome == null) {
  42. outcome = getMatchOutcomeForBasename(context, basename);
  43. cache.put(basename, outcome);
  44. }
  45. return outcome;
  46. }
  47. private ConditionOutcome getMatchOutcomeForBasename(ConditionContext context, String basename) {
  48. ConditionMessage.Builder message = ConditionMessage.forCondition("ResourceBundle");
  49. for (String name : StringUtils.commaDelimitedListToStringArray(StringUtils.trimAllWhitespace(basename))) {
  50. for (Resource resource : getResources(context.getClassLoader(), name)) {
  51. if (resource.exists()) {
  52. return ConditionOutcome.match(message.found("bundle").items(resource));
  53. }
  54. }
  55. }
  56. return ConditionOutcome.noMatch(message.didNotFind("bundle with basename " + basename).atAll());
  57. }
  58. // 读取classpath*:路径下的配置文件
  59. private Resource[] getResources(ClassLoader classLoader, String name) {
  60. String target = name.replace('.', '/');
  61. try {
  62. return new PathMatchingResourcePatternResolver(classLoader)
  63. .getResources("classpath*:" + target + ".properties");
  64. }
  65. catch (Exception ex) {
  66. return NO_RESOURCES;
  67. }
  68. }
  69. }
  70. }

以下这个类是Spring国际化处理的属性配置类,可以在application.properties文件中自定义修改这些默认值,例如:spring.messages.basename=i18n

  1. package org.springframework.boot.autoconfigure.context;
  2. public class MessageSourceProperties {
  3. /**
  4. * Comma-separated list of basenames (essentially a fully-qualified classpath
  5. * location), each following the ResourceBundle convention with relaxed support for
  6. * slash based locations. If it doesn't contain a package qualifier (such as
  7. * "org.mypackage"), it will be resolved from the classpath root.
  8. */
  9. private String basename = "messages";
  10. /**
  11. * Message bundles encoding.
  12. */
  13. private Charset encoding = StandardCharsets.UTF_8;
  14. /**
  15. * Loaded resource bundle files cache duration. When not set, bundles are cached
  16. * forever. If a duration suffix is not specified, seconds will be used.
  17. */
  18. @DurationUnit(ChronoUnit.SECONDS)
  19. private Duration cacheDuration;
  20. /**
  21. * Whether to fall back to the system Locale if no files for a specific Locale have
  22. * been found. if this is turned off, the only fallback will be the default file (e.g.
  23. * "messages.properties" for basename "messages").
  24. */
  25. private boolean fallbackToSystemLocale = true;
  26. /**
  27. * Whether to always apply the MessageFormat rules, parsing even messages without
  28. * arguments.
  29. */
  30. private boolean alwaysUseMessageFormat = false;
  31. /**
  32. * Whether to use the message code as the default message instead of throwing a
  33. * "NoSuchMessageException". Recommended during development only.
  34. */
  35. private boolean useCodeAsDefaultMessage = false;
  36. // 省略get/set
  37. }

在类路径下创建好国际化配置文件之后,就可以注入MessageSource实例,进行国际化处理了:
i18n.properties文件是默认文件,当找不到语言的配置的时候,使用该文件进行展示。

  1. @Autowired
  2. private MessageSource messageSource;
  3. @GetMapping("test")
  4. public GeneralResult<String> test() {
  5. // 获取客户端的语言环境Locale对象,即取的请求头Accept-Language键的值来判断,我们也可以自定义请求头键,来获取语言标识
  6. Locale locale = LocaleContextHolder.getLocale();
  7. String userName = messageSource.getMessage("userName", null, locale);
  8. System.out.println(userName);
  9. return GeneralResult.genSuccessResult(userName);
  10. }

上面是利用Spirng自带的LocaleContextHolder来获取本地对象Locale,它是取的请求头Accept-Language键的语言值来判断生成相应Locale对象。也可以根据其他方式,例如请求头中自定义键的值,来生成Locale对象,然后再通过messageSource.getMessage()方法来实现最终的国家化。