저장소에 next-intl, react-i18next, i18next, Lingui가 이미 연결돼 있다면(디스크의 로케일 폴더, package.json의 의존성, 미들웨어나 설정 파일), 처음부터 시작한다고 가정하는 다른 도구는 필요 없어요. globalize.now는 AI 기반 현지화 인프라예요. L1(이미 국제화된 프로젝트) 모드에서는 기존 구조를 건드리는 초기 스캐폴드를 건너뛰고 동기화 모드로 동작해요. 원본 언어를 읽고, 푸시할 때 다른 로케일과 diff를 비교하고, 빈 부분을 채운 PR을 열어요. 이 글에서는 이 모드가 무엇을 건드리고 무엇을 건드리지 않는지, 감지가 틀렸을 때 어떻게 하는지 다뤄요.
i18n 가이드는 왜 대부분 처음부터 시작한다고 가정할까요?
i18n 도구의 마케팅 문구는 아직도 ‘그린필드’ 상황을 기준으로 해요. 라이브러리도 로케일 파일도 없고 추출도 안 한 상태예요. 하지만 대부분의 프로덕션 코드베이스는 그렇지 않아요.
최근 몇 주 사이에 서로 무관한 세 번의 첫 사용 세션이 같은 모습으로 들어왔어요. 팀이 i18n을 한 번 시도했고, 반쯤 동작하는 상태에서 멈췄어요. 걷어 내고 다시 하는 것보다 지저분한 채로 사는 게 낫다고 느꼈기 때문이에요.
이 상황이 낯설지 않다면, 이 글은 바로 당신 같은 독자를 위해 썼어요.
반쯤 국제화된 코드베이스는 실제로 어떤 모습인가요?
이런 패턴이 계속 반복돼요(세부 내용은 익명화했어요).
- 대부분의 컴포넌트가
t()를 쓰지만, 첫 마이그레이션 단계가 끝나지 않아 오래된 라우트는 여전히 영어가 하드코딩된 Next.js + next-intl 앱. - 로케일 파일은 있지만 값이 영어뿐인 React + i18next 프로젝트예요. 번역은 늘 다음 분기 일이었어요.
en.json는 가득 차 있는데es.json는 사실상 비어 있는messages/구조.- 라우팅이 반쯤만 마이그레이션돼서 가끔 404가 뜨는, 레이아웃에 연결된 언어 전환기.
이 프로젝트들은 globalize.now가 처음부터 다시 시작하길 바라지 않아요. 작업을 끝내 주길 바라요.
globalize.now는 처음 실행할 때 어떤 신호를 스캔하나요?
감지는 한 번이 아니라 두 단계로 이루어져요.
먼저 globalize.now를 저장소에 연결하세요. 앱에서 연결하면 감지와 1회성 변환까지 대신 실행해요. 에이전트가 로컬에서 이 작업을 하게 하려면 Skill을 설치하세요. 플레이북 파일 몇 개를 .claude/skills/에 넣을 뿐, 저장소의 다른 부분은 건드리지 않아요.
npx skills add globalize-now/globalize-skills
그다음 에이전트에 프롬프트를 입력하세요. Claude Code, Cursor, Codex 모두 돼요. 에이전트가 설치된 Skill을 읽고 저장소를 스캔해요.
Set up localization for my project
실제 감지는 이 두 번째 단계에서 실행돼요. 에이전트는 다음을 확인해요.
package.json의존성:next-intl,react-i18next,i18next,@lingui/core,@lingui/react,@lingui/macro또는i18next-*플러그인.- 로케일 폴더: 저장소 루트의
messages/,locales/폴더, 또는 로케일 하위 폴더가 있는src/i18n/. - 기존 로케일 파일:
en.json,en.po,en.yml,en.yaml, 또는 사용 중인 라이브러리가 기대하는 기본 로케일 파일. - 프레임워크별 설정:
i18n.config.ts, next-intl 미들웨어,lingui.config.js또는 이에 준하는 설정.
이 신호 중 두 개 이상이 있으면 프로젝트를 L1(이미 국제화됨)로 판단하고, 전체 신규 스캐폴드를 실행하는 대신 설정 흐름이 갈라져요. 자세한 내용은 기존 i18n에 관한 Help Center 문서에서 볼 수 있어요.
L1 모드에서 건드리지 않는 것은 무엇인가요?
가장 궁금해하는 부분이에요. L1 모드에서 globalize.now는 다음 작업을 하지 않아요.
- 컴포넌트에서 하드코딩된 리터럴을 찾는 광범위한 문자열 추출 작업을 실행하지 않아요.
- 새 번역 키를 만들거나, 이미 커밋한 키 구조를 재배치하지 않아요.
- 아직 설정하지 않은 언어의 로케일 파일을 생성하지 않아요.
- 언어 전환기를 넣지 않아요. 이미 있으면 그대로 두고, 없으면 추가하지 않아요.
- 라우팅, 미들웨어, 프레임워크 설정을 대신 수정하지 않아요.
기존 i18n 설정은 그대로 유지해요. 이 모드에서는 리팩터링하지 않아요.
L1 동기화 모드는 감지 후 무엇을 하나요?
L1은 동기화가 중심이에요. 감지가 끝나면 다음 순서로 진행해요.
- 기존 로케일 파일을 읽어 현재 키 구조와 기준이 되는 원본 언어를 파악해요.
- globalize.now CLI나 웹 앱으로 GitHub 저장소를 연결하세요.
- main 브랜치에 푸시할 때마다 원본 언어 파일과 다른 로케일 파일을 비교해요. 누락된 번역은 설정해 둔 용어집과 스타일 가이드를 반영한 AI 번역으로 채워요.
- 업데이트된 로케일 파일이 담긴 PR이 올라와요. 검토하고 머지하세요. 대신 머지하는 일은 절대 없어요.
이게 전체 흐름이에요. 지켜봐야 하는 번역 대시보드도, 수동 내보내기도, 파일 형식 변환도 없어요.
Cursor로 만든 Next.js 앱에 15분 만에 i18n을 추가하려면 어떻게 하나요?의 L0 안내와 비교해 보세요. 같은 제품이지만 시작 경로가 달라요.
UI 일부에만 번역 호출이 적용돼 있다면 어떻게 되나요?
마이그레이션 중간 단계에서 흔히 볼 수 있는 모습이에요. 새 화면은 t()를 쓰고, 기존 화면에는 리터럴이 그대로 남아 있죠. 동기화 모드가 아닐 때 skills 파이프라인은 이미 키가 적용된 문자열을 잠가 둬요. 아직 연결되지 않은 리터럴에 집중하고 기존 키는 그대로 보존해요. 마이그레이션 중간에도 매주 배포하는 팀이 로그에서 가장 흔한 ‘혼합 L1’ 사용자예요.
복잡하게 얽힌 구조를 에이전트가 통째로 변환한 사례는 AI 에이전트가 실제 모노레포를 국제화하면 어떤 일이 생길까요?에서 볼 수 있어요.
설정 흐름이 모든 것을 새로 구성해 버렸다면 어떻게 해야 하나요?
잘못된 분기가 실행되지 않도록 감지 로직을 개선하고 있어요. 그래도 이미 로케일 폴더를 갈아엎거나, 요청하지 않은 스위처를 넣거나, 라우팅을 바꾸는 100개 이상 파일의 diff를 npx skills add globalize-now/globalize-skills에서 만들었다면 커밋하지 마세요. 오른쪽 아래 피드백 위젯으로 package.json 의존성 목록과 로케일 폴더 구성에 대한 간단한 설명을 보내 주세요. 저희가 저장소를 L1로 직접 분류해 드릴 수 있어요. 셀프 서비스용 --existing-i18n CLI 플래그도 곧 나와요.
로컬 복구는 git restore .에 필요하면 git clean -fd도 더하면 돼요. 푸시된 건 없고, 운영 환경에 영향을 준 것도 없어요. 에이전트는 로컬 브랜치만 건드렸어요. 전체 내용은 globalize_skills가 너무 많은 변경을 했어요: 무슨 일이 있었나요?에 있어요.
요즘은 왜 “i18n을 시도했다가 멈췄다”는 이야기가 흔할까요?
이건 구호가 아니라 패턴이에요. 6주 동안 서로 독립적인 첫 사용 세션이 세 번 있었고, 세 번 모두 “네, 시도는 했는데 지금은 엉망이에요”라는 답이었어요. 사용자가 수만 명인 Chrome 확장 프로그램은 한국 트래픽이 급증하자 절반만 끝난 next-intl 마이그레이션을 시작했어요. Lovable로 만든 앱은 다국어 지원을 추가하다 빌드가 깨져서 되돌렸어요. vibe coding으로 만든 React + Vite 저장소는 i18next를 연결하고 키의 3분의 1쯤만 채운 채 멈췄어요.
라이브러리만 찾으면 되는 깨끗한 L0 코드베이스도 분명 있어요. 하지만 그게 병목은 아니에요. 진짜 병목은 이미 한 번 시도했다가 뒷수습을 아무도 맡고 싶어 하지 않는 코드베이스예요.
L1 모드는 바로 그런 코드베이스를 위해 만들었어요.
요금은 얼마인가요?
Starter는 월 €20이고 매달 €20 크레딧이 포함돼요. 크레딧은 번역, QA 리뷰, 변환에 차감되고, 기간이 끝날 때 남은 크레딧은 소멸해요. 월 €249에 €100 크레딧이 포함된 Team 요금제도 있어요. 새 조직에는 14일 뒤 만료되는 1회성 체험 크레딧 €5가 제공돼요. 처음부터 시작하는 L0든 3년치 로케일 부채를 안고 있는 L1이든 요금은 같아요. 첫 커밋이 얼마나 지저분했는지가 아니라 제공업체 비용을 기준으로 사용량을 청구해요.
다음에는 어떤 글과 도움말 문서를 읽으면 좋을까요?
- Cursor Next.js 앱 L0 설정 가이드
- 모노레포 사례 연구: 에이전트가 실제로 건드린 것
- 기존 TMS 도구가 최신 Git 기반 스택에서 어려움을 겪는 이유
- Help Center: 이미 i18n이 있는데 globalize.now는 무엇을 하나요?
- 도움말: globalize_skills가 너무 많이 바꿨어요
트래픽이 이미 기대하는 언어를 배포하세요. globalize.now에서 저장소를 연결하거나, Git 푸시 자동화가 기존 팀 워크플로에 어떻게 들어맞는지 확인해 보세요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기