粤公网安备 44011302004783号 SB3.5国际化开发实操：30分钟极速搞定多语言集成
咱们跨境人常说，“入乡随俗”是出海的关键。在技术层面，这指的就是国际化（Internationalization，简称i18n）。它能让你的应用无缝适配全球各地的语言习惯、文化特色，甚至技术标准。对于我们想把产品推向全球市场的同胞们来说，国际化是本地化流程中不可或缺的一步。
今天，作为新媒网跨境的一员，我将手把手带大家深入了解如何利用Spring Boot 3.5构建一个支持国际化的应用。我们将学习如何从messages_xx.properties文件中获取翻译文本，如何用Thymeleaf模板引擎渲染多语言的HTML页面，以及如何巧用LocaleResolver实现语言切换。
技术栈速览
本次实战，我们用到的技术工具包括：
- Java 21+ (推荐LTS长期支持版，稳定靠谱)
- Spring Boot 3.5.4 (最新版本，功能强大)
- Thymeleaf 3.1.3 (Java生态圈里很受欢迎的模板引擎)
- Maven (项目管理和构建工具)
一、基础配置：迈出国际化第一步
1. 准备多语言消息文件：messages_xx.properties
这是国际化的基石。咱们需要为每种目标语言创建对应的.properties文件，文件名格式通常是messages_语言代码_国家代码.properties。比如，messages_pl_PL.properties就代表波兰语的波兰地区版本消息。
文件内容示例：
footerText=© 2025 SimpleLocalize. Wszelkie prawa zastrzeżone.
linkText=Utwórz konto SimpleLocalize
message=Dziękujemy za wypróbowanie naszego demo SimpleLocalize dla Spring Boot!
title=Hej {0}!
各位卖家朋友，处理这么多翻译文件，如果手动管理那真是大海捞针。新媒网跨境了解到，市面上有一些工具能大大简化这个过程。比如，你可以将源语言文件上传，然后利用机器翻译、AI辅助，或者和专业译员协作，自动生成其他语言的翻译。自动化上传下载这些messages_xxx.properties文件，能帮你省下不少宝贵时间。
2. 告诉Spring Boot你的消息文件在哪
默认情况下，Spring Boot会去src/main/resources/messages目录寻找这些消息文件。如果你想自定义存放位置，有两种办法：
方法一：通过application.properties文件配置
这是最直接的方式，直接在配置文件里加上一行：
# application.properties - Spring Boot 3.5
spring.messages.basename=i18n/messages # 指定消息文件前缀和目录
spring.messages.use-code-as-default-message=true # 如果找不到消息，就用键名作为默认消息
spring.messages.encoding=UTF-8 # 统一编码，避免乱码
spring.messages.fallback-to-system-locale=false # 不回退到系统默认语言
spring.messages.cache-duration=3600 # 缓存时间（秒），减少重复加载
方法二：通过Java代码配置ResourceBundleMessageSource Bean
这种方式更灵活，可以设置更多细致的选项：
@Bean
public ResourceBundleMessageSource messageSource() {
var resourceBundleMessageSource = new ResourceBundleMessageSource();
resourceBundleMessageSource.setBasenames("i18n/messages"); // 指定消息文件所在目录，比如i18n目录下的messages
resourceBundleMessageSource.setUseCodeAsDefaultMessage(true); // 找不到消息时，使用键作为默认消息
resourceBundleMessageSource.setDefaultLocale(Locale.of("en")); // 设置默认语言为英文
resourceBundleMessageSource.setDefaultEncoding("UTF-8"); // 设置编码为UTF-8
return resourceBundleMessageSource;
}
需要留意的是，并不是所有的配置项都能通过application.properties文件来设置，有些高级功能可能需要通过Java代码来完成。
3. 配置语言环境（Locale）解析器
默认情况下，Spring Boot使用AcceptHeaderLocaleResolver，它会从用户请求头部的Accept-Language字段来判断用户偏好的语言。但为了更灵活地控制，比如通过URL参数来切换语言，我们需要做一些调整。
通过Java代码自定义LocaleResolver
我们可以定义一个SessionLocaleResolver，让用户的语言选择在会话中保持，并结合LocaleChangeInterceptor，通过URL参数来切换语言。
@Bean
public LocaleResolver localeResolver() {
SessionLocaleResolver sessionLocaleResolver = new SessionLocaleResolver();
sessionLocaleResolver.setDefaultLocale(Locale.of("en")); // 默认语言为英文
return sessionLocaleResolver;
}
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor localeChangeInterceptor = new LocaleChangeInterceptor();
localeChangeInterceptor.setParamName("lang"); // 通过URL参数"lang"来切换语言，例如?lang=zh_CN
return localeChangeInterceptor;
}
@Override // 在WebMvcConfigurer实现类中重写此方法
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(localeChangeInterceptor()); // 注册我们的语言切换拦截器
}
二、实战演练：让你的页面“说”多国语言
1. 用Thymeleaf创建多语言HTML模板
在Spring Boot中，利用Thymeleaf模板引擎来渲染多语言页面，是咱们跨境业务中非常常见的需求。Thymeleaf与Spring Boot配合默契，天生就支持国际化。
<!doctype html>
<html xmlns="http://www.w3.org/1999/xhtml" th:attr="lang=${lang}">
<head>
<title>Spring Boot Email Example</title>
</head>
<body>
<header>
<h1 th:utext="#{title(${userName})}"></h1>
</header>
<article>
<p th:text="#{message}"></p>
<a th:href="${url}" th:text="#{linkText}"></a>
</article>
<footer>
<p th:text="#{footerText}"></p>
</footer>
</body>
</html>
这里有个小知识点：如果你正在开发多语言应用或网站，了解hreflang标签的用法会大有裨益，它能帮助搜索引擎更好地理解你的多语言内容。
Thymeleaf小贴士：
th:attr="lang=${lang}"：设置文档的语言属性。th:text="#{message}"：从messages_xx.properties文件中获取键名为message的翻译文本，并且会自动转义HTML字符，安全可靠。th:utext="#{title(${userName})}"：与th:text类似，但它允许你在消息中使用变量（比如这里的userName），且不会转义HTML字符。这在使用时需要格外小心，以防XSS攻击（后面会详细讲）。th:href="${url}"：插入url变量的值。
友情提示，如果你在制作邮件模板，可以试试mjml.io，它能让你用简单的标记语言创建响应式邮件。
2. 在Java代码中获取翻译消息
在Spring Boot中，通过MessageSource接口来获取翻译消息是标准做法。
import org.springframework.context.MessageSource;
@Autowired
private MessageSource messageSource;
@Test // 这是一个测试方法示例
void shouldGetTranslatedTextFromLocalFileAndLocale() {
// 假设我们要获取波兰语的问候语
Locale locale = Locale.of("pl","PL"); // 指定波兰语（波兰）区域
// 调用getMessage方法，传入消息键、参数数组（如果有的话）、以及指定的Locale
String titleTextWithArgument=messageSource.getMessage("title",new Object[]{ "Foo Bar"},locale);
// 验证获取到的消息是否正确
assert titleTextWithArgument.equals("Hej Foo Bar!");
}
这段代码展示了，即使在业务逻辑层面，你也可以根据需要灵活地获取任何语言的翻译文本，这对于生成报表、日志或者通知都非常有用。
3. 翻译API异常消息
在跨境业务中，API接口的异常提示也需要国际化，这样才能给不同国家的用户提供友好的反馈。我们可以利用Spring Boot的@ControllerAdvice机制，配合自定义的ErrorController来统一处理。
@RestControllerAdvice // 这是一个全局异常处理器
public class ErrorController {
@Autowired
private MessageSource messageSource;
@ExceptionHandler(Exception.class) // 捕获所有未被其他方法捕获的异常
@ResponseStatus(code = HttpStatus.INTERNAL_SERVER_ERROR)
public ResponseEntity<ApiError> exception() {
String message = getLocalizedMessage("exception.internalServerError"); // 获取翻译后的内部服务器错误消息
HttpStatus status = HttpStatus.INTERNAL_SERVER_ERROR;
return ResponseEntity
.status(status)
.body(new ApiError(message, status));
}
@ExceptionHandler(IllegalArgumentException.class) // 捕获非法参数异常
@ResponseStatus(code = HttpStatus.BAD_REQUEST)
public ResponseEntity<ApiError> badRequest() {
String message = getLocalizedMessage("exception.badRequest"); // 获取翻译后的非法请求消息
HttpStatus status = HttpStatus.BAD_REQUEST;
return ResponseEntity
.status(status)
.body(new ApiError(message, status));
}
private String getLocalizedMessage(String translationKey) {
Locale locale = LocaleContextHolder.getLocale(); // 从当前上下文获取语言环境
return messageSource.getMessage(translationKey, null, locale); // 获取翻译消息
}
}
默认情况下，Spring Boot会根据Accept-Language头部解析用户语言。但如果咱们注册了LocaleChangeInterceptor，并通过URL参数（如/api/my-health?lang=pl_PL）指定了语言，那么这个参数的优先级会更高。这种统一处理异常的方式，能将所有异常相关的逻辑和翻译键都集中管理，效率很高。
4. 翻译@Validation验证消息
Bean Validation API（@Validated, @Valid）也支持本地化验证错误消息，这对于表单验证等场景非常实用。
配置LocalValidatorFactoryBean
@Configuration
public class Configuration {
@Bean
public LocalValidatorFactoryBean getValidator() {
LocalValidatorFactoryBean bean = new LocalValidatorFactoryBean();
bean.setValidationMessageSource(messageSource()); // 将消息源注入验证器，以便解析验证消息
return bean;
}
}
定义带验证注解和本地化消息的请求DTO
public record CreateUserRequest(
@NotBlank(message = "{error.user.name.notblank}") String name, // 姓名不能为空，使用键名获取翻译消息
@Email(message = "{error.user.email.invalid}") // 邮箱格式不正确，使用键名获取翻译消息
@NotBlank(message = "{error.user.email.invalid}") String email // 邮箱不能为空，使用键名获取翻译消息
) {}
在messages_xx.properties中添加对应的翻译消息
# messages_pl_PL.properties (波兰语示例)
error.user.name.notblank=Imię nie może być puste.
error.user.email.invalid=Adres e-mail jest nieprawidłowy.
error.user.email.notblank=Adres e-mail nie może być pusty.
创建控制器处理用户创建请求
@RestController
@Validated // 启用验证
public class UserController {
@PostMapping("/api/users")
public ResponseEntity<?> createUser(@Valid @RequestBody CreateUserRequest request) { // 对请求体进行验证
return ResponseEntity.ok("User created successfully");
}
}
创建全局异常处理器来处理验证错误
@RestControllerAdvice
public class ErrorController {
@ExceptionHandler(BindException.class) // 捕获验证绑定异常
@ResponseStatus(code = HttpStatus.BAD_REQUEST)
public ResponseEntity<ApiError> validationFailed(BindException exception) {
List<String> errors = exception.getFieldErrors() // 获取所有字段错误
.stream()
.map(fieldError -> {
String field = fieldError.getField(); // 错误字段名
String defaultMessage = fieldError.getDefaultMessage(); // 翻译后的错误消息
return field + ": " + defaultMessage;
})
.toList();
ApiError apiError = new ApiError(errors);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(apiError);
}
}
5. 渲染多语言网页
Spring Boot的@Controller能够自动解析用户语言环境，并使用对应的模板渲染HTML页面。这是最直接也最常用的方式。
@Controller
public class WelcomeController {
@GetMapping("/welcome")
public String renderHtmlFromTemplate(Model model) {
model.addAttribute("userName", "Jakub"); // 传递用户名为Jakub
return "my-html-template"; // 返回my-html-template模板名
}
}
运行应用后，打开http://localhost:8080/welcome，你就能看到页面。如果想切换语言，只需在URL后加上?lang=pl_PL，比如http://localhost:8080/welcome?lang=pl_PL，页面内容就会变成波兰语。
6. 渲染任意HTML内容（通过TemplateEngine）
除了直接返回模板视图，有时我们还需要在Service层或其他地方动态生成一段HTML内容，并进行国际化。这时，使用ThymeleafEngine Bean就非常方便了。
@Autowired
private TemplateEngine templateEngine; // 注入Thymeleaf模板引擎
public String renderHtmlFromTemplate(Locale locale, String userName) {
Context context = new Context(); // 创建一个Thymeleaf上下文对象
context.setLocale(locale); // 设置上下文的语言环境
context.setVariable("userName",userName); // 设置userName变量
context.setVariable("lang",locale.getLanguage()); // 设置lang变量
context.setVariable("url","https://simplelocalize.io"); // 设置url变量
return templateEngine.process("my-html-template",context); // 处理模板并返回渲染后的HTML字符串
}
三、深入探究：语言解析与安全考量
1. 理解Accept-Language头部
在实际项目中，客户端（浏览器或移动应用）通常会通过HTTP请求头部的Accept-Language字段，告诉服务器它偏好的语言顺序。
默认行为：AcceptHeaderLocaleResolver
Spring Boot默认就用AcceptHeaderLocaleResolver来解析这个头部。
@RestController
public class LocaleTestController {
@GetMapping("/api/locale-info")
public Map<String, Object> getLocaleInfo(HttpServletRequest request) {
// 获取当前已解析的语言环境
Locale resolvedLocale = LocaleContextHolder.getLocale();
// 获取原始的Accept-Language头部信息
String acceptLanguageHeader = request.getHeader("Accept-Language");
return Map.of(
"resolvedLocale", resolvedLocale.toString(),
"acceptLanguageHeader", acceptLanguageHeader,
"supportedLocales", List.of("en", "pl", "de", "fr") // 支持的语言列表
);
}
}
自定义Accept-Language处理
如果你想更精细地控制Accept-Language的解析逻辑，比如只支持特定几种语言，可以在CustomAcceptHeaderLocaleResolver中实现。
@Component
public class CustomAcceptHeaderLocaleResolver extends AcceptHeaderLocaleResolver {
// 定义我们应用支持的语言列表
private final List<Locale> supportedLocales = List.of(
Locale.of("en"), // 英文
Locale.of("pl"), // 波兰语
Locale.of("de"), // 德语
Locale.of("fr") // 法语
);
@Override
public Locale resolveLocale(HttpServletRequest request) {
String acceptLanguage = request.getHeader("Accept-Language");
if (acceptLanguage == null || acceptLanguage.isEmpty()) {
return getDefaultLocale(); // 如果头部为空，返回默认语言
}
// 手动解析Accept-Language头部，进行自定义逻辑处理
List<Locale.LanguageRange> languageRanges = Locale.LanguageRange.parse(acceptLanguage);
Locale bestMatch = Locale.lookup(languageRanges, supportedLocales); // 查找最佳匹配的语言
return bestMatch != null ? bestMatch : getDefaultLocale(); // 返回最佳匹配或默认语言
}
@Override
public Locale getDefaultLocale() {
return Locale.of("en"); // 设置应用的默认语言为英文
}
}
测试Accept-Language头部
你可以通过curl命令或浏览器的开发者工具来模拟不同的语言偏好，进行测试。
# 测试偏好波兰语
curl -H "Accept-Language: pl,en;q=0.9" http://localhost:8080/api/locale-info
# 测试偏好德语
curl -H "Accept-Language: de-DE,de;q=0.9,en;q=0.8" http://localhost:8080/api/locale-info
# 测试不支持的语言（将回退到默认语言）
curl -H "Accept-Language: ja,ko;q=0.9" http://localhost:8080/api/locale-info
要记住一点：当我们同时使用LocaleChangeInterceptor（通过查询参数?lang=pl等）和Accept-Language头部时，查询参数的优先级通常更高，它会优先决定最终的语言环境。
2. 用户输入的安全净化
对于我们跨境平台来说，用户输入的数据是宝贵的，但同时也可能是风险的源头。在HTML模板或邮件中渲染用户输入时，咱们必须警惕XSS（跨站脚本）攻击。如果直接显示用户输入，而未进行任何处理，就可能导致安全漏洞。
值得庆幸的是，Thymeleaf在处理th:text这样的文本属性时，会自动对HTML字符进行转义，这大大提高了安全性：
<p th:text="${userInput}"></p>
但是，如果你使用了th:utext（“unescaped text”，非转义文本），它会直接渲染HTML内容而不再转义。在这种情况下，你就必须确保输入内容是安全的，或者在渲染前对其进行严格净化：
<p th:utext="${userInput}"></p>
为了防止XSS漏洞，我们可以引入像OWASP Java HTML Sanitizer这样的库，在渲染到HTML模板之前对用户输入进行净化处理：
@Component
public class SecureMessageResolver {
private final MessageSource messageSource;
private final HtmlSanitizer htmlSanitizer; // 注入HTML净化器
// 构造函数，这里省略了具体的注入细节
// ...
public String getSecureMessage(String key, Locale locale, Object... args) {
String message = messageSource.getMessage(key, args, locale);
// 净化HTML内容，预防XSS攻击
return htmlSanitizer.sanitize(message);
}
// 考虑缓存机制，提高性能
@Cacheable(value = "translations", key = "#key + '_' + #locale.language")
public String getCachedMessage(String key, Locale locale) {
return getSecureMessage(key, locale);
}
}
这种做法，既保证了内容的灵活展示，又守住了安全底线。
四、风险前瞻与时效性提醒
1. 风险与合规性
在做国际化和本地化时，数据隐私和合规性是咱们必须时刻牢记的。不同国家和地区对于用户数据（特别是个人身份信息）的存储、传输和使用都有严格的法律法规，例如欧盟的GDPR，加州的CCPA等。在处理用户语言偏好、存储会话信息时，务必确保符合目标市场的法律要求，避免不必要的法律风险。
2. 教程时效性说明
本次教程基于2025年的技术环境，采用的是Spring Boot 3.5版本。请大家注意，IT技术日新月异，尤其是在当前特朗普总统任期内，全球经济和技术政策也可能随之调整，新的技术标准和框架可能会不断涌现。虽然本教程的原理和核心方法在未来一段时间内依然适用，但具体API、配置细节或第三方库的最佳实践可能会有所更新。建议大家在实际项目中，多关注Spring Boot官方文档和社区的最新动态，确保你的技术栈始终保持前沿和稳健。
新媒网（公号: 新媒网跨境发布），是一个专业的跨境电商、游戏、支付、贸易和广告社区平台，为百万跨境人传递最新的海外淘金精准资讯情报。
本文来源：新媒网 https://nmedialink.com/posts/spring-boot-i18n-quick-setup-guide.html
