Next.js와 함께 globalize.now 사용하기
Next.js 앱의 국제화를 5분 안에 설정하세요.
Next.js는 next-intl, next-i18next 같은 라이브러리로 i18n을 훌륭하게 지원하지만, 이런 라이브러리는 번역 키가 이미 갖춰진 코드베이스를 전제로 해요. globalize.now는 그 앞 단계를 맡아요. 하드코딩된 영어로 가득한 Next.js 앱에서 키, 로케일 파일, 리팩터링된 컴포넌트를 만들어내면 next-intl(또는 다른 런타임 라이브러리)이 그대로 사용할 수 있어요.
사전 준비
- Next.js 프로젝트(App Router 또는 Pages Router)
- Git 저장소
- Node.js 18 이상
- i18n 런타임 라이브러리 (next-intl 권장)
Next.js에서 globalize.now 설정하는 방법
런타임 라이브러리 설치하기
앱이 실행 중에 로케일별 메시지를 불러올 수 있도록 next-intl이나 선호하는 라이브러리를 추가하세요.
npm install next-intlnext-intl 기본 라우팅 설정하기
next-intl 문서에 따라 미들웨어, 프로바이더, 라우트 세그먼트를 연결하세요. 이미 설정했다면 이 단계는 건너뛰어도 돼요.
Globalize Skill 설치 프로그램 실행하기
Next.js 프로젝트 루트에서 Skill을 설치하세요. 에이전트가 라우팅 설정에 맞춰 작업할 수 있어요.
npx skills add globalize-now/globalize-skills --allnext-intl 감지 확인하기
에이전트가 프로바이더와 메시지 경로가 globalize.now가 Next.js에서 기대하는 규칙과 맞는지 검증해요.
제안된 로케일 파일 구조 검토하기
제안된 messages 디렉터리와 파일 이름이 선택한 로케일별 메시지 패턴을 따르는지 확인하세요.
리터럴을 번역 호출로 리팩터링하기
코드에 박힌 영어를 t() 또는 프로바이더와 연결된 동등한 헬퍼로 바꾸는 변경을 승인하세요.
Git에 푸시하기
브랜치를 머지하고 푸시하세요. 이후 푸시마다 globalize.now가 번역을 계속 동기화해요.
자주 겪는 문제
next-intl이 특정 메시지 구조를 요구해요
해결 방법: globalize.now가 next-intl 규칙을 자동으로 감지하고, 설정한 로케일 폴더에 맞는 JSON을 작성해요. 구조를 손으로 고칠 일이 줄어들어요.
이미 번역된 문자열이 몇 개 있는데, globalize.now가 덮어쓰나요?
해결 방법: 기존 키는 가능한 한 그대로 유지하고, 새 리터럴만 점진적으로 추가해요. 번역가가 기존 작업을 잃지 않아요.
자주 묻는 질문
globalize.now는 next-intl, next-i18next와 함께 쓸 수 있나요?
네. globalize.now는 저장소 구조(키, JSON 카탈로그, 컴포넌트 호출부)에 집중하고, 런타임에는 next-intl이나 next-i18next가 계속 메시지를 불러와요. 라우팅 모델에 맞는 런타임을 고르세요. globalize.now가 그 선택에 맞춰 출력을 조정해요. Skill을 일부러 새로 갱신하는 경우가 아니라면, 프로젝트를 처음 설정할 때 npx skills add globalize-now/globalize-skills를 한 번만 실행하면 돼요.
globalize.now는 App Router와 Pages Router를 모두 지원하나요?
네. 에이전트 Skill이 사용 중인 라우터 방식을 감지해서 알맞은 레이아웃 파일, 라우트 핸들러, 프로바이더에 맞춰 문자열을 추출해요. globalize.now가 Next.js 라우팅을 대체하는 건 아니고, 라우트를 거치는 문자열이 모두 키로 관리되도록 보장해요. 설정이 끝나면 App Router의 서버 컴포넌트와 클라이언트 컴포넌트 모두 런타임이 기대하는 같은 로케일 파일을 참조해요.
이미 i18n이 일부 적용된 Next.js 앱에도 globalize.now를 쓸 수 있나요?
네. 에이전트에 저장소를 지정하면 기존 메시지 번들을 확장하면서 리터럴이 남은 부분을 채워요. 마케팅 페이지만 먼저 번역한 프로젝트에서 흔한 경우예요. globalize.now는 기존 번역을 버리지 않고 새 키만 병합하기 때문에 화면 단위로 차근차근 마이그레이션할 수 있어요.
globalize.now는 서버 컴포넌트와 클라이언트 컴포넌트를 다르게 처리하나요?
globalize.now는 훅과 프로바이더를 어디서 실행할 수 있는지에 관한 Next.js 규칙을 지키면서, 각 경계에서 스택이 쓰는 헬퍼로 리터럴을 바꿔요. JSON 결과물은 서버와 클라이언트 번들이 공유하므로 카탈로그를 중복으로 만들 필요가 없어요. 인터랙션이 필요한 컴포넌트를 클라이언트 컴포넌트로 지정하는 일은 Next.js 문서를 따라 직접 하세요.
globalize.now는 Next.js의 정적 생성과 어떻게 연동되나요?
로케일 파일은 Git에 있으므로 `next build`는 SSG나 SSR 라우트가 next-intl로 이미 가져오던 JSON을 그대로 번들링해요. globalize.now는 문자열이 리터럴 대신 데이터 파일에서 오도록 만들 뿐, 정적 생성 파이프라인은 바꾸지 않아요. 새 문구가 추가되면 Git에 푸시할 때마다 다음 배포 전에 번역이 갱신돼요.
npx skills add globalize-now/globalize-skills를 실행하기 전에 next-intl을 먼저 설치해야 하나요?
런타임이 이미 정해졌다면 next-intl을 먼저 설치하는 편이 좋아요. 에이전트가 프로바이더를 바로 연결할 수 있거든요. 아직 라이브러리를 고르지 않았더라도 npx skills add globalize-now/globalize-skills를 실행할 수 있어요(Skill이 스택 추천을 도와줘요). 다만 의존성을 설치한 뒤에 설정을 다시 실행해야 할 수 있어요. 어느 쪽이든 결과는 같아요. 키가 Git에 커밋되고, 푸시할 때 동기화돼요.
Next.js에서 globalize.now 사용해 보기
프로젝트 루트에서 시작하세요:
npx skills add globalize-now/globalize-skills --all