# Kord - 다국어 지원 기획 (i18n / Internationalization)

## 체인지로그 (Changelog)
- **2026-03-27**: 최초 기획서 작성

---

## 1. 개요

Kord 봇의 모든 **사용자 표시 텍스트**(명령어 응답, 에러 메시지, UI 라벨, 컨트롤 패널 등)를 다국어로 제공하는 시스템입니다.

### 현재 문제 (As-Is)

| 문제 | 위치 |
|------|------|
| 모든 사용자 메시지가 영어로 하드코딩 | `ErrorCodes.ts`, `interactionCreate.ts`, `VoiceService.ts`, `voiceSetup.ts` |
| Discord `interaction.locale` 미활용 | discord.js가 제공하는 사용자/서버 locale 정보를 무시 |
| 에러 메시지 키-값 구조 미비 | `ErrorCodes.ts`에 문자열 직접 포함 |
| 서버/사용자별 언어 설정 불가 | DB에 locale 필드 없음 |

### 목표 (To-Be)

- **Locale 키-값 구조** 기반 모든 사용자 문자열 관리
- **서버(Guild) → 사용자(User)** 우선순위 기반 언어 결정
- **discord.js `interaction.locale` / `guildLocale`** 활용한 자동 감지
- **에러 시스템(ErrorCodes)** 과 자연스러운 통합
- 영어(en) fallback + **한국어(ko)** 우선 지원

---

## 2. 언어 결정 우선순위 (Locale Resolution)

사용자에게 표시할 언어는 다음 우선순위로 결정합니다:

```
1. 사용자 개인 설정 (DB: UserLocale.locale)      ← 최우선
2. 서버 설정 (DB: GuildConfig.locale)              ← 2순위
3. Discord interaction.locale                      ← 3순위 (자동 감지)
4. 기본 언어: 'en' (English)                       ← fallback
```

> [!NOTE]
> Discord의 `interaction.locale`은 사용자의 Discord 클라이언트 언어를 자동으로 감지하므로,
> DB에 별도 설정이 없어도 적절한 언어가 자동 선택됩니다.

### 지원 언어 (초기)

| 코드 | 언어 |
|------|------|
| `en` | English (기본, fallback) |
| `ko` | 한국어 |

향후 `ja`, `zh-CN` 등 추가 가능. 번역 파일만 추가하면 자동 인식.

---

## 3. 번역 파일 구조 (Translation Files)

### 3-1. 디렉터리 구조

```
src/
├── i18n/
│   ├── index.ts              ← t() 함수, resolveLocale() 등 핵심 모듈
│   ├── types.ts              ← 타입 정의 (TranslationKeys, Locale 등)
│   └── locales/
│       ├── en.ts             ← 영어 번역 (기본, 전체 키 포함)
│       └── ko.ts             ← 한국어 번역
```

### 3-2. 번역 파일 형태 (TypeScript Object)

JSON/YAML 대신 **TypeScript 객체**를 사용합니다.  
이유: 타입 안전성, IDE 자동완성, 빌드 타임 검증 가능.

```typescript
// src/i18n/locales/en.ts
export const en = {
  // ── 에러 메시지 (Error Messages) ──
  errors: {
    E1001: {
      userMessage: 'The user limit value is invalid.',
      resolution: 'Please enter a number between 0 and 99. (0 = unlimited)',
    },
    E2001: {
      userMessage: 'The bot does not have sufficient permissions to manage channels.',
      resolution: 'Please ask a server administrator to grant the bot "Manage Channels" permission.',
    },
    // ... 모든 ErrorCodes의 userMessage/resolution
  },

  // ── 에러 카테고리 타이틀 ──
  errorTitles: {
    USER_INPUT: 'Please check your input',
    PERMISSION: 'Insufficient permissions',
    BOT_INTERNAL: 'Something went wrong',
    DISCORD_API: 'Temporary issue',
  },

  // ── 에러 Embed 필드명 ──
  errorFields: {
    resolution: '💡 How to resolve',
  },

  // ── 음성 채널 (Voice Channel) ──
  voice: {
    channelReady: '{{owner}}, your temporary channel is ready! Use the dropdown menu below to manage it.',
    defaultRoomName: "{{username}}'s Room",
    controlPanel: {
      placeholder: '⚙️ Manage Channel Settings',
      rename: 'Rename Channel',
      limit: 'Set User Limit',
      lock: 'Lock / Unlock',
      kick: 'Kick User',
      ban: 'Ban / Hide User',
      transfer: 'Transfer Ownership',
    },
    // 인터랙션 응답
    responses: {
      channelLocked: 'Channel Locked! Only you and invited members can join.',
      channelUnlocked: 'Channel Unlocked! Anyone can join now.',
      channelRenamed: 'Channel renamed to **{{name}}**!',
      limitSet: 'Channel limit set to **{{limit}}**!',
      limitUnlimited: 'Unlimited',
      kicked: 'Kicked {{user}} from the channel.',
      banned: 'Banned and hidden channel from {{user}}.',
      transferPrompt: 'Select who will become the new owner of this channel.',
      transferDone: 'Ownership successfully transferred to {{user}}.',
      banPrompt: 'Banning will make the channel invisible to them.',
    },
  },

  // ── 명령어 (Commands) ──
  commands: {
    voiceSetup: {
      setSuccess: 'Successfully set up {{channel}} as a Voice Generator Channel!',
      createSuccess: 'Successfully created and set up {{channel}} as a Voice Generator Channel!',
    },
  },

  // ── 모달 (Modals) ──
  modals: {
    renameTitle: 'Rename Voice Channel',
    renameLabel: 'New Channel Name',
    limitTitle: 'Set User Limit',
    limitLabel: 'User Limit (0 for unlimited, 1-99)',
  },

  // ── 셀렉트 메뉴 Placeholder ──
  selects: {
    kickUser: 'Select a user to kick',
    banUser: 'Select a user to ban/hide',
    transferOwner: 'Select a user to transfer ownership to',
  },
} as const;
```

```typescript
// src/i18n/locales/ko.ts
export const ko = {
  errors: {
    E1001: {
      userMessage: '사용자 제한 값이 올바르지 않습니다.',
      resolution: '0에서 99 사이의 숫자를 입력해주세요. (0 = 무제한)',
    },
    E2001: {
      userMessage: '봇에 채널을 관리할 권한이 부족합니다.',
      resolution: '서버 관리자에게 봇의 "채널 관리" 권한을 확인해달라고 요청하세요.',
    },
    // ...
  },
  errorTitles: {
    USER_INPUT: '입력을 확인해주세요',
    PERMISSION: '권한이 부족합니다',
    BOT_INTERNAL: '문제가 발생했습니다',
    DISCORD_API: '일시적인 문제입니다',
  },
  errorFields: {
    resolution: '💡 해결 방법',
  },
  voice: {
    channelReady: '{{owner}}, 임시 채널이 준비되었습니다! 아래 드롭다운 메뉴로 관리하세요.',
    defaultRoomName: '{{username}}의 방',
    controlPanel: {
      placeholder: '⚙️ 채널 설정 관리',
      rename: '채널 이름 변경',
      limit: '인원 제한 설정',
      lock: '채널 잠금 / 해제',
      kick: '유저 추방',
      ban: '유저 차단 / 숨기기',
      transfer: '소유권 이전',
    },
    responses: {
      channelLocked: '채널이 잠겼습니다! 초대된 멤버만 참여할 수 있습니다.',
      channelUnlocked: '채널이 해제되었습니다! 누구나 참여할 수 있습니다.',
      channelRenamed: '채널 이름이 **{{name}}**(으)로 변경되었습니다!',
      limitSet: '인원 제한이 **{{limit}}**명으로 설정되었습니다!',
      limitUnlimited: '무제한',
      kicked: '{{user}}을(를) 채널에서 추방했습니다.',
      banned: '{{user}}에게 채널을 숨기고 차단했습니다.',
      transferPrompt: '채널의 새 소유자를 선택하세요.',
      transferDone: '소유권이 {{user}}에게 이전되었습니다.',
      banPrompt: '차단하면 해당 유저에게 채널이 보이지 않게 됩니다.',
    },
  },
  commands: {
    voiceSetup: {
      setSuccess: '{{channel}}을(를) 음성 생성기 채널로 설정했습니다!',
      createSuccess: '{{channel}}을(를) 음성 생성기 채널로 생성 및 설정했습니다!',
    },
  },
  modals: {
    renameTitle: '음성 채널 이름 변경',
    renameLabel: '새 채널 이름',
    limitTitle: '인원 제한 설정',
    limitLabel: '인원 제한 (0 = 무제한, 1-99)',
  },
  selects: {
    kickUser: '추방할 유저를 선택하세요',
    banUser: '차단할 유저를 선택하세요',
    transferOwner: '소유권을 이전할 유저를 선택하세요',
  },
} as const;
```

### 3-3. 핵심 모듈: `t()` 함수

```typescript
// src/i18n/index.ts — 개념 설계

import { en } from './locales/en';
import { ko } from './locales/ko';

const locales = { en, ko };
type SupportedLocale = keyof typeof locales;
const DEFAULT_LOCALE: SupportedLocale = 'en';

/**
 * Resolve locale priority:
 * 1. 사용자 DB 설정
 * 2. 서버 DB 설정
 * 3. Discord interaction.locale
 * 4. fallback: 'en'
 */
function resolveLocale(options?: {
  userLocale?: string | null;
  guildLocale?: string | null;
  discordLocale?: string;
}): SupportedLocale {
  const candidates = [
    options?.userLocale,
    options?.guildLocale,
    options?.discordLocale?.split('-')[0], // 'ko-KR' → 'ko'
  ];
  for (const candidate of candidates) {
    if (candidate && candidate in locales) {
      return candidate as SupportedLocale;
    }
  }
  return DEFAULT_LOCALE;
}

/**
 * 번역 키로 현지화된 문자열을 가져옵니다.
 *
 * @param locale - 대상 locale
 * @param key - 점 표기법 키 (예: 'voice.responses.channelLocked')
 * @param vars - 템플릿 변수 (예: { user: '<@123>' })
 */
function t(
  locale: SupportedLocale,
  key: string,
  vars?: Record<string, string>
): string {
  // locale 번역에서 키 검색, 없으면 en fallback
  let value = getNestedValue(locales[locale], key)
           ?? getNestedValue(locales[DEFAULT_LOCALE], key)
           ?? key; // 키 자체를 반환 (최후 fallback)

  // 템플릿 변수 치환: {{name}} → 실제 값
  if (vars) {
    for (const [k, v] of Object.entries(vars)) {
      value = value.replace(new RegExp(`\\{\\{${k}\\}\\}`, 'g'), v);
    }
  }
  return value;
}
```

---

## 4. DB 스키마 확장

### 4-1. `GuildConfig`에 `locale` 필드 추가

```prisma
model GuildConfig {
  guildId       String   @id
  prefix        String   @default("!")
  mimicEnabled  Boolean  @default(true)
  locale        String?  // 서버 언어 설정 (e.g. 'ko', 'en')
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
}
```

### 4-2. `UserLocale` 모델 신규 생성

```prisma
model UserLocale {
  userId    String   @id
  locale    String   // 사용자 개인 언어 설정 (e.g. 'ko', 'en')
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}
```

> [!NOTE]
> `UserLocale`을 별도 모델로 분리하는 이유: `UserVoiceProfile`은 음성 채널 전용이므로,
> 언어 설정은 봇 전체에 걸친 범용 설정으로 독립 관리합니다.

---

## 5. 기존 시스템 통합

### 5-1. `ErrorCodes.ts` → i18n 전환

**Before**
```typescript
INVALID_USER_LIMIT: new BotError({
  code: 'E1001',
  category: ErrorCategory.USER_INPUT,
  userMessage: 'The user limit value is invalid.',
  resolution: 'Please enter a number between 0 and 99.',
}),
```

**After**
```typescript
INVALID_USER_LIMIT: {
  code: 'E1001',
  category: ErrorCategory.USER_INPUT,
  messageKey: 'errors.E1001',  // i18n 키로 대체
},
```

`BotError` 클래스를 수정하여 `userMessage`/`resolution` 대신 `messageKey`를 보유하고,
`ErrorReporter`가 보고 시점에 locale을 결정하여 `t()` 함수로 메시지를 해석합니다.

### 5-2. `ErrorReporter.ts` 변경

```typescript
// buildEmbed 메서드 변경 (개념)
private static buildEmbed(error: BotError, locale: SupportedLocale): EmbedBuilder {
  const msg = t(locale, `${error.messageKey}.userMessage`);
  const res = t(locale, `${error.messageKey}.resolution`);
  const title = t(locale, `errorTitles.${error.category}`);
  const fieldName = t(locale, 'errorFields.resolution');
  // ... Embed 빌드
}
```

### 5-3. `interactionCreate.ts` / `VoiceService.ts` 변경

하드코딩된 모든 사용자 문자열을 `t(locale, key, vars)` 호출로 교체합니다.

```typescript
// Before
await interaction.reply({ content: 'Channel Locked!', ephemeral: true });

// After
await interaction.reply({
  content: t(locale, 'voice.responses.channelLocked'),
  ephemeral: true,
});
```

### 5-4. 슬래시 명령어 설명 현지화 (discord.js `setDescriptionLocalizations`)

discord.js는 슬래시 명령어의 이름/설명에 대한 네이티브 다국어를 지원합니다:

```typescript
new SlashCommandBuilder()
  .setName('voice-setup')
  .setDescription('Setup a generator voice channel for temporary channels.')
  .setDescriptionLocalizations({
    ko: '임시 음성 채널을 위한 생성기 채널을 설정합니다.',
  })
```

> [!IMPORTANT]
> 명령어 이름(`setName`)은 Discord 정책상 영어만 허용됩니다.
> 설명(`setDescription`)과 옵션 설명만 현지화 가능합니다.

---

## 6. 언어 변경 명령어

### `/language` 슬래시 명령어

```
/language [scope] [locale]
  scope: 'user' | 'server'
  locale: 'en' | 'ko'
```

- `scope: user` → `UserLocale` 테이블에 개인 설정 저장
- `scope: server` → `GuildConfig.locale` 업데이트 (관리자 전용)

---

## 7. 구현 Phase

### Phase 1 — i18n 인프라 구축
- `src/i18n/` 디렉터리 생성 (index.ts, types.ts)
- `src/i18n/locales/en.ts`, `ko.ts` 번역 파일 작성
- `t()` 함수, `resolveLocale()` 함수 구현
- DB 스키마 변경: `GuildConfig.locale` 추가, `UserLocale` 모델 생성
- Prisma migrate 실행

### Phase 2 — 에러 시스템 i18n 통합
- `BotError`, `ErrorCodes` 리팩터링: `userMessage`/`resolution` → `messageKey`
- `ErrorReporter.report()` / `buildEmbed()` 에 locale 파라미터 추가
- `withErrorHandler`에 locale 전달 경로 추가
- 기존 테스트 업데이트

### Phase 3 — UI/명령어 문자열 전환
- `interactionCreate.ts` 모든 응답 메시지 `t()` 전환
- `VoiceService.ts` 컨트롤 패널 및 응답 메시지 `t()` 전환
- `voiceSetup.ts` 응답 메시지 `t()` 전환
- 슬래시 명령어 설명 `setDescriptionLocalizations()` 적용

### Phase 4 — 언어 변경 명령어
- `/language` 슬래시 명령어 구현
- `UserLocale` / `GuildConfig.locale` CRUD

### Phase 5 — 테스트
- `t()` 함수 유닛 테스트
- `resolveLocale()` 우선순위 유닛 테스트
- 에러 시스템 통합 테스트 업데이트
- 수동 테스트: Discord에서 `/language` 변경 후 응답 언어 확인

---

## 8. 검증 계획 (Verification Plan)

### 자동 테스트 (Automated Tests)

1. **i18n 핵심 모듈 유닛 테스트** — `tests/i18n/i18n.test.ts`
   - `t()`: 정상 키 → 번역 값 반환
   - `t()`: 미존재 키 → en fallback
   - `t()`: 미존재 키(en에도 없음) → 키 자체 반환
   - `t()`: 템플릿 변수 `{{var}}` 치환 검증
   - `resolveLocale()`: 우선순위 순서 검증 (user > guild > discord > default)
   - 실행: `yarn test -- --testPathPattern='tests/i18n'`

2. **에러 시스템 통합 테스트 업데이트** — `tests/errors/`
   - `ErrorReporter.report()`에 locale 전달 시 해당 언어 Embed 생성 검증
   - 기존 `BotError.test.ts`, `ErrorReporter.test.ts` 수정
   - 실행: `yarn test -- --testPathPattern='tests/errors'`

### 수동 테스트 (Manual Tests)

1. 봇 개발 서버에서 `/language user ko` 실행
2. `/voice-setup create test` 실행 → 한국어 응답 확인
3. 음성 채널 참여 → 한국어 컨트롤 패널 확인
4. 에러 유발 (잘못된 제한 입력 등) → 한국어 에러 Embed 확인
5. `/language user en`으로 복원 → 영어 응답 복원 확인

---

## 9. 열린 질문 / 결정 필요 사항

> [!IMPORTANT]
> 구현 전 확정이 필요한 항목입니다.

1. **번역 파일 형식**: TypeScript 객체(위 제안) vs JSON 파일
   - TS 객체: 타입 안전, IDE 지원 우수 / JSON: 비개발자 편집 용이
   - **제안**: TypeScript 객체 (현재 프로젝트 규모에 최적)

2. **Discord `interaction.locale` 활용 범위**
   - 3순위 fallback으로 사용 (사용자가 별도 설정하지 않은 경우 자동 감지)
   - DB 설정이 있으면 Discord locale을 무시 → 맞습니까?

3. **`/language` 명령어 권한**
   - `user` scope: 모든 사용자 사용 가능
   - `server` scope: 관리자(Administrator) 전용
   - 이 정책이 맞습니까?

4. **VoiceService 내부 로그 메시지**는 i18n 대상에서 **제외** (영어 고정)
   - 서버 로그는 개발자/운영자 전용이므로 영어 유지 → 맞습니까?
