지금 Cursor나 Claude Code에 Next.js 앱에 i18n을 추가해 달라고 하면 십중팔구 middleware.ts, 모든 레이아웃의 setRequestLocale, 그리고 useTranslations를 async 페이지에서 호출하는 구성이 나와요. Next.js 15에서는 맞았지만 Next.js 16 기준으로는 한 세대 지난 구성이에요. globalize.now는 AI 기반 현지화 인프라라서 바로 이 계층을 지켜봐요. 라우팅 연결 방식은 바뀌었지만 그 라우팅이 제공하는 카탈로그는 그대로예요. 무엇이 바뀌었는지, 생성된 코드가 어느 시대 기준인지 구분하는 방법, 그리고 전체를 다시 짜지 않고 오후 한나절이면 끝나는 수정 세 가지를 소개해요.
어느 것도 호환성을 깨는 변경은 아니에요. 그래서 오히려 놓치기 쉬워요.
Next.js 16에서 i18n 관련해 무엇이 바뀌었나요?
로케일을 결정하는 파일의 이름이 바뀌었어요. Next.js 문서에 따르면 middleware 파일 규칙은 지원이 중단되고 proxy로 이름이 바뀌었으며, v16.0.0부터 적용돼요. 이유는 용어 문제예요. “middleware”가 계속 Express 미들웨어로 읽혀서, 실제 역할인 네트워크 경계를 나타내는 이름으로 바꿨어요.
v16에서는 이름 변경과 함께 동작 변화가 두 가지 있어요. Proxy는 기본적으로 Node.js 런타임에서 실행되고, 파일별 runtime 설정 옵션은 더 이상 쓸 수 없어요. 설정하면 Next.js가 에러를 던져요. 또 Proxy는 정적 export를 지원하지 않아요. 로케일 협상 때문에 export를 못 하고 있었다면 중요한 부분이에요.
로케일 라우팅 기준으로 next-intl 설정 가이드는 이제 이 파일을 src/proxy.ts로 안내하고, Next.js 16 전까지는 middleware.ts라고 불렀다고 분명히 적어 둬요. 파일 안의 import는 그대로예요.
// src/proxy.ts
import createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';
export default createMiddleware(routing);
export const config = {
matcher: '/((?!api|trpc|_next|_vercel|.*\\..*).*)'
};
헷갈리기 쉬운 비대칭이 있어요. 파일은 이제 proxy.ts이지만 import 경로는 여전히 next-intl/middleware예요. import까지 바꿔 버리는 건 흔한 과잉 수정이에요.
AI가 생성한 i18n 코드가 한 버전 뒤처지는 이유는 뭔가요?
코딩 에이전트는 가장 많이 나온 패턴을 예측하고, 가장 많이 나온 패턴은 몇 년간 쌓인 쪽이니까요. 2026년 후반 이전에 쓰인 App Router 로케일 라우팅 관련 블로그 글, Stack Overflow 답변, GitHub 예제는 모두 middleware.ts라고 해요. 이 코퍼스와 몇 주 분량의 v16 문서를 저울질하면 모델은 자신 있게 옛 구조를 택하고, 이름이 바뀌었다는 경고는 하지 않아요.
전에 다룬 문제, 즉 i18n 설정 후에도 Cursor가 하드코딩 문자열을 계속 추가하는 현상과 같은 원리예요. 에이전트는 내 코드베이스가 아니라 통계적으로 가장 흔한 코드베이스를 재현해요. GitHub Copilot에서 지침 파일이 일부만 해결해 주는 이유도 마찬가지예요. 채팅에서 읽는 규칙을 인라인 자동 완성이 반드시 읽는 것은 아니니까요.
실제 영향은 좁지만 분명해요. 생성된 설정이 동작하니 요란하게 실패하는 건 없어요. 그러다 버그를 만나 검색해 보면, 최신 답변은 전부 내 프로젝트에 없는 파일을 설명하고 있어요.
생성된 설정이 어느 시대 것인지 어떻게 알 수 있나요?
grep 네 번이면 돼요. 프로젝트 루트에서 실행하면 1분 안에 알 수 있어요.
# 1. Pre-16 locale negotiation file
ls middleware.ts src/middleware.ts 2>/dev/null
# 2. Legacy static-rendering API
grep -rn "setRequestLocale" app src 2>/dev/null
# 3. Hooks called inside async components
grep -rn -B3 "useTranslations" app | grep -n "async function"
# 4. Which next-intl era the config reads from
grep -rn "root-params\|await params" src/i18n/request.ts 2>/dev/null
1번과 2번에서 결과가 나오면 16 이전 스캐폴딩이에요. 3번에서 나오면 해당 컴포넌트를 렌더링하는 첫 요청에서 터질 진짜 런타임 오류예요. 4번에서 아무것도 안 나오면 request config가 이전 방식으로 로케일을 읽고 있다는 뜻이에요.
middleware.ts를 proxy.ts로 꼭 바꿔야 하나요?
급하지는 않아요. 다만 손으로 바꾸지는 마세요. Next.js가 파일 이름과 export 함수 이름을 함께 바꿔 주는 codemod를 제공해요.
npx @next/codemod@canary middleware-to-proxy .
이름 변경은 제거가 아닌 deprecation이라서 기존 middleware.ts도 계속 동작해요. 그래도 실행하는 이유는 유지보수 비용이에요. 파일 이름이 최신 문서와 맞으면 앞으로 나오는 검색 결과가 모두 내 저장소에 적용돼요. 그대로 두면 디버깅할 때마다 작은 비용을 계속 치르게 돼요.
next-intl에서 setRequestLocale은 deprecated인가요?
레거시로 표시돼 있어요. deprecated보다는 약한 표현이니 정확히 읽을 필요가 있어요. next-intl 문서는 setRequestLocale를 next/root-params가 도입되기 전까지 쓰던 API로 설명하고, 하위 호환을 위해 계속 지원하며, 대신 next/root-params를 쓰라고 권장해요.
새로운 방식은 모든 레이아웃과 페이지로 로케일을 직접 전달하는 대신, request config 안에서 매칭된 로케일을 읽어요.
// src/i18n/request.ts
import * as rootParams from 'next/root-params';
import {notFound} from 'next/navigation';
import {getRequestConfig} from 'next-intl/server';
import {hasLocale} from 'next-intl';
import {routing} from './routing';
export default getRequestConfig(async ({locale}) => {
if (!locale) {
const paramValue = await rootParams.locale();
if (hasLocale(routing.locales, paramValue)) {
locale = paramValue;
} else {
notFound();
}
}
return {locale};
});
next/root-params는 Next.js 16.3 이상에서 기본 제공되고, 이전 버전에서는 experimental.rootParams로 켜야 해요. 이렇게 설정하면 [locale] 세그먼트에 generateStaticParams를 계속 export하기만 하면 정적 렌더링이 자동으로 따라와요.
예전 방식에서는 Next.js가 레이아웃과 페이지를 각각 독립적으로 렌더링하기 때문에, 정적으로 렌더링하려는 모든 페이지와 레이아웃에서 다른 next-intl 호출보다 먼저 setRequestLocale를 호출해야 했어요. AI 에이전트가 다섯 번째 파일쯤에서 잊어버리는 규칙이에요. 이 요구 사항이 사라지면서 이런 종류의 버그도 사라져요.
async Server Component에서 useTranslations가 크래시하는 이유는 뭔가요?
async 컴포넌트에서는 훅을 호출할 수 없는데 useTranslations는 훅이기 때문이에요. next-intl의 특이한 동작이 아니라 React Server Components의 제약이고, next-intl은 await 가능한 대응 함수 세트로 이를 해결해요.
// Async component: await the server API
import {getTranslations} from 'next-intl/server';
export default async function ProfilePage() {
const user = await fetchUser();
const t = await getTranslations('ProfilePage');
return <h1>{t('title', {username: user.name})}</h1>;
}
// Non-async component: the hook is correct here
import {useTranslations} from 'next-intl';
export default function UserDetails({user}) {
const t = useTranslations('UserProfile');
return <h2>{t('title')}</h2>;
}
getFormatter, getNow, getTimeZone, getMessages, getLocale도 같은 패턴을 따라요. 두 번째 예시는 짚고 넘어갈 만해요. async가 아니고 인터랙션이 없는 컴포넌트는 공유 컴포넌트이고, next-intl이 서버에서 렌더링되는지 클라이언트에서 렌더링되는지에 따라 알맞은 구현을 선택해요. 그래서 서버 컴포넌트에서 useTranslations를 쓰는 것은 실수가 아니에요. 문제는 async 컴포넌트에서 호출하는 경우예요.
NextIntlClientProvider 컨텍스트 오류는 왜 발생하나요?
next-intl의 트러블슈팅 문서는 원인을 두 가지로 설명하는데, 해결 방향은 정반대예요. 컴포넌트가 실제로 클라이언트에서 실행되는데 위쪽에 provider가 없다면 provider로 감싸고 필요한 메시지를 넘기세요. 서버 렌더링을 기대했는데 클라이언트 모듈 그래프로 딸려 들어갔다면, Server Component 안에서 import하지 말고 children를 통해 Server Component에서 넘기세요.
AI가 생성한 앱은 두 번째 경우에 자주 걸려요. 에이전트가 인터랙션을 동작시키려고 'use client'를 넉넉하게 붙이는데, 이 지시어는 import 그래프를 따라 아래로 전염되거든요. 권장하는 패턴은 서버에서 번역하고, 완성된 문자열을 경계 너머로 넘기는 거예요.
import {useTranslations} from 'next-intl';
import Expandable from './Expandable'; // 'use client'
export default function FAQEntry() {
const t = useTranslations('FAQEntry');
return <Expandable title={t('title')}>{t('description')}</Expandable>;
}
클라이언트에서 메시지가 꼭 필요한 컴포넌트가 있다면, 모든 메시지를 브라우저로 보내는 대신 그 서브트리만 감싸는 provider를 둘 수 있어요. 루트 provider에 messages={null}을 쓰면 메시지를 전혀 전달하지 않아요.
이 모든 변경에도 바뀌지 않는 건 뭘까요?
바로 로케일 파일이에요. 위의 수정은 모두 라우팅과 렌더링 배선이고, 앱이 불러오는 JSON은 하나도 건드리지 않아요. 여기가 핵심이에요. 배선은 한나절이면 끝나고 1년에 한 번쯤 바뀌지만, 카탈로그는 새 UI가 나올 때마다 매주 낡아가니까요.
globalize.now는 이 역할 분리를 전제로 만들었어요. next-intl과 비슷한 라이브러리는 런타임에 번역을 제공하고, 우리는 그들과 경쟁하지 않아요. 아직 고르는 중이라면 next-intl vs react-i18next vs Lingui에서 장단점을 비교해 보세요. globalize.now는 한 계층 위에서 그 런타임이 읽는 키와 로케일 파일을 만들어요. 그래서 Next.js 연동은 로케일 협상이 middleware.ts에 있든 proxy.ts에 있든 상관없어요.
변환은 앱에서 한 번만 이뤄져요. 저장소를 연결하면 globalize.now가 코드베이스를 한 번 변환하고 카탈로그가 담긴 PR을 열어요. 그 뒤로는 새 카탈로그 항목이 생길 때마다 푸시 작업이 번역해요. 번역 파일이 계속 어긋나는 이유에서 설명한 문제가 바로 이 지점에서 생기고, 그래서 세 번째 로케일을 추가하기 전에 이 간극을 메워 두는 것이 좋아요.
이미 직접 작성한 next-intl 설정이 있다면 globalize.now가 무엇을 건드리고 무엇을 건드리지 않는지를 정리해 뒀어요. 설정이 없다면 Cursor 따라 하기 가이드가 가장 빠른 길이에요. 다만 그 가이드가 생성하는 파일은 이전 규칙의 이름을 쓰니, 가이드를 마친 뒤 codemod를 실행하세요.
시작하는 방법
grep 네 개를 실행하세요. 처음 두 개에서 결과가 나오면 codemod를 실행하고, 요청 설정을 next/root-params로 옮기면 최신 상태가 돼요. 그다음 로케일 파일을 살펴보세요. 다음 달에도 계속 어긋날 부분이 바로 여기예요. AI로 만든 앱을 배포 중인데 카탈로그를 직접 관리하는 대신 맡기고 싶다면, 개요는 vibe coder 페이지에, 요금은 별도 페이지에 있어요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기