hskwon
8af838ab55
- 2025-12-28 고객센터 시스템 게시판 API 연동 수정 기록 - 날짜 범위 필터 초기값 변경 내용 문서화 fix: 고객센터 목록 날짜 범위 초기값 변경 - EventList, InquiryList, NoticeList 날짜 범위 초기값 빈 문자열로 변경 - 페이지 진입 시 전체 데이터 조회 가능하도록 수정 feat: 1:1 문의 댓글 기능 API 연동 - 댓글 CRUD API 함수 구현 (shared/actions.ts) - getComments, createComment, updateComment, deleteComment - CommentApiData 타입 및 transformApiToComment 변환 함수 추가 - InquiryDetail 컴포넌트 callback props 방식으로 변경 - user.id localStorage 저장으로 본인 글 수정/삭제 버튼 표시 - page.tsx에서 댓글 API 호출 및 상태 관리 feat(WEB): 게시판 시스템 Mock → API 연동 (Phase J) - BoardList: getPosts, getMyPosts API 연동 - BoardDetail: getPost API 연동, 새 라우트 구조 적용 - BoardForm: getBoards, createPost, updatePost API 연동 - 라우트 변경: /board/[id] → /board/[boardCode]/[postId] - Toast 라이브러리 sonner로 통일 - MOCK_BOARDS 완전 제거, types.ts 정리 chore: 작업 현황 업데이트 refactor: BoardForm 부서 Mock 데이터 분리 - types.ts에서 MOCK_DEPARTMENTS 제거 - BoardForm 내부에 임시 Mock 데이터 정의 - TODO: API에서 부서 목록 연동 필요 feat: 종합현황 반려 사유 입력 Dialog 추가 - 반려 시 사유 입력 Dialog 표시 - 사유 미입력 시 toast 에러 메시지 - rejectIssue 함수에 reason 파라미터 추가 feat: 고객센터 Mock → API 연동 완료 - shared/actions.ts: 공통 게시글 API 액션 추가 - shared/types.ts: 공통 타입 정의 - InquiryList: Mock → API 연동, transform 함수 추가 - FAQList: Mock → API 연동, transform 함수 추가 - 상세 페이지: API 연동 (notices, events, inquiries) - 각 types.ts: transformPost 함수 추가 fix: 고객센터 board_code 불일치 수정 - 공지사항: notice → notices - 이벤트: event → events - DB 시스템 게시판 코드와 일치하도록 수정 feat: 결재 문서 작성 파일 첨부 기능 구현 - UploadedFile 타입 추가 및 ProposalData/ExpenseReportData에 uploadedFiles 필드 추가 - uploadFiles() 함수 구현 (/api/v1/files/upload API 연동) - createApproval/updateApproval에서 파일 업로드 후 저장 처리 - ProposalForm/ExpenseReportForm에 첨부파일 UI 개선 - 기존 업로드 파일 표시 (파일 보기/삭제 기능) - 새 첨부 파일 목록 표시 및 삭제 기능 - DraftBox에서 결재자 부서/직책 정보 표시 - 문서 상세 모달에서 실제 API 데이터 표시 (목업 데이터 제거) - 수정 모드 상신 시 PATCH 메서드 사용 (405 에러 수정) feat: [mock-migration] Phase J-4 게시판 관리 Mock → API 연동 완료 - types.ts: BoardApiData, BoardExtraSettings API 타입 추가 - actions.ts: Server Actions 생성 (CRUD, 변환 함수) - index.tsx: Mock 데이터 → API 호출로 전환 - [id]/page.tsx: 상세 페이지 API 연동 - [id]/edit/page.tsx: 수정 페이지 API 연동 - new/page.tsx: 등록 페이지 API 연동 주요 정책: - /boards/tenant 엔드포인트로 테넌트 게시판만 조회 - 수정 시 board_code 전송 안함 (코드 변경 불가) - extra_settings 내 target/target_name 저장 feat: 매입유형(purchase_type) 필드 저장 기능 추가 - actions.ts: API 응답/요청에 purchase_type 매핑 추가 - PurchaseDetail.tsx: 저장 시 purchaseType 포함하도록 수정 fix(salary): 직책/직급 매핑 수정 (사원관리 기준 통일) - transformApiToFrontend: position → job_title_label (직책), rank → rank (직급) - transformApiToDetail: 동일하게 수정 - 기존 잘못된 매핑: position_label(직위) → 직책, job_title_label(직책) → 직급 feat: [mock-migration] Phase M 잔여 Mock/TODO 제거 완료 - M-1: 매입 상세 모달 MOCK_ACCOUNTS, MOCK_VENDORS → API 연동 - M-2: 직원 관리 파일 업로드 API 연동 (uploadProfileImage) - M-4: 결재 문서 생성 MOCK_EMPLOYEES 제거 → getEmployees API - M-5: 결재함/기안함 console.log 제거 → 승인/반려 API 연동 - M-6: 구독 관리 TODO 제거 → requestDataExport, cancelSubscription - M-7: 계정 정보 TODO 제거 → withdrawAccount, suspendTenant docs: 휴가관리 사용현황 동기화 수정 작업 기록 - 2025-12-26 휴가 사용현황 동기화 수정 내용 추가 - fetchUsageData 호출 추가, 부여일수 계산 수정 문서화 feat: Phase G 생산관리/품질검사 Mock → API 연동 완료 G-1 작업지시관리: - WorkOrderList: getWorkOrders, getWorkOrderStats API - WorkOrderDetail: getWorkOrderById API - WorkOrderCreate: createWorkOrder API - SalesOrderSelectModal: getSalesOrdersForWorkOrder API G-2 작업실적관리: - WorkResultList: getWorkResults, getWorkResultStats API G-3 생산대시보드: - actions.ts 생성, getDashboardData API G-4 작업자화면: - actions.ts 생성 - getMyWorkOrders, completeWorkOrder API - MaterialInputModal: getMaterialsForWorkOrder, registerMaterialInput API - ProcessDetailSection: getProcessSteps, requestInspection API G-5 품질검사: - actions.ts 생성 - InspectionList: getInspections, getInspectionStats API - InspectionDetail: getInspectionById, updateInspection API - InspectionCreate: createInspection API fix: [vacation] 휴가 사용현황 동기화 및 부여일수 계산 수정 - 승인 후 fetchUsageData() 호출 추가로 사용현황 즉시 반영 - baseVacation: 동적 totalDays → 고정 '15일' (기본 연차) - grantedVacation: 하드코딩 '0일' → Math.max(0, totalDays-15) 계산 - useCallback dependencies에 fetchUsageData 추가 feat: Phase I Excel/PDF 다운로드 API 연동 - ReceivablesStatus: 채권현황 엑셀 다운로드 API 연동 - VendorLedger: 거래처원장 목록 엑셀, 상세 PDF 다운로드 API 연동 - DailyReport: 일일일보 엑셀 다운로드 API 연동 - Blob 다운로드 패턴 및 toast 알림 적용 feat: L-2 견적 관리 Mock → API 연동 ## 변경사항 - SAMPLE_QUOTES Mock 데이터 제거 - Server Actions 생성 (CRUD + 특수 기능 14개) - QuoteManagementClient 분리 (SSR/CSR 패턴) - Quote 타입 및 변환 함수 정의 ## 추가된 API 연동 - 목록/상세/등록/수정/삭제/일괄삭제 - 최종확정/확정취소/수주전환 - PDF 생성/이메일/카카오 발송 - 견적번호 미리보기/요약 통계 feat: 공정관리 페이지 및 컴포넌트 추가 - 공정관리 목록/상세/등록/수정 페이지 구현 - ProcessListClient, ProcessDetail, ProcessForm 컴포넌트 추가 - ProcessWorkLogPreviewModal, RuleModal 추가 - MobileCard 공통 컴포넌트 추가 - WorkLogModal.tsx 개선 - .gitignore 업데이트 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> (cherry picked from commitf0c0de2ecd) chore: React 공통 컴포넌트 업데이트 - VacationManagement: API 연동 개선 - WorkOrders: 작업자 선택 모달 개선 - TypeScript 빌드 설정 업데이트 feat: I-8 휴가 정책 관리 API 연동 - actions.ts: 휴가 정책 CRUD Server Actions - LeavePolicyManagement 컴포넌트 API 연동 feat: I-7 종합분석 API 연동 - actions.ts: 종합분석 조회 Server Actions - ComprehensiveAnalysis 컴포넌트 API 연동 feat: I-6 일일 생산현황 API 연동 - actions.ts: 일일 리포트 조회 Server Actions - DailyReport 컴포넌트 API 연동 feat: I-5 미수금 현황 API 연동 - actions.ts: 미수금 조회 Server Actions - ReceivablesStatus 컴포넌트 API 연동 feat: I-4 거래통장 조회 API 연동 - actions.ts: 은행 거래내역 조회 Server Actions - BankTransactionInquiry 컴포넌트 API 연동 feat: I-3 법인카드 사용내역 API 연동 - actions.ts: 카드 거래내역 조회 Server Actions - CardTransactionInquiry 컴포넌트 API 연동 feat: I-2 거래처 원장 API 연동 - actions.ts: 거래처 원장 조회 Server Actions - VendorLedger 컴포넌트 API 연동 - VendorLedgerDetail 상세 조회 연동 feat: H-3 출하 관리 API 연동 - actions.ts: Server Actions (CRUD, 상태 변경) - ShipmentList: 출하 목록 API 연동 - ShipmentCreate: 출하 등록 API 연동 - ShipmentEdit: 출하 수정 API 연동 - ShipmentDetail: 출하 상세 API 연동 feat: G-2 작업실적 관리 API 연동 - types.ts API 타입 추가 (WorkResultApi, WorkResultStatsApi 등) - transformApiToFrontend/transformFrontendToApi 변환 함수 추가 - actions.ts 서버 액션 생성 (8개 함수) - index.ts 액션 exports 추가 Server Actions: - getWorkResults: 목록 조회 (페이징, 필터링) - getWorkResultStats: 통계 조회 - getWorkResultById: 상세 조회 - createWorkResult: 등록 - updateWorkResult: 수정 - deleteWorkResult: 삭제 - toggleInspection: 검사 상태 토글 - togglePackaging: 포장 상태 토글 fix: StockStatusList Hook 순서 오류 수정 - 조건부 return 전에 모든 Hooks(useCallback, useMemo) 선언 - React Rules of Hooks 준수 feat: H-2 재고현황 Mock → API 연동 완료 - StockStatusDetail.tsx: 상세 조회 API 연동 - StockStatusList.tsx: 목록 조회 API 연동 (이전 세션) - actions.ts: 재고 현황 Server Actions 구현 feat: H-1 입고 관리 Mock → API 연동 완료 - ReceivingDetail.tsx: 상세 조회 및 입고처리 API 연동 - ReceivingProcessDialog.tsx: 폼 데이터 API 전달 구조로 변경 - InspectionCreate.tsx: 검사 대상 목록 API 조회 적용 - ReceivingList.tsx: 미사용 타입 import 정리 feat: G-1 작업지시 관리 API 연동 - actions.ts 서버 액션 11개 함수 구현 - types.ts API 타입 및 변환 함수 추가 - index.ts 액션 함수 export 추가 Server Actions: - getWorkOrders (목록) - getWorkOrderStats (통계) - getWorkOrderById (상세) - createWorkOrder (등록) - updateWorkOrder (수정) - deleteWorkOrder (삭제) - updateWorkOrderStatus (상태변경) - assignWorkOrder (담당자배정) - toggleBendingField (벤딩토글) - addWorkOrderIssue (이슈등록) - resolveWorkOrderIssue (이슈해결) feat: I-1 미지급비용 관리 React 연동 - Server Actions 패턴으로 API 연동 구현 (actions.ts) - Mock 데이터 제거, props 기반 데이터 주입 - Server Component로 초기 데이터 로딩 - 삭제/지급일 변경 등 CRUD 액션 연동 feat: HR 모듈 API 연동 완료 및 휴가관리 버그 수정 ## 휴가관리 (VacationManagement) - 휴가 부여 API 연동: createLeaveGrant 호출 추가 - 휴가 신청 시 선택된 사원 userId 전달 (잔여휴가 오류 수정) - LeaveType 타입 분리 (VacationType과 구분) - VacationGrantDialog에 부여일(grantDate) 필드 추가 ## 근태관리 (AttendanceManagement) - actions.ts 추가: API 호출 함수 분리 - 타입 정의 확장 및 개선 ## 기타 개선 - CardManagement, SalaryManagement: actions 개선 - DocumentCreate: 전자결재 actions 및 index 개선 - GoogleMap: 지도 컴포넌트 개선 feat: Phase E 인사관리 Mock → API 마이그레이션 - E-1 법인카드 관리 API 연동 - actions.ts 생성 (getCards, createCard, updateCard, deleteCard, toggleCardStatus) - CardForm, 페이지 컴포넌트 API 연동 - E-2 급여 관리 API 연동 - actions.ts 생성 (getSalaries, getSalary, updateSalaryStatus, bulkUpdateSalaryStatus) - 급여 목록 컴포넌트 API 연동 - 결재 시스템 actions.ts 추가 (ApprovalBox, DraftBox, ReferenceBox, DocumentCreate) - DepositManagement actions.ts 페이지네이션 응답 구조 수정 - 부서 관리, 휴가 관리 actions.ts 개선 - API URL에 /api prefix 추가 회계 및 설정 모듈 리팩토링: actions 분리, 타입 정의 개선 feat: 휴가 부여현황 Mock 데이터 제거 및 API 연동 - getLeaveGrants, createLeaveGrant, deleteLeaveGrant API 함수 추가 - LeaveGrantType, LeaveGrantRecord, CreateLeaveGrantRequest 타입 추가 - generateGrantData Mock 함수 제거 - fetchGrantData로 실제 API 호출 - grantData 상태를 API 데이터로 갱신 feat: 휴가 사용현황 Mock 데이터 제거 및 API 연동 - getLeaveBalances() API 함수 추가 - LeaveBalanceRecord, GetLeaveBalancesParams 타입 정의 - generateUsageData() Mock 함수 제거 - fetchUsageData()로 실제 API 호출 - hireDate 날짜 포맷팅 예외 처리 추가 feat: C-4 부서 관리 Mock → API 연동 - actions.ts 생성 (getDepartmentTree, createDepartment, updateDepartment, deleteDepartment, deleteDepartmentsMany) - index.tsx Mock 데이터 제거 및 API 연동 - 트리 구조 CRUD 완전 연동 ⚠️ .env.local에 API_URL=https://api.sam.kr/api 설정 필요 (Server Actions용) feat: C-3 휴가 관리 Mock → API 연동 - actions.ts 생성: getLeaves, createLeave, approveLeave, rejectLeave, cancelLeave 등 - index.tsx 수정: 신청현황 탭 Mock 데이터 → API 호출 전환 - 일괄 승인/반려 API 연동 (approveLeavesMany, rejectLeavesMany) - 휴가 신청 다이얼로그 createLeave API 연동 feat: C-2 근태 관리 Mock → API 연동 - actions.ts 생성 (checkIn/checkOut/getTodayAttendance) - GoogleMap.tsx userLocation 콜백 추가 - page.tsx Mock console.log 제거 + API 연동 - 처리중 상태 및 버튼 텍스트 추가 feat: C-1 직원 관리 Mock → API 연동 - actions.ts 생성 (CRUD + 통계 + 일괄삭제 Server Actions) - utils.ts 생성 (API ↔ Frontend 데이터 변환) - index.tsx Mock 데이터 제거, API 연동 - [id]/page.tsx 상세 페이지 API 연동 - [id]/edit/page.tsx 수정 페이지 API 연동 - new/page.tsx 등록 페이지 API 연동 API Endpoints: - GET/POST /api/v1/employees - GET/PATCH/DELETE /api/v1/employees/{id} - POST /api/v1/employees/bulk-delete - GET /api/v1/employees/stats feat: Daum 우편번호 서비스 연동 및 악성채권 UI 개선 - useDaumPostcode 공통 훅 생성 (Daum Postcode API 연동) - 우편번호 찾기 기능 적용: 악성채권, 거래처, 직원, 회사정보, 주문등록 - 악성채권 페이지 토글 순서 변경 (라벨 → 토글) - 악성채권 토글 기능 수정 (매출/매입 → 등록/해제) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> (cherry picked from commit41ef0bdd86) feat: A-2 팝업 관리 Mock → API 연동 - 상세 조회 페이지: MOCK_POPUPS → getPopupById() API - 수정 페이지: MOCK_POPUPS → getPopupById() API + 로딩 상태 - PopupForm: console.log → createPopup/updatePopup Server Actions - 삭제 기능: deletePopup() API 연동 + 로딩 상태 - 데이터 변환 유틸리티 추가 (API ↔ Frontend) feat: A-1 악성채권 관리 Mock → API 연동 완료 - 상세 페이지 서버 컴포넌트 전환 ([id]/page.tsx, [id]/edit/page.tsx) - BadDebtDetail.tsx: CRUD API 연동 (createBadDebt, updateBadDebt, deleteBadDebt) - actions.ts: 메모 API 추가 (addBadDebtMemo, deleteBadDebtMemo) feat: 매입 관리 Mock → API 전환 및 세금계산서 토글 연동 - index.tsx: Mock 데이터 제거, API 데이터 로딩으로 전환 - actions.ts: getPurchases(), togglePurchaseTaxInvoice() 서버 액션 추가 - vendorOptions 빈 문자열 필터링 (Select.Item 에러 수정) feat: 매출 상세 페이지 API 연동 - 목데이터(MOCK_VENDORS, fetchSalesDetail) 제거 - getSaleById, createSale, updateSale, deleteSale API 연동 - getClients로 거래처 목록 로드 - 상태 관리 개선 (clients, isLoading, isSaving) fix: Mock 데이터를 실제 API 연동으로 복원 - 팝업 관리, 결제 내역, 구독 관리, 알림 설정 API 연동 - 입금/출금/거래처 관리 API 연동 - page.tsx를 서버 컴포넌트로 변환 - actions.ts 서버 액션 추가
15 KiB
15 KiB
next-intl 다국어 설정 가이드
개요
이 문서는 Next.js 16 기반 멀티 테넌트 ERP 시스템의 다국어(i18n) 설정 및 사용법을 설명합니다. next-intl 라이브러리를 활용하여 한국어(ko), 영어(en), 일본어(ja) 3개 언어를 지원합니다.
📦 설치된 패키지
{
"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)
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)
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)
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)
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)
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)
{
"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. 클라이언트 컴포넌트에서 사용
기본 사용법
'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>
);
}
여러 네임스페이스 사용
'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>
);
}
동적 값 포함 (변수 치환)
'use client';
import { useTranslations } from 'next-intl';
export default function ValidationMessage() {
const t = useTranslations('validation');
return (
<p>{t('minLength', { min: 8 })}</p>
// 출력: "최소 8자 이상 입력하세요"
);
}
2. 서버 컴포넌트에서 사용
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. 현재 로케일 가져오기
'use client';
import { useLocale } from 'next-intl';
export default function LocaleDisplay() {
const locale = useLocale(); // 'ko' | 'en' | 'ja'
return <div>Current locale: {locale}</div>;
}
4. 언어 전환 컴포넌트
'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 컴포넌트에서 사용
'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 사용:
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 → 일본어 대시보드
🔄 자동 로케일 감지
미들웨어가 다음 순서로 로케일을 감지합니다:
- URL 경로:
/en/dashboard→ 영어 - 쿠키:
NEXT_LOCALE쿠키 값 - Accept-Language 헤더: 브라우저 언어 설정
- 기본 언어: 위 모두 실패 시 한국어(ko)
📚 고급 사용법
1. Rich Text 포맷팅
{
"welcome": "안녕하세요, <b>{name}</b>님!"
}
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. 복수형 처리
{
"items": "{count, plural, =0 {항목 없음} =1 {1개 항목} other {#개 항목}}"
}
const t = useTranslations();
<p>{t('items', { count: 0 })}</p> // "항목 없음"
<p>{t('items', { count: 1 })}</p> // "1개 항목"
<p>{t('items', { count: 5 })}</p> // "5개 항목"
3. 날짜 및 시간 포맷팅
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. 숫자 포맷팅
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. 언어 코드 추가
// src/i18n/config.ts
export const locales = ['ko', 'en', 'ja', 'zh'] as const; // 중국어 추가
2. 메시지 파일 생성
# src/messages/zh.json 생성
cp src/messages/en.json src/messages/zh.json
# 내용을 중국어로 번역
3. 언어 정보 추가
// 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. 서버 재시작
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 헤더 테스트
# 영어
curl -H "Accept-Language: en" http://localhost:3000
# 일본어
curl -H "Accept-Language: ja" http://localhost:3000
3. 로케일별 라우팅 테스트
# 한국어
curl http://localhost:3000/
# 영어
curl http://localhost:3000/en
# 일본어
curl http://localhost:3000/ja
⚠️ 주의사항
1. 서버/클라이언트 컴포넌트 구분
// ❌ 잘못된 예 (클라이언트 전용 훅을 서버 컴포넌트에서 사용)
import { useRouter } from 'next/navigation';
export default function ServerComponent() {
const router = useRouter(); // 에러!
return <div>...</div>;
}
// ✅ 올바른 예
'use client';
import { useRouter } from 'next/navigation';
export default function ClientComponent() {
const router = useRouter();
return <div>...</div>;
}
2. 메시지 키 누락
모든 언어 파일에 동일한 키가 있어야 합니다.
// ❌ ko.json에는 있지만 en.json에 없는 경우
// ko.json
{ "newFeature": "새 기능" }
// en.json
{} // 누락!
해결: 모든 언어 파일에 키 추가
3. 동적 라우팅
// ❌ 로케일 없이 하드코딩
<Link href="/dashboard">Dashboard</Link>
// ✅ 로케일 포함
<Link href={`/${locale}/dashboard`}>Dashboard</Link>
🔗 참고 자료
📝 변경 이력
| 날짜 | 버전 | 변경 내용 |
|---|---|---|
| 2025-11-06 | 1.0.0 | 초기 i18n 설정 구현 (ko, en, ja 지원) |
💡 팁
번역 키 네이밍 규칙
패턴: {네임스페이스}.{카테고리}.{키}
예시:
- common.buttons.save
- auth.form.emailPlaceholder
- validation.errors.required
- navigation.menu.dashboard
메시지 파일 관리
# 번역 누락 확인 스크립트 (package.json에 추가)
{
"scripts": {
"i18n:check": "node scripts/check-translations.js"
}
}
성능 최적화
- Code Splitting: 네임스페이스별로 메시지 파일 분리
- Dynamic Import: 필요한 언어만 로드
- Caching: 번역 결과 메모이제이션
문서 작성일: 2025-11-06 작성자: Claude Code 프로젝트: Multi-tenant ERP System