# next-intl 다국어 설정 가이드

## 개요

이 문서는 Next.js 16 기반 멀티 테넌트 ERP 시스템의 다국어(i18n) 설정 및 사용법을 설명합니다. `next-intl` 라이브러리를 활용하여 한국어(ko), 영어(en), 일본어(ja) 3개 언어를 지원합니다.

---

## 적용 현황 분석 (2026-02-03 기준)

### 인프라 상태: 완비

| 항목 | 상태 | 설명 |
|------|------|------|
| 라이브러리 | `next-intl` ^4.4.0 | 설치 및 설정 완료 |
| 지원 언어 | ko, en, ja | 3개 locale |
| 번역 파일 | `src/messages/{ko,en,ja}.json` | 13개 네임스페이스, ~215개 키 |
| 미들웨어 | `src/middleware.ts` | locale 라우팅 + 인증 통합 완료 |
| Provider | `[locale]/layout.tsx` | `NextIntlClientProvider` 정상 |
| URL 라우팅 | `localePrefix: 'as-needed'` | ko는 URL 생략, en/ja는 prefix |

### 실제 적용 현황: 극히 일부만 적용

**`useTranslations` 사용 중인 파일: 3개 (전체의 ~1% 미만)**

| 파일 | 사용 네임스페이스 |
|------|-------------------|
| `src/components/auth/LoginPage.tsx` | auth, common, validation |
| `src/components/auth/SignupPage.tsx` | auth, signup, validation |
| `src/app/[locale]/layout.tsx` | Provider 설정만 |

**하드코딩된 한국어가 있는 파일: ~1,131개**

### 영역별 하드코딩 현황

| 영역 | 파일 수 | 주요 내용 |
|------|---------|----------|
| `business/` (건설) | ~171 | 계약, 입찰, 견적, 기성, 현장관리, 노무, 단가 |
| `items/` (품목) | ~101 | 품목마스터, BOM, 폼, 동적 품목관리 |
| `accounting/` (회계) | ~69 | 거래처, 입출금, 매출, 매입, 어음, 카드 |
| `settings/` (설정) | ~59 | 계정, 권한, 팝업, 구독, 회사정보, 직급, 휴가정책 |
| `hr/` (인사) | ~45 | 직원, 근태, 휴가, 급여, 카드, 부서 |
| `production/` (생산) | ~38 | 작업지시, 작업일지, 검사, 작업자화면 |
| `ui/` (공통 UI) | ~26 | file-list, confirm-dialog, error-card, inputs 등 |
| `approval/` (결재) | ~26 | 결재 워크플로우, 문서생성, 상세 |
| `quotes/` (견적) | ~21 | 견적 등록, 관리, 문서, 계산 |
| `outbound/` (출고) | ~21 | 출고증, 배차차량 |
| `quality/` (품질) | ~13 | 제품검사, 수입검사 |
| 기타 (dashboard, board 등) | ~541 | 대시보드, 게시판, CRM 등 |

### 하드코딩 유형 분류

**1. Config 파일 (~47개)** - 페이지 타이틀, 설명, 라벨
```typescript
// 예: vehicleDispatchConfig.ts
title: '배차차량 상세',
description: '배차차량 정보를 조회합니다',
backLabel: '목록',
```

**2. JSX 직접 텍스트** - 버튼, 라벨, placeholder
```tsx
<Button>삭제</Button>
placeholder="거래처명"
<Label>비고</Label>
```

**3. 토스트/알림 메시지**
```typescript
toast.success('저장되었습니다');
toast.error('삭제에 실패했습니다');
```

**4. 상태/상수 정의 (types.ts)**
```typescript
export const STATUS_LABELS = { draft: '작성대기', completed: '작성완료' };
export const FREIGHT_COST_LABELS = { prepaid: '선불', collect: '착불' };
```

**5. 로딩/에러 상태**
```typescript
if (isLoading) return <div>로딩 중...</div>;  // 79+ 인스턴스
```

**6. Mock 데이터 (~7개)**
```typescript
siteName: '위브 청라',
orderCustomer: '두산건설(주)',
```

### 번역 파일 동기화 상태

| 비교 | 상태 | 이슈 |
|------|------|------|
| ko ↔ en | 동기화 완료 | 231줄 일치 |
| ko ↔ ja | 1건 누락 | `auth.loggingIn` 키 없음 (ja.json) |

### 현재 번역 파일 네임스페이스

```
common       : ~25개 키 (기본 UI 액션)
auth         : ~63개 키 (로그인, 회원가입, 역할, 직급)
signup       : ~14개 키 (업종, 회사규모)
navigation   : ~10개 키 (메인 메뉴)
dashboard    : ~10개 키 (대시보드 위젯)
inventory    : ~15개 키 (재고관리)
finance      : ~11개 키 (회계)
hr           : ~14개 키 (인사)
crm          : ~8개 키 (고객관리)
settings     : ~13개 키 (설정)
errors       : ~7개 키 (에러 메시지)
validation   : ~6개 키 (폼 유효성)
messages     : ~8개 키 (성공/실패 알림)
```

### 작업 규모 (전체 적용 시)

| 작업 항목 | 수량 | 비고 |
|-----------|------|------|
| 번역 키 추출 대상 파일 | ~1,131개 | 반복적 패턴 작업 |
| 추가 필요 번역 키 (추정) | ~3,000~5,000개 | 3개 언어 동기화 필요 |
| Config 파일 전환 | ~47개 | 패턴 동일, 일괄 처리 가능 |
| 공통 UI 컴포넌트 | ~26개 | 영향 범위 넓음 (전체 앱) |
| 비즈니스 컴포넌트 | ~1,000+개 | 단순 반복이나 양 많음 |

### 단계별 적용 계획 (권장)

**Phase 1: 공통 기반** - 효과 가장 큼
- 공통 UI 컴포넌트 26개 (confirm-dialog, error-card, inputs 등)
- 공통 라벨 (저장, 삭제, 취소, 검색, 로딩 중... 등)
- "로딩 중..." 같은 반복 문자열 일괄 처리
- 이것만 해도 전체 앱에 영향

**Phase 2: Config 파일** - 기계적 작업
- 47개 config 파일의 title/description/label
- 패턴이 동일해서 일괄 처리 가능

**Phase 3: 영역별 비즈니스 컴포넌트**
- accounting (69개) → hr (45개) → production (38개) → ...
- 영역당 번역 네임스페이스 1개씩 추가
- business/ (171개)가 가장 큰 덩어리

**Phase 4: 나머지 + 검증**
- 누락 확인, 빌드 테스트
- 실제 언어 전환 테스트 (ko → en → ja)
- ja.json `auth.loggingIn` 누락 수정

### 즉시 수정 필요 사항

1. **ja.json 누락 키**: `auth.loggingIn` 추가 필요
   - ko: `"loggingIn": "로그인 중..."`
   - en: `"loggingIn": "Logging in..."`
   - ja: (누락) → `"loggingIn": "ログイン中..."` 추가

---

## 📦 설치된 패키지

```json
{
  "dependencies": {
    "next-intl": "^latest"
  }
}
```

---

## 🏗️ 프로젝트 구조

```
src/
├── i18n/
│   ├── config.ts                # i18n 설정 (지원 언어, 기본 언어)
│   └── request.ts               # 서버사이드 메시지 로딩
├── messages/
│   ├── ko.json                  # 한국어 메시지
│   ├── en.json                  # 영어 메시지
│   └── ja.json                  # 일본어 메시지
├── app/
│   └── [locale]/                # 동적 로케일 라우팅
│       ├── layout.tsx           # 루트 레이아웃 (NextIntlClientProvider)
│       └── page.tsx             # 홈 페이지
├── components/
│   ├── LanguageSwitcher.tsx     # 언어 전환 컴포넌트
│   ├── WelcomeMessage.tsx       # 번역 샘플 컴포넌트
│   └── NavigationMenu.tsx       # 내비게이션 메뉴 컴포넌트
└── middleware.ts                # 로케일 감지 + 봇 차단 미들웨어
```

---

## 🔧 핵심 설정 파일

### 1. i18n 설정 (`src/i18n/config.ts`)

```typescript
export const locales = ['ko', 'en', 'ja'] as const;
export type Locale = (typeof locales)[number];

export const defaultLocale: Locale = 'ko';

export const localeNames: Record<Locale, string> = {
  ko: '한국어',
  en: 'English',
  ja: '日本語',
};

export const localeFlags: Record<Locale, string> = {
  ko: '🇰🇷',
  en: '🇺🇸',
  ja: '🇯🇵',
};
```

**주요 설정**:
- `locales`: 지원하는 언어 목록
- `defaultLocale`: 기본 언어 (한국어)
- `localeNames`: 언어 표시 이름
- `localeFlags`: 언어별 국기 이모지

---

### 2. 메시지 로딩 (`src/i18n/request.ts`)

```typescript
import { getRequestConfig } from 'next-intl/server';
import { locales } from './config';

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale;

  if (!locale || !locales.includes(locale as any)) {
    locale = 'ko'; // 기본값
  }

  return {
    locale,
    messages: (await import(`@/messages/${locale}.json`)).default,
  };
});
```

**동작 방식**:
- 요청된 로케일을 확인
- 유효하지 않으면 기본 언어(ko)로 폴백
- 해당 언어의 메시지 파일을 동적으로 로드

---

### 3. Next.js 설정 (`next.config.ts`)

```typescript
import createNextIntlPlugin from 'next-intl/plugin';

const withNextIntl = createNextIntlPlugin('./src/i18n/request.ts');

const nextConfig: NextConfig = {
  /* config options here */
};

export default withNextIntl(nextConfig);
```

**역할**: next-intl 플러그인을 Next.js에 통합

---

### 4. 미들웨어 (`src/middleware.ts`)

```typescript
import createMiddleware from 'next-intl/middleware';
import { locales, defaultLocale } from '@/i18n/config';

const intlMiddleware = createMiddleware({
  locales,
  defaultLocale,
  localePrefix: 'as-needed', // 기본 언어는 URL에 표시하지 않음
});

export function middleware(request: NextRequest) {
  // ... 봇 차단 로직 ...

  // i18n 미들웨어 실행
  const intlResponse = intlMiddleware(request);

  // 보안 헤더 추가
  intlResponse.headers.set('X-Robots-Tag', 'noindex, nofollow');

  return intlResponse;
}
```

**특징**:
- 자동 로케일 감지 (Accept-Language 헤더 기반)
- URL 리다이렉션 처리 (예: `/` → `/ko`)
- 기존 봇 차단 로직과 통합

---

### 5. 루트 레이아웃 (`src/app/[locale]/layout.tsx`)

```typescript
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';
import { notFound } from 'next/navigation';
import { locales } from '@/i18n/config';

export function generateStaticParams() {
  return locales.map((locale) => ({ locale }));
}

export default async function RootLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;

  if (!locales.includes(locale as any)) {
    notFound();
  }

  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}
```

**주요 기능**:
- `generateStaticParams`: 정적 생성할 로케일 목록 반환
- `NextIntlClientProvider`: 클라이언트 컴포넌트에서 번역 사용 가능
- 로케일 유효성 검증

---

## 📝 메시지 파일 구조

### 메시지 파일 예시 (`src/messages/ko.json`)

```json
{
  "common": {
    "appName": "ERP 시스템",
    "welcome": "환영합니다",
    "loading": "로딩 중...",
    "save": "저장",
    "cancel": "취소"
  },
  "auth": {
    "login": "로그인",
    "email": "이메일",
    "password": "비밀번호"
  },
  "navigation": {
    "dashboard": "대시보드",
    "inventory": "재고관리",
    "finance": "재무관리"
  },
  "validation": {
    "required": "필수 항목입니다",
    "invalidEmail": "유효한 이메일 주소를 입력하세요",
    "minLength": "최소 {min}자 이상 입력하세요"
  }
}
```

**네임스페이스 구조**:
- `common`: 공통 UI 요소
- `auth`: 인증 관련
- `navigation`: 메뉴/내비게이션
- `validation`: 유효성 검증 메시지

---

## 💻 컴포넌트에서 사용법

### 1. 클라이언트 컴포넌트에서 사용

#### 기본 사용법

```typescript
'use client';

import { useTranslations } from 'next-intl';

export default function MyComponent() {
  const t = useTranslations('common');

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('appName')}</p>
    </div>
  );
}
```

#### 여러 네임스페이스 사용

```typescript
'use client';

import { useTranslations } from 'next-intl';

export default function LoginForm() {
  const t = useTranslations('auth');
  const tCommon = useTranslations('common');

  return (
    <form>
      <h2>{t('login')}</h2>
      <input placeholder={t('emailPlaceholder')} />
      <button>{tCommon('submit')}</button>
    </form>
  );
}
```

#### 동적 값 포함 (변수 치환)

```typescript
'use client';

import { useTranslations } from 'next-intl';

export default function ValidationMessage() {
  const t = useTranslations('validation');

  return (
    <p>{t('minLength', { min: 8 })}</p>
    // 출력: "최소 8자 이상 입력하세요"
  );
}
```

---

### 2. 서버 컴포넌트에서 사용

```typescript
import { useTranslations } from 'next-intl';

export default function ServerComponent() {
  const t = useTranslations('common');

  return (
    <div>
      <h1>{t('welcome')}</h1>
    </div>
  );
}
```

**참고**: Next.js 16에서는 서버 컴포넌트에서도 `useTranslations` 사용 가능

---

### 3. 현재 로케일 가져오기

```typescript
'use client';

import { useLocale } from 'next-intl';

export default function LocaleDisplay() {
  const locale = useLocale(); // 'ko' | 'en' | 'ja'

  return <div>Current locale: {locale}</div>;
}
```

---

### 4. 언어 전환 컴포넌트

```typescript
'use client';

import { useLocale } from 'next-intl';
import { useRouter, usePathname } from 'next/navigation';
import { locales, type Locale } from '@/i18n/config';

export default function LanguageSwitcher() {
  const locale = useLocale();
  const router = useRouter();
  const pathname = usePathname();

  const switchLocale = (newLocale: Locale) => {
    // 현재 경로에서 로케일 제거
    const pathnameWithoutLocale = pathname.replace(`/${locale}`, '');

    // 새 로케일로 이동
    router.push(`/${newLocale}${pathnameWithoutLocale}`);
  };

  return (
    <select
      value={locale}
      onChange={(e) => switchLocale(e.target.value as Locale)}
    >
      {locales.map((loc) => (
        <option key={loc} value={loc}>
          {loc.toUpperCase()}
        </option>
      ))}
    </select>
  );
}
```

---

### 5. Link 컴포넌트에서 사용

```typescript
'use client';

import Link from 'next/link';
import { useLocale } from 'next-intl';

export default function Navigation() {
  const locale = useLocale();

  return (
    <nav>
      <Link href={`/${locale}/dashboard`}>Dashboard</Link>
      <Link href={`/${locale}/settings`}>Settings</Link>
    </nav>
  );
}
```

**또는 `next-intl`의 `Link` 사용**:

```typescript
import { Link } from '@/i18n/navigation'; // next-intl/navigation에서 생성

export default function Navigation() {
  return (
    <nav>
      <Link href="/dashboard">Dashboard</Link>
      <Link href="/settings">Settings</Link>
    </nav>
  );
}
```

---

## 🌐 URL 구조

### 기본 언어 (한국어)

```
http://localhost:3000/              → 한국어 홈
http://localhost:3000/dashboard     → 한국어 대시보드
```

**참고**: `localePrefix: 'as-needed'` 설정으로 기본 언어는 URL에 표시하지 않음

### 다른 언어

```
http://localhost:3000/en            → 영어 홈
http://localhost:3000/en/dashboard  → 영어 대시보드
http://localhost:3000/ja/dashboard  → 일본어 대시보드
```

---

## 🔄 자동 로케일 감지

미들웨어가 다음 순서로 로케일을 감지합니다:

1. **URL 경로**: `/en/dashboard` → 영어
2. **쿠키**: `NEXT_LOCALE` 쿠키 값
3. **Accept-Language 헤더**: 브라우저 언어 설정
4. **기본 언어**: 위 모두 실패 시 한국어(ko)

---

## 📚 고급 사용법

### 1. Rich Text 포맷팅

```json
{
  "welcome": "안녕하세요, <b>{name}</b>님!"
}
```

```typescript
import { useTranslations } from 'next-intl';

export default function Greeting({ name }: { name: string }) {
  const t = useTranslations();

  return (
    <p
      dangerouslySetInnerHTML={{
        __html: t('welcome', { name, b: (chunks) => `<b>${chunks}</b>` }),
      }}
    />
  );
}
```

---

### 2. 복수형 처리

```json
{
  "items": "{count, plural, =0 {항목 없음} =1 {1개 항목} other {#개 항목}}"
}
```

```typescript
const t = useTranslations();

<p>{t('items', { count: 0 })}</p>  // "항목 없음"
<p>{t('items', { count: 1 })}</p>  // "1개 항목"
<p>{t('items', { count: 5 })}</p>  // "5개 항목"
```

---

### 3. 날짜 및 시간 포맷팅

```typescript
import { useFormatter } from 'next-intl';

export default function DateDisplay() {
  const format = useFormatter();
  const date = new Date();

  return (
    <div>
      <p>{format.dateTime(date, { dateStyle: 'full' })}</p>
      <p>{format.dateTime(date, { timeStyle: 'short' })}</p>
    </div>
  );
}
```

**출력 예시**:
- 한국어: "2025년 11월 6일 수요일"
- 영어: "Wednesday, November 6, 2025"
- 일본어: "2025年11月6日水曜日"

---

### 4. 숫자 포맷팅

```typescript
import { useFormatter } from 'next-intl';

export default function PriceDisplay() {
  const format = useFormatter();
  const price = 1234567.89;

  return (
    <div>
      {/* 통화 */}
      <p>{format.number(price, { style: 'currency', currency: 'KRW' })}</p>
      {/* ₩1,234,568 */}

      {/* 퍼센트 */}
      <p>{format.number(0.85, { style: 'percent' })}</p>
      {/* 85% */}
    </div>
  );
}
```

---

## 🛠️ 새 언어 추가하기

### 1. 언어 코드 추가

```typescript
// src/i18n/config.ts
export const locales = ['ko', 'en', 'ja', 'zh'] as const; // 중국어 추가
```

### 2. 메시지 파일 생성

```bash
# src/messages/zh.json 생성
cp src/messages/en.json src/messages/zh.json
# 내용을 중국어로 번역
```

### 3. 언어 정보 추가

```typescript
// src/i18n/config.ts
export const localeNames: Record<Locale, string> = {
  ko: '한국어',
  en: 'English',
  ja: '日本語',
  zh: '中文', // 추가
};

export const localeFlags: Record<Locale, string> = {
  ko: '🇰🇷',
  en: '🇺🇸',
  ja: '🇯🇵',
  zh: '🇨🇳', // 추가
};
```

### 4. 서버 재시작

```bash
npm run dev
```

---

## ✅ 체크리스트

새 페이지/컴포넌트 생성 시 확인 사항:

- [ ] 클라이언트 컴포넌트는 `'use client'` 지시문 추가
- [ ] `useTranslations` 훅 import
- [ ] 하드코딩된 텍스트를 번역 키로 대체
- [ ] 새 번역 키를 모든 언어 파일(ko, en, ja)에 추가
- [ ] Link는 로케일 포함 경로 사용 (`/${locale}/path`)
- [ ] 날짜/숫자는 `useFormatter` 훅 사용

---

## 🧪 테스트 방법

### 1. 브라우저에서 수동 테스트

```
1. http://localhost:3000 접속
2. 언어 전환 버튼 클릭
3. URL이 /en, /ja로 변경되는지 확인
4. 모든 텍스트가 올바르게 번역되는지 확인
```

### 2. Accept-Language 헤더 테스트

```bash
# 영어
curl -H "Accept-Language: en" http://localhost:3000

# 일본어
curl -H "Accept-Language: ja" http://localhost:3000
```

### 3. 로케일별 라우팅 테스트

```bash
# 한국어
curl http://localhost:3000/

# 영어
curl http://localhost:3000/en

# 일본어
curl http://localhost:3000/ja
```

---

## ⚠️ 주의사항

### 1. 서버/클라이언트 컴포넌트 구분

```typescript
// ❌ 잘못된 예 (클라이언트 전용 훅을 서버 컴포넌트에서 사용)
import { useRouter } from 'next/navigation';

export default function ServerComponent() {
  const router = useRouter(); // 에러!
  return <div>...</div>;
}
```

```typescript
// ✅ 올바른 예
'use client';

import { useRouter } from 'next/navigation';

export default function ClientComponent() {
  const router = useRouter();
  return <div>...</div>;
}
```

### 2. 메시지 키 누락

모든 언어 파일에 동일한 키가 있어야 합니다.

```json
// ❌ ko.json에는 있지만 en.json에 없는 경우
// ko.json
{ "newFeature": "새 기능" }

// en.json
{} // 누락!
```

**해결**: 모든 언어 파일에 키 추가

### 3. 동적 라우팅

```typescript
// ❌ 로케일 없이 하드코딩
<Link href="/dashboard">Dashboard</Link>

// ✅ 로케일 포함
<Link href={`/${locale}/dashboard`}>Dashboard</Link>
```

---

## 🔗 참고 자료

- [next-intl 공식 문서](https://next-intl-docs.vercel.app/)
- [Next.js Internationalization](https://nextjs.org/docs/app/building-your-application/routing/internationalization)
- [ICU Message Format](https://unicode-org.github.io/icu/userguide/format_parse/messages/)

---

## 📝 변경 이력

| 날짜 | 버전 | 변경 내용 |
|-----|------|---------|
| 2025-11-06 | 1.0.0 | 초기 i18n 설정 구현 (ko, en, ja 지원) |
| 2026-02-03 | 1.1.0 | 전체 프로젝트 다국어 적용 현황 분석 추가 (하드코딩 현황, 단계별 적용 계획) |

---

## 💡 팁

### 번역 키 네이밍 규칙

```
패턴: {네임스페이스}.{카테고리}.{키}

예시:
- common.buttons.save
- auth.form.emailPlaceholder
- validation.errors.required
- navigation.menu.dashboard
```

### 메시지 파일 관리

```bash
# 번역 누락 확인 스크립트 (package.json에 추가)
{
  "scripts": {
    "i18n:check": "node scripts/check-translations.js"
  }
}
```

### 성능 최적화

- **Code Splitting**: 네임스페이스별로 메시지 파일 분리
- **Dynamic Import**: 필요한 언어만 로드
- **Caching**: 번역 결과 메모이제이션

---

**문서 작성일**: 2025-11-06
**작성자**: Claude Code
**프로젝트**: Multi-tenant ERP System

---

## 관련 파일

### 프론트엔드
- `src/i18n/config.ts` - i18n 설정 (지원 언어, 기본 언어)
- `src/i18n/request.ts` - 서버사이드 메시지 로딩
- `src/messages/ko.json` - 한국어 메시지
- `src/messages/en.json` - 영어 메시지
- `src/messages/ja.json` - 일본어 메시지
- `src/middleware.ts` - 로케일 감지 + 봇 차단 미들웨어
- `src/app/[locale]/layout.tsx` - 루트 레이아웃 (NextIntlClientProvider)
- `src/components/LanguageSwitcher.tsx` - 언어 전환 컴포넌트

### 설정 파일
- `next.config.ts` - Next.js 설정 (next-intl 플러그인)

### 참조 문서
- `claudedocs/architecture/[REF] architecture-integration-risks.md` - 아키텍처 통합 위험 분석