Next.js 앱을 번역했는데 브라우저 탭, 404 페이지, 폼 오류, 링크 미리보기가 아직 영어라면 원인은 거의 항상 같아요. 이 문자열들은 컴포넌트 바깥에서 만들어져서 useTranslations 호출이 닿지 않았어요. globalize.now는 AI 기반 현지화 인프라예요. AI 에이전트가 App Router 프로젝트에 i18n을 추가할 때 이 계층이 반쯤 빠지는 경우를 자주 봐요. 눈에 보이는 페이지는 변환되지만 나머지 영역은 그대로예요.
아래에서 각 문자열이 어디에 있고 어떤 next-intl 호출로 처리하는지 살펴볼게요. 모든 예시는 2026-10-28에 확인한 최신 next-intl 문서를 따라요.
App Router 앱에서 번역되지 않은 문자열은 어디에 숨어 있나요?
텍스트를 렌더링하는 React 컴포넌트가 아닌 여섯 곳에 숨어 있어요. 컴포넌트를 하나씩 돌며 i18n을 추가하는 코딩 에이전트는 눈에 보이는 UI는 변환하고, 이 영역은 그냥 지나쳐요.
generateMetadata의 페이지 제목과 설명.- Server Action의 유효성 검사 오류와 결과 메시지.
- 404 페이지인
not-found.tsx. - 런타임 오류 페이지인
error.tsx. opengraph-image.tsx,manifest.ts,sitemap.ts같은 생성 파일.- 텍스트를 반환하는 Route Handler.
공통점은 이 중 어느 것도 [locale] 레이아웃 트리 안에서 일반적인 방식으로 렌더링되지 않는다는 거예요. 그래서 로케일을 직접 넘기거나 다른 방식으로 읽어야 해요. 라우팅 배선은 Next.js 16 라우팅 글에서 다뤘고, 이 글은 그 배선이 닿지 않는 부분을 다뤄요.
페이지 제목과 설명은 어떻게 번역하나요?
generateMetadata 안에서 next-intl/server의 getTranslations를 호출하세요. 이 함수는 page나 layout에서 export할 수 있고 비동기라서, await 방식의 API가 맞아요.
// app/[locale]/page.tsx
import {getTranslations} from 'next-intl/server';
export async function generateMetadata() {
const t = await getTranslations('Metadata');
return {title: t('title'), description: t('description')};
}
함정은 정적 형태예요. 에이전트는 더 짧다는 이유로 export const metadata = {title: 'Dashboard'}를 자주 쓰는데, 상수는 번역 함수를 호출할 수 없어요. 함수 형태로 바꾸고, 같은 키를 모든 로케일의 카탈로그에 추가하세요. 이 텍스트는 검색 결과에 노출되는 부분이기도 해서, 메타데이터를 번역하지 않고 앱만 번역하면 검색 순위에 별 도움이 안 돼요.
Server Action과 유효성 검사 메시지는 어떻게 번역하나요?
액션에 로케일을 넘기고, 네임스페이스와 그 로케일을 함께 지정해 getTranslations를 호출하세요. Server Action은 페이지가 어떤 언어로 표시되는지 알지 못하므로, next-intl 문서는 예를 들어 인자로 로케일을 직접 전달하도록 안내해요.
'use server';
import {getTranslations} from 'next-intl/server';
export async function subscribe(locale: string, formData: FormData) {
const t = await getTranslations({locale, namespace: 'Subscribe'});
// ...validate, then return t('success') or t('invalidEmail')
}
같은 문서의 주의사항이 하나 있어요. 액션 메시지가 화면에 떠 있는 동안 방문자가 언어를 바꿀 수 있다면 어떻게 될지 생각해 보세요. URL에 [locale] 세그먼트가 있으면 라우트가 바뀌므로 자동으로 처리돼요. 없다면 직접 메시지를 지워야 할 수 있어요. 예를 들어 컴포넌트에 key={locale}를 지정해 상태를 초기화하세요.
Zod로 폼을 검증할 때 문서가 안내하는 방법은 오류 맵이에요. Zod는 safeParse 호출마다 하나씩 받고, 이 맵에서 getTranslations를 호출할 수 있어요. 이를 비동기 헬퍼 하나에 담고, 그 결과를 각 parse의 error 옵션으로 넘기세요. 그러면 스키마에는 규칙만 남고 영어 문장은 사라져서, AI가 생성한 폼이 라트비아어 페이지에 "Invalid email"를 내보내는 일이 없어져요.
404 페이지와 오류 페이지는 어떻게 번역하나요?
app/[locale]/ 안에 not-found.tsx를 두고, 실제로 동작하도록 catch-all을 추가하세요. Next.js는 세그먼트가 notFound()를 호출할 때 이 파일을 렌더링하는데, 알 수 없는 URL은 스스로 호출하지 않아요.
// app/[locale]/[...rest]/page.tsx
import {notFound} from 'next/navigation';
export default function CatchAllPage() {
notFound();
}
next-intl 미들웨어가 매칭하지 않는 요청에는 로케일이 아예 없어서 [locale] 404가 적용되지 않아요. 문서가 안내하는 방법은 app/global-not-found.tsx인데, Next.js 문서에서는 이를 실험적 기능으로 분류하고, 이 파일은 자체 html와 body를 렌더링해요. 알 수 없는 [locale] 값이 들어온 경우에는 문서에 따라 보통 i18n/request.ts에서 notFound()를 호출하세요.
error.tsx는 달라요. Next.js는 이 파일이 Client Component이길 요구하고 레이아웃 아래에서 렌더링되므로, 최소한 Error 네임스페이스를 담은 NextIntlClientProvider가 필요해요. 카탈로그 전체가 아니라 해당 메시지만 넘기세요.
// app/[locale]/layout.tsx (excerpt)
const messages = await getMessages();
// ...
<NextIntlClientProvider locale={locale} messages={pick(messages, 'Error')}>
그러면 error.tsx 안에서 useTranslations('Error')가 동작해요. 이 페이지는 global-error를 다루지 않으니, 해당 파일이 있다면 직접 확인하세요.
공유 이미지, manifest, sitemap은 어떻게 하나요?
이들은 레이아웃 트리 바깥에 있어서 모두 로케일을 직접 넘겨야 해요. opengraph-image.tsx에서는 params에서 locale를 읽고 getTranslations({locale, namespace})를 호출하세요. localePrefix를 커스터마이징했다면, Next.js가 프록시(미들웨어) 리라이트를 인식하지 못해 생성된 라우트에 접근할 수 없게 될 수 있다고 문서가 경고해요. 해결책은 matcher가 opengraph-image로 끝나는 경로를 건너뛰게 하는 거예요.
app/manifest.ts는 [locale] 바깥에 있어서 next-intl이 경로에서 로케일을 추론할 수 없어요. 보통 기본 로케일처럼 대표 로케일 하나를 골라 직접 넘기세요. sitemap.ts에서는 alternates.languages 항목을 추가하고, 내비게이션 모듈의 비동기 getPathname({locale, href})로 각 URL을 만든 뒤 호스트를 앞에 붙이세요. next-intl은 기본적으로 언어별 버전을 알리는 link 응답 헤더도 보내요. CMS에서 오는 슬러그를 직접 제어해야 한다면 sitemap을 쓰세요.
Route Handler는 어떻게 처리하나요?
검색 파라미터, 세그먼트, 또는 accept-language 헤더에서 로케일을 가져와 hasLocale(routing.locales, locale)로 검증하고, 실패하면 400을 반환하세요. 그다음 getTranslations({locale, namespace})를 호출하세요. 검증을 건너뛰면 임의의 문자열이 카탈로그 조회까지 도달해요.
에이전트가 남긴 영어는 어떻게 찾나요?
프로젝트 루트에서 실행하세요. 정밀하지 않게 의도적으로 단순하게 만든 명령이에요. 점수를 내는 게 아니라 읽어볼 목록을 얻는 게 목적이에요.
# 1. Static metadata that cannot be translated
grep -rn "export const metadata" app
# 2. Titles and descriptions already in generateMetadata
grep -rn "title:" app --include=page.tsx --include=layout.tsx
# 3. Server Actions with literal return messages
grep -rln "use server" app src 2>/dev/null | xargs grep -n "message:\|error:"
# 4. Zod schemas with inline messages
grep -rn "message:\s*['\"]" app src 2>/dev/null
# 5. 404 and error files, and whether a catch-all exists
ls app/\[locale\]/not-found.tsx app/\[locale\]/error.tsx "app/[locale]/[...rest]/page.tsx" 2>&1
처음 네 개의 결과 중 평범한 영어 리터럴이 있다면 카탈로그에 넣어야 해요. 이런 일이 되풀이되는 이유는 에이전트가 하드코딩된 문자열을 계속 추가하는 이유에서 설명해요. 에이전트는 눈에 보이는 패턴을 따르는데, 그 패턴이 바로 컴포넌트이기 때문이에요. Copilot을 쓴다면 Copilot의 지침 파일 한계도 여기에 적용돼요.
이게 카탈로그에는 어떤 변화를 줄까요?
키가 늘어나는데, 어긋남은 바로 키에서 시작돼요. 위의 모든 항목은 Metadata, Error, Subscribe, 유효성 검사 메시지 같은 새 항목을 카탈로그에 추가하고, 각 항목은 출시하는 모든 로케일에 번역이 필요해요. 컴포넌트를 한 번 번역한 뒤 Server Action이나 새 페이지 제목을 추가하는 프로젝트가 바로 번역 파일이 어긋나는 이유에서 설명한 그 프로젝트예요.
next-intl은 런타임에 번역을 제공하고, 우리는 이를 대체하지 않아요. globalize.now는 한 계층 위에 있어요. 앱에서 저장소를 연결하면 코드베이스가 한 번 카탈로그로 변환되고, 이후 푸시 작업이 새로 생긴 카탈로그 단위를 번역해 검토할 수 있는 변경으로 전달해요. 설정은 Next.js 연동에, 이미 next-intl을 직접 연결해 둔 경우는 기존 i18n 설정에서 건드리는 부분과 건드리지 않는 부분에 있어요.
시작하는 방법
grep 다섯 개를 실행하고, 정적 metadata export를 바꾸고, catch-all 라우트를 추가하고, error.tsx에 provider를 추가하세요. 그다음 모든 로케일의 카탈로그에 새 네임스페이스가 있는지 확인하세요. AI로 만든 앱을 배포했고 변환과 번역을 직접 관리하는 대신 맡기고 싶다면, 개요는 vibe coder 페이지에, 에이전트 설정은 개발자 레퍼런스에 있고, 요금은 별도 페이지에 있어요.
globalize.now는 하드코딩된 앱 문구를 번역할 수 있는 로케일 파일로 바꾸고, 배포할 때마다 최신 상태로 유지해요.
globalize.now 무료로 시작하기