Spring Boot로 국제화(i18n)와 다국어 지원 구현
Spring Boot에서 국제화의 기본 개념부터 MessageSource 구성, LocaleResolver 설정과 뷰·컨트롤러 연동까지 실제 적용에 적합한 설정
목차
개요
웹 애플리케이션을 여러 언어로 제공하면 사용자 경험이 크게 개선된다. Spring Boot는 i18n 기능을 간편하게 제공하며, 적절한 설정만으로 다국어 메시지와 지역화된 포맷을 처리할 수 있다. 이 글에서는 spring boot i18n 설정의 핵심 요소를 단계별로 설명한다.
핵심 개념 정리
MessageSource
다국어 문자열을 관리하는 중앙 저장소다. 메시지 키와 각 언어별 메시지 파일을 연결한다. spring boot 다국어 메시지 관리의 출발점이다.
Locale 및 LocaleResolver
Locale은 사용자 지역·언어 정보를 나타낸다. locale resolver spring boot 설정은 요청에서 Locale을 결정하는 전략을 정의한다. 쿠키, 세션, 요청 파라미터 등 다양한 방법으로 Locale을 결정할 수 있다.
프로젝트에 필요한 파일 구성
일반적으로 src/main/resources에 메시지 파일을 둔다.
- messages.properties (기본 메시지)
- messages_ko.properties (한국어)
- messages_en.properties (영어)
예시: messages.properties
greeting=Hello
error.notfound=Resource not found예시: messages_ko.properties
greeting=안녕하세요
error.notfound=자원을 찾을 수 없습니다Spring Boot 설정 코드
MessageSource와 LocaleResolver, LocaleChangeInterceptor를 설정하면 대부분의 요구사항을 충족한다.
package com.example.config;
import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ReloadableResourceBundleMessageSource;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;
@Configuration
public class I18nConfig implements WebMvcConfigurer {
@Bean
public MessageSource messageSource() {
ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
messageSource.setBasename("classpath:messages");
messageSource.setDefaultEncoding("UTF-8");
return messageSource;
}
@Bean
public LocaleResolver localeResolver() {
CookieLocaleResolver resolver = new CookieLocaleResolver();
resolver.setDefaultLocale(java.util.Locale.KOREAN);
resolver.setCookieName("LOCALE");
resolver.setCookieMaxAge(3600);
return resolver;
}
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("lang");
return interceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(localeChangeInterceptor());
}
}컨트롤러에서 메시지 사용
컨트롤러에서 MessageSource와 Locale을 주입받아 메시지를 조회할 수 있다. 이 방식은 API 응답이나 서버 사이드 렌더링 메시지를 지역화할 때 유용하다.
package com.example.controller;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletRequest;
import java.util.Locale;
@RestController
public class HomeController {
@Autowired
private MessageSource messageSource;
@GetMapping("/greet")
public String greet(HttpServletRequest request) {
Locale locale = request.getLocale();
return messageSource.getMessage("greeting", null, locale);
}
}
뷰 템플릿(Thymeleaf)에서의 사용
Thymeleaf는 Spring MessageSource와 통합되어 있다. 표현식에서 메시지 키를 사용하면 자동으로 지역화된 문자열을 출력한다.
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" lang="ko">
<body>
<h1 th:text="#{greeting}">Greeting</h1>
</body>
</html>요청에서 언어 변경 처리
localeChangeInterceptor를 사용하면 쿼리 파라미터로 언어를 변경할 수 있다. 예: /page?lang=en
- 쿠키 사용 시 사용자 환경에 언어 설정을 저장
- 세션 사용 시 로그인 기반 언어 유지
- 파라미터 사용 시 즉시 전환
운영에서 고려할 점
- 메시지 파일 인코딩을 UTF-8로 유지
- 키 네이밍은 일관성 있게 관리
- 동적 수정이 필요하면 ReloadableResourceBundleMessageSource의 캐시 설정 조정
- 기본 Locale과 예외 처리 메시지를 명확히 정함
정리
이 글에서는 spring boot i18n 설정의 핵심인 MessageSource 구성, locale resolver spring boot 설정, 그리고 컨트롤러와 뷰에서의 다국어 연동 방법을 다뤘다. 처음 적용할 때는 messages 파일 구조와 Locale 결정 방식부터 정리한 뒤, 단계적으로 인터셉터와 쿠키·세션 전략을 선택하면 운영에 유연한 다국어 지원을 만들 수 있다.