1
설치
npm install i18nexusReact 컴포넌트와 CLI 도구를 모두 설치합니다
2
프로젝트 초기화
npx i18n-sheets init다음을 생성합니다:
- •
i18nexus.config.json- 프로젝트 설정 파일 - •
locales/- 번역 파일 디렉토리 (ko.json, en.json)
3
i18n 설정
locales/index.ts 파일 생성:
// locales/index.ts
import { createI18n } from "i18nexus";
export const translations = {} as const;
async function loadNamespace(namespace: string, lang: string) {
const module = await import(\`./\${namespace}/\${lang}.json\`);
return module.default;
}
export const i18n = createI18n(translations, {
fallbackNamespace: "common",
lazy: true,
loadNamespace,
preloadNamespaces: ["common"],
languageManager: {
defaultLanguage: "ko",
availableLanguages: [
{ code: "ko", name: "한국어", flag: "🇰🇷" },
{ code: "en", name: "English", flag: "🇺🇸" },
],
},
});Root Layout: Provider 없이 간단하게
// app/layout.tsx
export default function RootLayout({ children }) {
return (
<html lang="ko">
<body>{children}</body>
</html>
);
}4
한국어 텍스트 감싸기
npx i18n-wrapper모든 한국어 텍스트를 자동으로 t()로 감쌉니다
⚠️중요: 서버 컴포넌트 확인
i18n-wrapper 실행 후 일부 파일에서 에러가 발생할 수 있습니다:
- 1. 서버 컴포넌트:
파일이 서버 컴포넌트인 경우 (use client가 없는 경우), 훅 대신 서버 유틸리티를 사용해야 합니다 - 2. 수동으로 수정:
에러를 확인하고 use client를 추가할지 getServerTranslation()을 사용할지 결정하세요
✓클라이언트 컴포넌트의 경우
"use client";
import { useTranslation, useLanguageSwitcher } from "i18nexus";
export default function Page() {
const { t } = useTranslation("getting-started");
return <div>{t("안녕하세요")}</div>;
}✓서버 컴포넌트의 경우
import { useTranslation, useLanguageSwitcher } from "i18nexus";
export default async function Page() {
const { t } = await i18n.getServerTranslation();
return <div>{t("안녕하세요")}</div>;
}5
번역 키 추출
npx i18n-extractor코드를 스캔하여 번역 파일을 생성/업데이트합니다
💡App 디렉토리 참고사항
Next.js App Router를 사용하는 경우, -p 플래그를 사용하여 올바른 디렉토리를 지정하세요:
npx i18n-extractor -p "app/**/*.tsx"결과 파일:
- →
locales/ko.json- 한국어 번역 (자동 채워짐) - →
locales/en.json- 영어 번역 (수동 번역 필요)
6
영어 번역 추가
locales/en.json 파일을 열고 영어 번역을 추가하세요
이전 (자동 생성):
{
"안녕하세요": "안녕하세요",
"환영합니다": "환영합니다"
}이후 (번역됨):
{
"안녕하세요": "Hello",
"환영합니다": "Welcome"
}📊
선택사항: Google Sheets 연동
팀 협업을 위해 Google Sheets와 동기화할 수 있습니다
번역 업로드:
npx i18n-sheets upload -s YOUR_SPREADSHEET_ID번역 다운로드:
npx i18n-sheets download -s YOUR_SPREADSHEET_ID