스프링 부트 3에서 다국어 지원 구현

 

스프링 부트 3는 개발자들이 보다 쉽게 국제화(i18n, Internationalization)를 구현할 수 있도록 다양한 기능을 제공합니다. 다국어 지원은 웹 애플리케이션에서 사용자의 언어 및 문화권에 맞는 콘텐츠를 제공하기 위해 필수적인 요소입니다. 이번 글에서는 스프링 부트 3를 활용한 다국어 지원 구현 방법을 상세히 알아보고, 실무에 바로 적용할 수 있도록 3가지 예제를 포함해 설명하겠습니다.

---

1. 다국어 지원의 기본 개념과 필요성

다국어 지원은 애플리케이션이 여러 언어로 콘텐츠를 표시할 수 있도록 설계하는 작업을 의미합니다. 이를 위해 메시지 번들이라는 개념이 사용되며, 스프링 부트에서는 기본적으로 .properties 파일 형식으로 다국어 메시지를 관리합니다.

다국어 지원의 주요 장점:

1. 글로벌 사용자 경험 향상
   사용자가 자신의 언어로 서비스를 이용할 수 있으므로 접근성이 향상됩니다.
2. 시장 확대 가능성
   다국어 지원은 글로벌 사용자 기반을 확보하는 데 기여합니다.
3. 유지보수 용이성
   모든 언어 데이터를 별도의 파일로 관리하여 코드 변경 없이 쉽게 업데이트할 수 있습니다.

---

2. 스프링 부트 3의 다국어 지원 구성 단계

스프링 부트에서 다국어 지원을 구현하기 위해 다음의 단계를 거칩니다.

(1) 의존성 추가

spring-boot-starter-web은 다국어 지원에 필요한 기능을 포함하고 있습니다. Gradle 또는 Maven에 다음과 같이 의존성을 추가합니다.

Gradle

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

Maven

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

---

(2) 메시지 번들 파일 생성

메시지 번들 파일은 src/main/resources 디렉토리 하위에 생성하며, 언어별로 파일 이름을 지정합니다. 기본적으로 messages.properties 파일을 사용하고, 각 언어에 맞는 파일명을 추가합니다.

예시: 메시지 파일 생성

• messages.properties (기본 언어, 영어)

  greeting=Hello
  farewell=Goodbye
  

• messages_ko.properties (한국어)

  greeting=안녕하세요
  farewell=안녕히 가세요
  

• messages_es.properties (스페인어)

  greeting=Hola
  farewell=Adiós
  

---

(3) MessageSource Bean 등록

스프링 부트 3에서는 MessageSource를 통해 메시지 번들을 관리합니다. @Configuration 클래스를 작성하여 메시지 소스를 정의합니다.

import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ResourceBundleMessageSource;

@Configuration
public class MessageConfig {

    @Bean
    public MessageSource messageSource() {
        ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
        messageSource.setBasename("messages"); // 메시지 파일 이름
        messageSource.setDefaultEncoding("UTF-8"); // 인코딩 설정
        return messageSource;
    }
}

---

(4) 클라이언트의 언어 설정 감지

스프링은 LocaleResolver를 사용하여 클라이언트의 언어를 감지합니다. 일반적으로 Accept-Language 헤더를 기반으로 자동 감지가 이루어지며, 필요시 특정 언어를 강제로 설정할 수도 있습니다.

LocaleResolver 설정 예시

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver;

import java.util.Locale;

@Configuration
public class LocaleConfig {

    @Bean
    public LocaleResolver localeResolver() {
        AcceptHeaderLocaleResolver localeResolver = new AcceptHeaderLocaleResolver();
        localeResolver.setDefaultLocale(Locale.ENGLISH); // 기본 언어 설정
        return localeResolver;
    }
}

---

(5) 컨트롤러에서 메시지 사용

컨트롤러에서는 MessageSource를 주입받아 특정 키에 해당하는 메시지를 가져올 수 있습니다.

컨트롤러 예시

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.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

import java.util.Locale;

@RestController
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);
    }
}

---

3. 실무에서의 적용 예제

예제 1: 다국어 환영 메시지 출력

1. URL: http://localhost:8080/greet
2. 헤더: Accept-Language에 따라 메시지가 결정됩니다.
   • en: Hello
   • ko: 안녕하세요
   • es: Hola

---

예제 2: 특정 언어 강제 설정

LocaleContextHolder를 사용하여 특정 언어로 강제 설정할 수 있습니다.

import org.springframework.context.i18n.LocaleContextHolder;

public String getKoreanGreeting() {
    Locale koreanLocale = Locale.KOREAN;
    LocaleContextHolder.setLocale(koreanLocale);
    return messageSource.getMessage("greeting", null, koreanLocale);
}

---

예제 3: UI에서 언어 선택 기능 제공

다국어 지원은 프론트엔드와도 통합될 수 있습니다. 예를 들어, React 또는 Vue.js와 같은 프레임워크에서 사용자가 언어를 선택하면, 선택된 언어를 Accept-Language 헤더에 포함하여 백엔드로 요청을 보냅니다.

---

4. 다국어 지원 구현 시 유의사항

1. 메시지 키 관리
   키는 간결하고 직관적으로 작성해야 하며, 주석을 활용해 각 키의 용도를 기록하는 것이 좋습니다.
2. UTF-8 인코딩 확인
   메시지 파일의 인코딩을 항상 UTF-8로 설정해야 글자 깨짐을 방지할 수 있습니다.
3. 기본 언어 제공
   기본 언어를 설정해 사용자의 언어 감지가 실패할 경우에도 서비스가 제공되도록 해야 합니다.

---

결론

스프링 부트 3를 사용하면 다국어 지원을 간편하게 구현할 수 있습니다. 위에서 설명한 단계를 따라가며 기본적인 메시지 파일 구성부터 클라이언트의 언어 감지까지 모두 설정해 보세요. 이를 통해 글로벌 사용자들에게 더욱 매력적인 애플리케이션을 제공할 수 있을 것입니다.