2025-04-08T19:56:24

docs/i18n.md

@@ -0,0 +1,105 @@
+스프링부트에서 국제화(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`에서 커스터마이징할 수 있습니다:
+```properties
+spring.messages.basename=messages
+spring.messages.encoding=UTF-8
+```
+- `spring.messages.basename`: 메시지 파일의 기본 이름 (디렉토리 경로 없이).
+- `spring.messages.encoding`: 파일 인코딩 설정.
+
+#### (4) **로케일 설정**
+스프링부트는 사용자의 요청 헤더(`Accept-Language`)를 기반으로 로케일을 자동 감지합니다. 필요 시 `LocaleResolver`를 커스터마이징할 수 있습니다. 예를 들어, 세션 기반 로케일을 사용하려면:
+```java
+@Bean
+public LocaleResolver localeResolver() {
+    SessionLocaleResolver slr = new SessionLocaleResolver();
+    slr.setDefaultLocale(Locale.KOREAN); // 기본 로케일 설정
+    return slr;
+}
+```
+
+#### (5) **컨트롤러에서 사용**
+컨트롤러에서 `MessageSource`를 주입받아 메시지를 가져올 수 있습니다:
+```java
+@Autowired
+private MessageSource messageSource;
+
+@GetMapping("/greet")
+public String greet(Locale locale) {
+    String greeting = messageSource.getMessage("greeting", new Object[]{"사용자"}, locale);
+    return greeting;
+}
+```
+위 코드는 로케일에 따라 적절한 메시지를 반환합니다.
+
+#### (6) **Thymeleaf와 같은 템플릿 엔진에서 사용**
+Thymeleaf를 사용할 경우, 템플릿에서 직접 메시지를 참조할 수 있습니다:
+```html
+<p th:text="#{greeting('사용자')}"></p>
+```
+`#{key}`는 메시지 파일에서 해당 키를 찾아 로케일에 맞는 값을 렌더링합니다.
+
+### 3. **추가 기능**
+- **파라미터 전달**: 메시지에 동적 값을 삽입하려면 `{0}`, `{1}` 같은 플레이스홀더를 사용합니다.
+- **로케일 변경**: `LocaleChangeInterceptor`를 추가해 URL 파라미터(예: `?lang=ko`)로 로케일을 동적으로 변경할 수 있습니다:
+```java
+@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 문자가 깨질 수 있으니 주의하세요.
+
+스프링부트의 국제화는 이렇게 간단하면서도 강력하게 다국어 지원을 가능하게 합니다. 추가로 궁금한 점이 있으면 말씀해주세요!