하드코딩의 늪에서 AST 스크립트로 탈출한 Next.js i18n 마이그레이션

Context

Next.js 15 App Router 기반 프로젝트의 UI 텍스트 하드코딩 구조. 5,000라인 이상의 거대 컴포넌트로 인한 유지보수 불가 상태. 글로벌 확장 시점에 직면한 다국어 처리 체계 부재 문제.

Technical Solution

• next-intl 라이브러리를 도입하여 App Router 최적화 다국어 라우팅 체계 구축
• 거대 파일의 AI 직접 수정 한계를 극복하기 위해 Node.js 기반 AST(Abstract Syntax Tree) 교체 스크립트 제작 및 적용
• Next.js 15의 dynamic routes params Promise 변경 사항을 컴파일러 에러 피드백 루프로 강제 교정
• 기존 일본어 루트 경로(/)를 유지하고 타 언어는 서브디렉토리(/en, /es 등)로 분리하는 Middleware 설계로 기존 SEO 자산 보호
• sitemap.ts 내 hreflang 태그 자동 생성 로직을 구현하여 검색 엔진의 언어별 인덱싱 최적화
• 단순 번역을 넘어 국가별 문화적 맥락에 맞는 데모 데이터를 생성하는 Localization 전략 적용
• Generative Engine Optimization(GEO) 대응을 위해 AI 크롤러 전용 /llms.txt 파일 구축

Key Takeaway

거대 코드베이스의 리팩토링 시 AI에게 직접 수정을 맡기기보다 수정 도구를 만들게 하는 전략적 접근 필요. 초기 설계 단계에서 i18n 프레임워크를 도입하는 것이 기술 부채를 최소화하는 최선책.