Next.js 앱 라우터 애플리케이션 번역하기
모든 페이지에 로캘 접두사를 붙여 제공하고, 접두사가 없는 경로는 리디렉션하고, @lingo.dev/react-next로 번역된 서버 및 클라이언트 컴포넌트를 렌더링하세요.
앱 라우터에서는 소스 로캘을 포함한 모든 로캘에 고유한 URL 접두사가 있습니다. 사용자는 /en/pricing와 /de/pricing로 접속합니다. @lingo.dev/react-next는 app/[locale] 라우트 세그먼트에서 로캘을 읽고, 서버에서 해당 로캘의 카탈로그를 불러와 서버 및 클라이언트 컴포넌트에 동일한 메시지를 제공합니다. 이 가이드에서는 영어 애플리케이션에 독일어와 프랑스어를 추가합니다.
Next.js 16 이상과 React 19를 사용하세요. 각 진입점은 next/root-params를 통해 로캘을 읽습니다. 다음 패키지를 설치하세요.
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latest로캘 정의하기 #
app/ 옆에 i18n.ts를 만드세요. 애플리케이션에서 src/를 사용한다면 src/i18n.ts에 만드세요.
import { createLocaleRouter } from "@lingo.dev/locale-router";
export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });
export const localePath = (pathname: string, locale: string) =>
locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);.lingo/config.json에 로캘 목록을 작성하고 소스 로캘을 defaultLocale로 지정하세요. exclude에는 app/api/ 아래의 라우트 핸들러처럼 접두사를 붙이지 않을 경로의 첫 번째 세그먼트를 지정합니다. slugs는 전달하지 마세요. getLingo()가 세그먼트만으로 로캘을 판별하므로 각 로캘의 URL 세그먼트는 해당 태그의 소문자 표기여야 합니다(pt-BR의 경우 /pt-br). 사용자 지정 슬러그를 사용하면 프로바이더에서 해당 슬러그가 명시된 오류가 발생합니다. 프록시, 서버 컴포넌트, 클라이언트 컴포넌트가 모두 이 파일을 가져오므로 이 파일에서는 다른 항목을 가져오지 마세요.
접두사가 없는 경로 리디렉션하기 #
app/ 옆에 proxy.ts를 만드세요.
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";
export const proxy = lingoProxy(locales);
export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };lingoProxy(locales)는 두 가지 유형의 요청을 처리합니다.
| 요청 | 응답 |
|---|---|
/DE/about, /de-AT, /de_DE처럼 첫 번째 세그먼트가 슬러그 이외의 형식으로 로캘을 나타내는 요청 | 표준 주소로 301. |
/about처럼 로캘이 없는 현지화 대상 경로 | Cache-Control: private, no-store 및 Vary: Accept-Language와 함께 Accept-Language를 바탕으로 결정한 로캘로 307. |
| 그 외 모든 요청 | undefined. |
리디렉션 시 쿼리 문자열과 애플리케이션의 basePath는 유지됩니다. Next.js는 빌드 시 매처를 읽으므로 리터럴로 작성하고, 매처의 api를 exclude와 일치시키세요. 애플리케이션에 이미 프록시가 있다면 먼저 lingoProxy를 호출하고, undefined가 반환되면 기존 로직을 계속 실행하세요. middleware.ts는 같은 파일의 이전 이름입니다. 파일 이름을 proxy.ts로, 함수 이름을 proxy로 바꾸세요.
라우트를 로캘 아래로 이동하기 #
루트 레이아웃과 모든 페이지를 한 단계 아래 폴더인 app/[locale]/로 이동하세요. app/[locale]/layout.tsx가 루트 레이아웃이 되며, 이동 후에는 app/layout.tsx가 남아 있지 않아야 합니다. app/api/ 아래의 라우트 핸들러, globals.css, 아이콘, robots.ts, sitemap.ts는 기존 위치에 그대로 둡니다. next.config에 i18n 키가 있다면 제거하세요. 앱 라우터는 이 키를 읽지 않습니다.
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";
export function generateStaticParams() {
return lingoStaticParams(locales);
}
export default async function RootLayout({ children }: { children: ReactNode }) {
const l = await getLingo();
return (
<html lang={l.locale} dir={l.direction}>
<body>
<LingoAppProvider locales={locales}>{children}</LingoAppProvider>
</body>
</html>
);
}lingoStaticParams는 로캘마다 { locale }를 하나씩 반환하므로 빌드 시 모든 페이지가 로캘별로 한 번씩 사전 렌더링됩니다. LingoAppProvider는 목록에 없는 로캘에 대해 404를 반환합니다. export const dynamicParams = false는 추가하지 마세요. cacheComponents가 활성화되어 있으면 Next.js에서 이를 허용하지 않습니다.
서버 및 클라이언트 컴포넌트 번역하기 #
서버 컴포넌트, 페이지, 레이아웃, generateMetadata는 @lingo.dev/react-next/app/server에서 가져온 await getLingo()를 호출합니다. 클라이언트 컴포넌트는 @lingo.dev/react에서 가져온 useLingo()를 호출하며, LingoAppProvider가 로캘과 카탈로그를 제공합니다. 어느 쪽도 로캘을 하위 컴포넌트로 전달할 필요가 없습니다.
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";
export default async function Home() {
const l = await getLingo();
return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}서버 컴포넌트는 부모 서버 컴포넌트에서 l를 속성으로 받을 수 있습니다. 다만 l를 클라이언트 컴포넌트에 전달해서는 안 됩니다. 함수는 서버에서 클라이언트로 전달할 수 없기 때문입니다. app/[locale]/ 밖에서 getLingo()를 호출하면 [locale] 세그먼트를 찾을 수 없어 오류가 발생합니다.
메타데이터 추가하기 #
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
export async function generateMetadata() {
const l = await getLingo();
return {
title: l.text("Pricing", { context: "Title of the pricing page" }),
...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
};
}lingoMetadata({ locales, pathname, origin, ogLocale? })는 alternates.canonical, 각 로캘의 alternates.languages에 더해 x-default, 그리고 openGraph.url와 openGraph.locale를 반환합니다. 로캘 접두사, 쿼리, 해시를 제외한 페이지 경로를 전달하세요. 동적 라우트에서는 매개변수로 이 경로를 구성합니다. 예시의 오리진을 사이트의 오리진으로 바꾸세요. 로캘 URL 정책에서는 이 값들을 구성하는 lingoHead와 ogLocale 재정의를 설명합니다.
링크 연결 및 언어 전환하기 #
i18n.ts에서 가져온 localePath("/pricing", l.locale)로 모든 내부 링크에 접두사를 붙이세요. l.locale는 일반 문자열이므로 localePath로 라우터의 로캘 중 하나로 범위를 좁힌 다음 locales.prefix로 접두사를 추가합니다. 접두사가 없는 링크는 프록시로 전달되며, 프록시는 페이지 언어가 아닌 브라우저 언어로 리디렉션합니다. redirect(), router.push(), 경로를 지정하는 폼 액션에도 동일하게 적용됩니다.
"use client";
import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";
export function LocaleSwitcher() {
const options = useLocaleSwitch(locales);
return (
<nav aria-label="Language">
{options.map((option) => (
<Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
{option.label}
</Link>
))}
</nav>
);
}useLocaleSwitch(locales)는 로캘마다 { locale, label, href, current }를 하나씩 반환합니다. 여기에는 해당 로캘의 현재 페이지, 해당 언어로 표기한 언어 이름, 현재 선택된 로캘인지 여부가 담깁니다. 쿼리 문자열은 하이드레이션 후에 추가되므로 언어 전환기를 렌더링하는 페이지도 정적으로 유지됩니다. 링크로 이동하면 레이아웃이 다시 렌더링되면서 새 로캘의 카탈로그를 불러옵니다.
카탈로그 추출 및 불러오기 #
서버는 fs를 사용해 next가 실행되는 폴더에서 locales/<locale>.jsonc를 읽으므로 i18n.messagesPath를 기본값인 locales로 유지하세요. 더 이상 참조되지 않는 항목은 제외하고 요청마다 파일을 다시 읽으므로 next dev는 바로 다음 요청부터 수정된 카탈로그를 제공합니다. 파일이 없으면 빈 카탈로그를 사용하며, 개발 환경에서는 경고를 표시합니다. 파일 형식이 잘못되었거나 문자열이 아닌 값이 있으면 파일 이름이 명시된 오류가 발생합니다. 프로덕션에서는 소스 로캘의 텍스트가 대체 텍스트로 사용되므로 해당 로캘의 카탈로그를 브라우저로 보내지 않습니다.
src/ 폴더 없이 app/가 프로젝트 루트에 있다면, 추출 시 app/와 components/를 검색하도록 .lingo/config.json에서 "i18n": { "src": "." }를 설정하세요. 추출 시 node_modules와 .next처럼 점으로 시작하는 폴더는 건너뜁니다. 새로 구성하려면 다음을 실행하세요.
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitinit는 i18n 섹션을 다시 작성하므로 실행 후에 i18n.src를 설정하세요. 모노레포에서는 .lingo/config.json가 저장소 루트에 있고 경로도 그 위치를 기준으로 합니다. 따라서 messagesPath는 apps/web/locales처럼 앱 폴더에 locales를 더한 경로가 됩니다. CLI 구성에서 이름이 지정된 앱의 i18n 맵을 참고하세요. 서버는 여전히 앱 자체 폴더에서 locales/를 읽습니다.
next build와 next start를 실행한 후 /를 열어 로캘로 리디렉션되는지 확인하세요. 이어서 /de를 열어 HTML에 독일어 텍스트가 있는지 확인하세요.
런타임 #
사전 렌더링된 페이지는 어떤 호스트에서든 작동합니다. 요청 시 렌더링되는 페이지는 디스크에서 카탈로그를 읽으므로 Node.js 런타임이 필요합니다. Cloudflare Workers와 에지 런타임에서는 카탈로그를 읽을 수 없습니다.
내보내기 #
| 진입점 | 내보내는 항목 |
|---|---|
@lingo.dev/react-next/app/server | getLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales). |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales) 및 LocaleOption 타입. |
@lingo.dev/react-next/app/proxy | lingoProxy(locales). |
패키지를 설치하면 코딩 에이전트가 lingo agent-guide react-next-app의 안내를 따를 수 있습니다. next-intl에서 마이그레이션할 때는 lingo agent-guide react-next-migrate의 안내를 따를 수 있습니다. 코딩 에이전트로 설정하기를 참고하세요.