Spring Boot i18n Internals: MessageSource, LocaleResolver & Source Code Flow
This article provides a comprehensive deep dive into Spring Boot internationalization, covering MessageSource message resolution with resource bundle loading and fallback strategies, four LocaleResolver implementations for determining request locale, LocaleChangeInterceptor for runtime language switching, and the complete source-code-level request-to-response flow with practical configuration and code examples.
1. What Problems Does Internationalization Solve
1.1 Two Core Concepts
Locale : Composed of language and region, e.g., zh_CN (Chinese China), en_US (English US), ja_JP.
Message : Same message code maps to different text per Locale. Example: code = "greeting" → zh_CN → "你好,{0}", en_US → "Hello, {0}".
1.2 Why Not Hardcode
Separate copy from code into resource files.
Resolve correct language at runtime based on current Locale.
Add new languages by adding resource files only, no business logic changes.
1.3 Overall Architecture
Request arrives
↓
LocaleResolver resolves current Locale
↓
Business code calls MessageSource.getMessage(code, args, locale)
↓
MessageSource finds resource file by Locale, fills parameters
↓
Returns localized copy2. Message System: MessageSource & Resource File Loading
2.1 MessageSource Interface
Spring abstracts a unified message resolution interface:
public interface MessageSource {
String getMessage(String code, Object[] args, String defaultMessage, Locale locale);
String getMessage(String code, Object[] args, Locale locale) throws NoSuchMessageException;
String getMessage(MessageSourceResolvable resolvable, Locale locale);
}Core parameters: message code, argument array, default message, target Locale.
2.2 Two Common Implementations
ResourceBundleMessageSource : Based on JDK ResourceBundle, reads classpath resource bundles, loads at startup.
ReloadableResourceBundleMessageSource : Supports timed hot reload, can read non-classpath paths, suitable for runtime copy changes.
2.3 Resource File Naming Convention
With basename messages, files match by Locale suffix:
messages.properties # Root fallback file
messages_zh_CN.properties # Simplified Chinese (China)
messages_en_US.properties # English (US)
messages_zh.properties # Language only: ChineseLookup order (for zh_CN):
messages_zh_CN.properties
↓ not found
messages_zh.properties
↓ not found
messages.properties (root file)
↓ still not found
Return code itself / throw NoSuchMessageException2.4 Message Content & Parameter Placeholders
Resource files use MessageFormat -style placeholders:
# messages_zh_CN.properties
greeting=你好,{0}
order.created=订单 {0} 已创建,金额 {1} 元
user.not.found=用户 {0} 不存在
# messages_en_US.properties
greeting=Hello, {0}
order.created=Order {0} created, amount {1}
user.not.found=User {0} not foundCall with argument array, filled in {0}, {1} order.
2.5 Spring Boot Auto-Configuration
MessageSourceAutoConfigurationassembles MessageSource via spring.messages.*:
spring:
messages:
basename: messages
encoding: UTF-8
cache-duration: 3600000
fallback-to-system-locale: true
use-code-as-default-message: false2.6 Fallback Strategy Details
fallback-to-system-locale=true: If specified Locale not found, fall back to JVM system default Locale. use-code-as-default-message=true: If ultimately not found, return code directly instead of throwing exception.
Production recommendation: Explicitly provide root messages.properties fallback to avoid raw codes leaking.
3. Locale Resolution: Four LocaleResolvers & Switching Interceptor
3.1 LocaleResolver Interface
public interface LocaleResolver {
Locale resolveLocale(HttpServletRequest request);
void setLocale(HttpServletRequest request, HttpServletResponse response, Locale locale);
}It decides "which Locale for current request" and supports switching when needed.
3.2 Four Implementations
AcceptHeaderLocaleResolver : Basis: Accept-Language header; Storage: Stateless, parsed each request; Typical scenario: Frontend-backend separation, browser auto-sends language (default).
SessionLocaleResolver : Basis: Session attribute; Storage: Server-side Session; Typical scenario: Switch per user preference after login.
CookieLocaleResolver : Basis: Cookie; Storage: Browser Cookie; Typical scenario: Retain language preference across requests.
FixedLocaleResolver : Basis: Fixed config; Storage: None; Typical scenario: Single language or forced Locale.
3.3 Default: AcceptHeaderLocaleResolver
Spring Boot uses it by default, parsing browser/client Accept-Language header: Accept-Language: zh-CN,zh;q=0.9,en;q=0.8 Resolves preferred Locale as zh_CN. Stateless, suitable for pure API services.
3.4 Session & Cookie Resolvers
SessionLocaleResolver : Stores chosen Locale in Session, effective for entire session after switch.
CookieLocaleResolver : Writes Locale into Cookie, automatically sent on next request, suitable for cross-session preference retention.
3.5 LocaleChangeInterceptor: Switch Language by Parameter
Resolver alone cannot actively switch. LocaleChangeInterceptor intercepts request, reads specified parameter, calls resolver's setLocale:
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Bean
public LocaleResolver localeResolver() {
SessionLocaleResolver resolver = new SessionLocaleResolver();
resolver.setDefaultLocale(Locale.SIMPLIFIED_CHINESE);
return resolver;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("lang"); // parameter name, default locale
registry.addInterceptor(interceptor);
}
}Request with ?lang=en_US switches Locale to en_US, stored in Session/Cookie.
3.6 LocaleContextHolder
Current Locale also bound to LocaleContextHolder, accessible in non-web threads, async scenarios:
Locale locale = LocaleContextHolder.getLocale();Note: Async threads don't inherit context by default, must pass manually.
4. Source Code Flow: From Request to Copy Output
4.1 Complete Process
① Request reaches DispatcherServlet
↓
② LocaleResolver.resolveLocale(request) determines Locale
↓
③ LocaleContextHolder binds current Locale
↓
④ Controller / business code injects MessageSource
↓
⑤ getMessage(code, args, locale)
↓
⑥ MessageSource finds resource bundle by basename + Locale
↓
⑦ Hit file → MessageFormat fills parameters → returns copy
↓ not hit
⑧ Fallback chain: language variant → system Locale → root file → code / exception4.2 Message Lookup Source Code Perspective
ResourceBundleMessageSourceuses ResourceBundle to load, caches loaded bundles:
protected String getStringOrNull(Locale locale, String code) {
// 1. Get ResourceBundle for that Locale
ResourceBundle bundle = getBundle(basename, locale);
// 2. Read copy for code
if (bundle != null && bundle.containsKey(code)) {
return bundle.getString(code);
}
return null; // not hit, enter fallback
}4.3 Parameter Formatting
After getting template copy, uses MessageFormat to fill parameters:
protected String formatMessage(String msg, Object[] args, Locale locale) {
if (args == null || args.length == 0) {
return msg;
}
MessageFormat format = new MessageFormat(msg, locale);
return format.format(args);
}4.4 How Validation Messages Go Through i18n
@Validatedvalidation failure produces BindingResult, its error messages also resolved via MessageSource. Validation annotation's message = "{user.not.found}", curly braces syntax means look up corresponding code in message source.
4.5 Core Source Code Classes
MessageSource : Message resolution abstraction
ResourceBundleMessageSource : Resource bundle implementation
ReloadableResourceBundleMessageSource : Hot-reloadable implementation
MessageSourceAutoConfiguration : Spring Boot auto-wiring
LocaleResolver : Locale resolution abstraction
AcceptHeaderLocaleResolver : Request-header based
SessionLocaleResolver : Session based
CookieLocaleResolver : Cookie based
LocaleChangeInterceptor : Parameter-switch interceptor
LocaleContextHolder : Context holds current Locale
5. Practice: Configuration, Controller, Validation & Exception Messages
5.1 Resource Files
src/main/resources/messages_zh_CN.properties:
greeting=你好,{0}
order.created=订单 {0} 已创建,金额 {1} 元
user.not.found=用户 {0} 不存在src/main/resources/messages_en_US.properties:
greeting=Hello, {0}
order.created=Order {0} created, amount {1}
user.not.found=User {0} not found5.2 YML Configuration
spring:
messages:
basename: messages
encoding: UTF-8
fallback-to-system-locale: true5.3 Controller Fetching Messages
@RestController
@RequestMapping("/i18n")
public class GreetController {
private final MessageSource messageSource;
public GreetController(MessageSource messageSource) {
this.messageSource = messageSource;
}
@GetMapping("/greet")
public String greet(@RequestParam(defaultValue = "访客") String name) {
Locale locale = LocaleContextHolder.getLocale();
return messageSource.getMessage("greeting", new Object[]{name}, locale);
}
@GetMapping("/order/{id}")
public String order(@PathVariable String id, @RequestParam BigDecimal amount) {
Locale locale = LocaleContextHolder.getLocale();
return messageSource.getMessage(
"order.created", new Object[]{id, amount}, locale);
}
}5.4 Validation Annotation i18n
@Data
public class UserDTO {
@NotBlank(message = "{user.name.required}")
private String name;
@NotNull(message = "{user.age.required}")
private Integer age;
}
@RestController
public class UserController {
@PostMapping("/user")
public Result create(@Valid @RequestBody UserDTO dto, BindingResult result) {
if (result.hasErrors()) {
String msg = result.getFieldError().getDefaultMessage();
return Result.fail(msg);
}
return Result.ok();
}
}5.5 Business Exception i18n
public class BizException extends RuntimeException {
private final String code;
private final Object[] args;
public BizException(String code, Object... args) {
this.code = code;
this.args = args;
}
// getters
}
@RestControllerAdvice
public class GlobalExceptionHandler {
private final MessageSource messageSource;
@ExceptionHandler(BizException.class)
public Result handle(BizException e, Locale locale) {
String msg = messageSource.getMessage(e.getCode(), e.getArgs(), locale);
return Result.fail(msg);
}
}5.6 Multiple Resource Bundle Configuration
Split multiple basenames by module:
spring:
messages:
basename: messages,validation,messages_payInternationalization, MessageSource, Locale resolution are common topics in backend multi-language systems and mid-to-senior interviews. Understanding message resource loading and Locale chain enables transfer to environment property binding, validation message resolution, exception info encapsulation, cross-region architecture, and precise troubleshooting of "copy not found", "language not switching", "Chinese garbled" issues.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
