Skip to content
Spring Boot i18n Internals: MessageSource, LocaleResolver & Source Code Flow

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.

Java Tech Workshop
Java Tech Workshop
Java Tech Workshop

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 copy

2. 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: Chinese

Lookup 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 NoSuchMessageException

2.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 found

Call with argument array, filled in {0}, {1} order.

2.5 Spring Boot Auto-Configuration

MessageSourceAutoConfiguration

assembles MessageSource via spring.messages.*:

spring:
  messages:
    basename: messages
    encoding: UTF-8
    cache-duration: 3600000
    fallback-to-system-locale: true
    use-code-as-default-message: false

2.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 / exception

4.2 Message Lookup Source Code Perspective

ResourceBundleMessageSource

uses 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

@Validated

validation 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 found

5.2 YML Configuration

spring:
  messages:
    basename: messages
    encoding: UTF-8
    fallback-to-system-locale: true

5.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_pay

Internationalization, 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.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

spring-bootspring-mvci18ninternationalizationmessagesourcelocalechangeinterceptorlocaleresolverresourcebundle
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.