기술과 산업/언어 및 프레임워크

Spring Boot 시리즈 27편 – 다국어(i18n) 지원 전략: 메시지 번들, 리소스 자동 로딩, 언어 감지까지

B컷개발자 2025. 5. 7. 00:16
728x90
Spring Boot에서 다국어(i18n) 지원을 위한 메시지 번들 구성, 언어 자동 감지, 동적 언어 전환 방법을 설명합니다. 글로벌 서비스 대응을 위한 실전 전략을 제시합니다.

 

 

Spring Boot 시리즈 27편 – 다국어(i18n) 지원 전략: 메시지 번들, 리소스 자동 로딩, 언어 감지까지

 

전 세계를 대상으로 서비스하는 SaaS나 앱은 더 이상 예외적인 사례가 아닙니다.

한국어 외에도 영어, 일본어, 스페인어 등 다국어 지원은 기획 단계에서 반드시 고려해야 하는 필수 기능입니다.

 

Spring Boot는 기본적으로 i18n(Internationalization) 기능을 내장하고 있으며,

적절한 설정과 구조만 갖춘다면 유연하게 글로벌 사용자에게 맞춤 언어를 제공할 수 있습니다.

 

이번 글에서는 Spring Boot 기반 프로젝트에서

 

  • 메시지 리소스 설정
  • 언어 선택 및 감지 방법
  • 동적 언어 전환 방법
  • 을 실무 중심으로 설명합니다.

 

 

📌 1. i18n 기본 개념과 흐름

 

Spring Boot의 i18n 처리 흐름은 다음과 같습니다.

[1] 사용자의 Accept-Language 또는 수동 선택
      ↓
[2] MessageSource가 언어에 맞는 properties 파일 탐색
      ↓
[3] 컨트롤러/템플릿/에러 메시지에 번역 결과 반영

 

 

 

✅ 2. 메시지 번들 구성하기

 

 

1️⃣ 기본 폴더 구조

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

 

 

 

2️⃣ application.yml 설정

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

 

  • basename에 다국어 메시지 파일 접두어 설정
  • Locale에 따라 자동으로 해당 언어 리소스 로드됨

 

 

3️⃣ 메시지 번들 예시

 

messages.properties (기본)

greeting=Welcome!

messages_ko.properties

greeting=환영합니다!

messages_ja.properties

greeting=ようこそ!

 

 

 

🛠️ 3. 컨트롤러에서 다국어 메시지 사용

@RestController
@RequiredArgsConstructor
public class GreetingController {

    private final MessageSource messageSource;

    @GetMapping("/greet")
    public String greet(Locale locale) {
        return messageSource.getMessage("greeting", null, locale);
    }
}

 

  • Locale은 HTTP Header의 Accept-Language를 기준으로 자동 주입됨
  • 영어 브라우저로 요청 시 Welcome!, 일본어는 ようこそ!

 

 

🌐 4. 언어 감지 및 수동 전환 전략

 

 

1️⃣ Accept-Language 기반 자동 감지

GET /greet
Accept-Language: en-US

Spring Boot는 기본적으로 Header 기반 LocaleResolver를 사용

 

 

2️⃣ Cookie 기반 수동 전환

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

→ 사용자가 언어 선택 시 쿠키에 저장 가능

예: locale=ja → 이후부터 일본어 메시지 사용

 

 

3️⃣ 웹 기반 언어 선택 처리 (링크 기반)

<a href="?lang=ko">한국어</a>
<a href="?lang=en">English</a>
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
    LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
    interceptor.setParamName("lang");
    return interceptor;
}

→ /greet?lang=ja 요청 시 일본어로 동적 변경

 

 

🧠 실무 설계 팁

항목전략

파일 위치 src/main/resources/messages_*.properties 유지
기본 언어 messages.properties는 항상 영어 또는 디폴트 언어
신규 번역 대응 키 기반 정렬, 버전 관리 Git으로 추적
관리자 도구 i18n 관리 툴(PoEditor, Crowdin 등) 연계 추천
미번역 대응 defaultMessage 파라미터 지정 or 로그 경고 출력

 

 

 

✅ 마무리 요약

항목요약

메시지 파일 언어별 .properties 파일로 분리 관리
자동 감지 Accept-Language 기반 Locale 자동 선택
수동 전환 Cookie, URL 파라미터 기반 언어 변경 처리 가능
실무 팁 번역 키 관리 일관성 유지 + 자동화 도구 연계
확장 전략 외부 CMS, DB 기반 번역 로딩으로 확장 가능

 

 

 

📌 다음 편 예고

 

Spring Boot 시리즈 28편: 예외 처리 전략 – @ControllerAdvice, 커스텀 예외, 에러 응답 표준화

728x90