How to Implement i18n Internationalization in Spring Boot APIs

In a new Spring Boot project that provides API endpoints, you often need to support multiple languages. This article explains how to enable i18n (internationalization) in Spring Boot, focusing on backend configuration and usage.

Dependency

The standard spring-boot-starter-web starter already includes the necessary components. Add the following Maven dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.2.2.RELEASE</version>
</dependency>

Project Structure

The project is a typical front‑back separation API. The backend needs locale configuration and a way to retrieve messages by key.

Locale Resolver Configuration

Define a @Configuration class that creates a SessionLocaleResolver with a default locale (Chinese).

@Configuration
public class LocaleConfig {
    @Bean
    public LocaleResolver localeResolver() {
        SessionLocaleResolver localeResolver = new SessionLocaleResolver();
        localeResolver.setDefaultLocale(Locale.CHINA);
        return localeResolver;
    }
}

Interceptor Configuration

Register a LocaleChangeInterceptor to read the language parameter (e.g., ?lang=zh_CN) from request URLs.

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        LocaleChangeInterceptor localeInterceptor = new LocaleChangeInterceptor();
        localeInterceptor.setParamName("lang");
        registry.addInterceptor(localeInterceptor);
    }
}

Message Files

Create messages.properties (default, can be empty) and locale‑specific files such as messages_en_US.properties, messages_zh_CN.properties, and messages_zh_TW.properties under src/main/resources. Example content:

username=zhangsan
username=张三
username=張三

If you prefer a custom directory, set the base name in application.properties:

spring.messages.basename=statistics/i18n/messages

Utility Class

A helper component injects MessageSource and provides a static method to fetch a message by key.

@Component
public class MessageUtils {
    private static MessageSource messageSource;
    public MessageUtils(MessageSource messageSource) {
        MessageUtils.messageSource = messageSource;
    }
    public static String get(String msgKey) {
        try {
            return messageSource.getMessage(msgKey, null, LocaleContextHolder.getLocale());
        } catch (Exception e) {
            return msgKey;
        }
    }
}

Using the Utility in a Controller

Expose an endpoint that returns the localized value for a given key.

@RestController
@RequestMapping("/i18n")
public class I18nController {
    @RequestMapping("/user")
    public String getUserName() {
        return MessageUtils.get("username");
    }
}

Calling http://localhost:8080/i18n/user?lang=zh_TW returns 張三, confirming that i18n works.

For further reference, the source code can be obtained by following the original WeChat public account instructions.