[JAVA] Spring Boot에서 국제화(i18n) 적용하기 – 다국어 지원 가이드

서비스 대상이 국내를 넘어 글로벌 사용자라면, 국제화(i18n)는 필수 요소입니다. Spring Boot는 Locale에 따라 다국어 메시지를 자동으로 적용할 수 있는 기능을 기본 제공하며, 설정도 비교적 간단한 편입니다.

이 글에서는 Spring Boot 애플리케이션에 i18n(Internationalization)을 적용하는 방법을 단계별로 정리하고, 실무에서 고려할 사항도 함께 다룹니다.

 

1. 국제화(i18n)란?

Internationalization은 사용자 언어나 지역 설정에 따라 UI를 다르게 표시하는 기술입니다. 보통 메시지, 날짜/시간, 화폐 등의 표현을 해당 Locale 기준에 맞춰 처리합니다.

Spring Boot는 다음 요소들을 통해 i18n을 지원합니다:

• MessageSource: 다국어 메시지를 읽어오는 Bean
• LocaleResolver: 현재 요청의 Locale을 결정
• messages_xx.properties: 다국어 리소스 파일

 

2. message.properties 파일 생성

src/main/resources 경로에 다국어 메시지를 정의합니다.

📁 src/main/resources/
 ├── messages.properties           (기본: 한국어)
 ├── messages_en.properties        (영어)
 └── messages_ja.properties        (일본어)

messages.properties

greeting=안녕하세요

messages_en.properties

greeting=Hello

messages_ja.properties

greeting=こんにちは

 

3. application.yml 설정

spring:
  messages:
    basename: messages
    encoding: UTF-8

기본 경로는 classpath:messages이며 확장자 없이 설정합니다. UTF-8 인코딩을 명시하지 않으면 한글이 깨질 수 있습니다.

 

4. LocaleResolver Bean 등록

Locale을 어떤 기준으로 판단할지 설정해야 합니다. 가장 많이 사용하는 건 Accept-Language 헤더 기반의 설정입니다.

@Configuration
public class LocaleConfig {

    @Bean
    public LocaleResolver localeResolver() {
        AcceptHeaderLocaleResolver resolver = new AcceptHeaderLocaleResolver();
        resolver.setDefaultLocale(Locale.KOREA);
        return resolver;
    }

    @Bean
    public MessageSource messageSource() {
        ReloadableResourceBundleMessageSource source = new ReloadableResourceBundleMessageSource();
        source.setBasename("classpath:messages");
        source.setDefaultEncoding("UTF-8");
        return source;
    }
}

 

5. 컨트롤러에서 메시지 사용하기

MessageSource를 주입받아 사용합니다.

@RestController
@RequestMapping("/api")
public class GreetingController {

    @Autowired
    private MessageSource messageSource;

    @GetMapping("/greet")
    public String greet(@RequestHeader(name = "Accept-Language", required = false) Locale locale) {
        return messageSource.getMessage("greeting", null, locale);
    }
}

 

6. 테스트 예시

curl 또는 Postman 테스트

curl -H "Accept-Language: en" http://localhost:8080/api/greet
# 결과: Hello

curl -H "Accept-Language: ja" http://localhost:8080/api/greet
# 결과: こんにちは

curl -H "Accept-Language: ko" http://localhost:8080/api/greet
# 결과: 안녕하세요

 

7. 실무 팁

• 다국어 메시지 키는 명확하게 정리 – 중복 키나 의미 불명확한 키는 유지보수 어려움
• message.properties는 IDE에서 지원되는 plugin 활용 – IntelliJ 기준 Resource Bundle 기능 활용 추천
• Locale 선택 UI 제공 – 브라우저 자동 설정 외에도 사용자가 언어를 직접 선택할 수 있도록 구현하는 것이 UX 측면에서 좋음

 

결론

국제화는 더 이상 선택이 아닌 기본입니다. Spring Boot의 i18n 기능은 비교적 직관적으로 구성할 수 있으며, 컨트롤러, 예외 메시지, Validation 메시지까지 다양하게 활용 가능합니다.