41 lines
2.1 KiB
Markdown
41 lines
2.1 KiB
Markdown
# 2026-03-27: 다국어 지원(i18n) 구현
|
|
|
|
## 개요
|
|
Kord 봇의 모든 사용자 표시 텍스트를 다국어로 제공하는 i18n 시스템을 구현했습니다.
|
|
|
|
## 변경된 파일
|
|
|
|
### 신규 생성
|
|
| 파일 | 설명 |
|
|
|------|------|
|
|
| `src/i18n/types.ts` | `I18nProvider` 인터페이스, `TranslationSchema`, `SupportedLocale` 타입 정의 |
|
|
| `src/i18n/index.ts` | `t()` 번역 함수, `resolveLocale()`, `StaticI18nProvider`, `setI18nProvider()` |
|
|
| `src/i18n/locales/en.ts` | 영어 번역 (전체 키 — 에러, 음성채널, 명령어, 모달, 셀렉트 메뉴) |
|
|
| `src/i18n/locales/ko.ts` | 한국어 번역 |
|
|
| `src/i18n/localeHelper.ts` | `getInteractionLocale()`, `getContextLocale()` 헬퍼 |
|
|
| `src/commands/language.ts` | `/language` 슬래시 명령어 (user/server scope) |
|
|
| `tests/i18n/i18n.test.ts` | i18n 유닛 테스트 (14 tests) |
|
|
|
|
### 수정
|
|
| 파일 | 변경 내용 |
|
|
|------|-----------|
|
|
| `src/errors/BotError.ts` | `userMessage`/`resolution` → `messageKey` (i18n 키) |
|
|
| `src/errors/ErrorCodes.ts` | `BotError` 인스턴스 → `ErrorDef` 경량 정의 객체 |
|
|
| `src/errors/ErrorReporter.ts` | `locale` 파라미터 추가, `t()` 함수로 메시지 해석 |
|
|
| `src/events/interactionCreate.ts` | 모든 하드코딩 문자열 → `t(locale, key, vars)` |
|
|
| `src/services/VoiceService.ts` | 컨트롤 패널, 채널명, 응답 → `t()` 사용 |
|
|
| `src/commands/voiceSetup.ts` | 응답 + `setDescriptionLocalizations()` 적용 |
|
|
| `prisma/schema.prisma` | `GuildConfig.locale` 추가, `UserLocale` 모델 신설 |
|
|
|
|
## 아키텍처 결정
|
|
|
|
1. **I18nProvider 인터페이스**: `setI18nProvider()`로 런타임에 번역 백엔드 교체 가능
|
|
2. **TypeScript 객체 기반 번역**: 타입 안전성 + IDE 자동완성 활용
|
|
3. **Locale 우선순위**: 사용자 DB → 서버 DB → Discord Auto-detect → 영어 fallback
|
|
4. **서버 로그는 영어 고정**: 개발자/운영자 전용
|
|
|
|
## 검증 결과
|
|
- **TypeScript 빌드**: 성공 (0 errors)
|
|
- **테스트**: 6 suites, 39 tests 전체 통과
|
|
- **DB 마이그레이션**: `add-i18n-locale-support` 완료
|