spring-boot-examples/docs/i18n.md at main

Files

Elex eef061c1c9 2025-04-08T19:56:24

2025-04-08 19:56:24 +09:00

4.7 KiB

Raw Permalink Blame History

스프링부트에서 국제화(Internationalization, i18n)는 애플리케이션이 여러 언어와 지역 설정을 지원할 수 있도록 하는 기능입니다. 이를 통해 사용자의 언어 환경에 맞춰 메시지, 날짜, 숫자 형식 등을 동적으로 제공할 수 있습니다. 스프링부트는 이를 쉽게 구현할 수 있도록 MessageSource와 같은 기능을 제공합니다. 아래에서 주요 개념과 설정 방법을 설명하겠습니다.

1. 국제화의 기본 개념

국제화는 주로 메시지 파일을 통해 구현됩니다. 메시지 파일은 언어별로 번역된 텍스트를 키-값 쌍으로 저장하며, 사용자의 로케일(Locale)에 따라 적절한 메시지를 불러옵니다. 예를 들어:

messages.properties: 기본 메시지 (영어 등)
messages_ko.properties: 한국어 메시지
messages_en.properties: 영어 메시지

2. 스프링부트에서 국제화 설정

스프링부트에서 국제화를 설정하는 기본 단계는 다음과 같습니다.

(1) 의존성 확인

스프링부트 프로젝트라면 별도의 의존성 추가 없이 spring-boot-starter에 포함된 기능을 사용할 수 있습니다.

(2) 메시지 파일 생성

프로젝트의 src/main/resources 디렉토리에 메시지 파일을 추가합니다. 예시:

messages.properties:
```
greeting=Hello, {0}!
```
messages_ko.properties:
```
greeting=안녕하세요, {0}님!
```
messages_en.properties:
```
greeting=Hello, {0}!
```

파일 이름은 messages_[언어코드].properties 형식을 따르며, 언어 코드는 ISO 639-1 표준(예: ko, en, fr)을 사용합니다.

(3) MessageSource 설정

스프링부트는 기본적으로 MessageSource 빈을 자동으로 설정합니다. 필요 시 application.properties에서 커스터마이징할 수 있습니다:

spring.messages.basename=messages
spring.messages.encoding=UTF-8

spring.messages.basename: 메시지 파일의 기본 이름 (디렉토리 경로 없이).
spring.messages.encoding: 파일 인코딩 설정.

(4) 로케일 설정

스프링부트는 사용자의 요청 헤더(Accept-Language)를 기반으로 로케일을 자동 감지합니다. 필요 시 LocaleResolver를 커스터마이징할 수 있습니다. 예를 들어, 세션 기반 로케일을 사용하려면:

@Bean
public LocaleResolver localeResolver() {
    SessionLocaleResolver slr = new SessionLocaleResolver();
    slr.setDefaultLocale(Locale.KOREAN); // 기본 로케일 설정
    return slr;
}

(5) 컨트롤러에서 사용

컨트롤러에서 MessageSource를 주입받아 메시지를 가져올 수 있습니다:

@Autowired
private MessageSource messageSource;

@GetMapping("/greet")
public String greet(Locale locale) {
    String greeting = messageSource.getMessage("greeting", new Object[]{"사용자"}, locale);
    return greeting;
}

위 코드는 로케일에 따라 적절한 메시지를 반환합니다.

(6) Thymeleaf와 같은 템플릿 엔진에서 사용

Thymeleaf를 사용할 경우, 템플릿에서 직접 메시지를 참조할 수 있습니다:

<p th:text="#{greeting('사용자')}"></p>

#{key}는 메시지 파일에서 해당 키를 찾아 로케일에 맞는 값을 렌더링합니다.

3. 추가 기능

파라미터 전달: 메시지에 동적 값을 삽입하려면 {0}, {1} 같은 플레이스홀더를 사용합니다.
로케일 변경: LocaleChangeInterceptor를 추가해 URL 파라미터(예: ?lang=ko)로 로케일을 동적으로 변경할 수 있습니다:

@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
    LocaleChangeInterceptor lci = new LocaleChangeInterceptor();
    lci.setParamName("lang");
    return lci;
}

@Bean
public WebMvcConfigurer webMvcConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
            registry.addInterceptor(localeChangeInterceptor());
        }
    };
}

4. 실행 예시

요청: GET /greet (Accept-Language: ko)
- 응답: "안녕하세요, 사용자님!"
요청: GET /greet (Accept-Language: en)
- 응답: "Hello, 사용자!"

5. 주의점

메시지 파일이 없거나 키가 누락된 경우, 기본 메시지 파일(messages.properties)을 참조하거나 예외가 발생할 수 있습니다.
UTF-8 인코딩을 명시적으로 설정하지 않으면 한글 등 비ASCII 문자가 깨질 수 있으니 주의하세요.

스프링부트의 국제화는 이렇게 간단하면서도 강력하게 다국어 지원을 가능하게 합니다. 추가로 궁금한 점이 있으면 말씀해주세요!

4.7 KiB Raw Permalink Blame History