넥스트 제이에스 페이지 애플리케이션 번역하기
페이지의 번역 메시지를 불러와 페이지 래퍼로 렌더링하고, 로캘 전환과 대체 언어 링크를 추가하세요.
넥스트 제이에스 페이지 라우트는 요청에 사용할 로캘을 이미 결정합니다. @lingo.dev/react-next는 이 로캘에 맞는 리액트 메시지를 제공해 페이지 데이터와 번역문을 함께 관리할 수 있게 합니다. 이 예제에서는 소개 페이지를 영어와 프랑스어로 렌더링하고, 번역된 제이슨씨에서 메타데이터가 사라져도 라우트에 맞는 메시지가 선택되도록 합니다.
리액트 19를 사용하는 기존 페이지 애플리케이션을 준비하세요. 패키지는 넥스트 제이에스 13 이상과 리액트 18/19를 피어 의존성으로 선언하지만, 현재 런타임 공급자는 리액트 19의 컨텍스트 축약 문법을 사용합니다. 내보내는 항목은 /pages, /pages/client, /pages/server이며, 루트 내보내기나 앱 라우터 진입점은 없습니다.
로캘과 앱 래퍼 구성하기 #
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latest기존 next.config.mjs의 다른 설정은 유지하면서 국제화 설정을 추가하세요.
export default {
i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};pages/_app.tsx에서 애플리케이션을 래퍼로 감싸세요.
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";
function App({ Component, pageProps }: AppProps) {
const { locale, defaultLocale } = useRouter();
useEffect(() => {
document.documentElement.lang = locale ?? defaultLocale ?? "en";
}, [locale, defaultLocale]);
return <Component {...pageProps} />;
}
export default withLingoApp(App);래퍼는 pageProps.__lingoMessages를 읽고 넥스트의 활성 로캘을 결정한 뒤 LingoProvider를 제공합니다. 주소 정책은 넥스트 자체의 국제화 설정에 따라 결정되며, 기본 영어 경로에는 보통 접두사가 붙지 않습니다.
페이지 작성하고 메시지 불러오기 #
먼저 카탈로그 불러오기의 loadMatchedMessages 함수를 lib/catalog.ts로 추가하세요. 이 함수는 제이슨씨의 값이 문자열인지 검증하고, 대상 언어의 값을 활성 소스 키에 연결합니다.
그런 다음 pages/about.tsx를 만드세요.
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";
export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
if (!["en", "fr"].includes(locale)) return { notFound: true };
const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
const target =
locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
const messages = loadMatchedMessages(source, target, (entry) => {
const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
});
return { props: { __lingoMessages: messages } };
};
export default function About() {
const l = useLingo();
return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}이 판별 함수는 페이지 자체의 항목과 공유 컴포넌트의 메시지를 유지합니다. 소스 메타데이터에서는 확장자와 이전 형식의 줄 번호 접미사를 제거합니다. 페이지가 src/pages/about.tsx에 있다면 가져오기 경로와 라우트 비교 조건을 모두 그에 맞게 수정하세요.
사용자 정의 로더는 필수 파일이 없거나 형식이 잘못되면 의도적으로 실패하도록 설계되어 있습니다. 따라서 빌드 과정에서 필요한 프랑스어 카탈로그가 아무런 알림 없이 영어 폴백으로 대체되는 일을 막습니다. 개별 대상 키가 누락된 경우에는 누락 상태를 유지하고 일반적인 런타임 폴백을 적용합니다.
추출하고 번역한 뒤 두 라우트 열기 #
프로젝트 루트에서 npx lingo extract --src pages --source-locale en를 실행하세요. 새 Lingo.dev 프로젝트를 구성하려면 다음을 실행하세요.
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait이미 구성된 프로젝트라면 기존 연결과 기타 파일 옵션을 유지하세요. 추출 후에는 기존 대상 로캘의 업데이트를 평소대로 완료하고 결과를 가져와 확인하세요. 그런 다음 fr를 추가하고, 해당 소스 리비전을 변경하지 않은 상태에서 누락분을 채우세요. 구성 단계는 카탈로그 불러오기에서, 필요한 작업 순서는 언어 추가하기에서 확인할 수 있습니다. 공유 컴포넌트가 pages 밖에 있다면 모든 메시지 호출을 포함하는 디렉터리에서 추출하거나, 공통 src 트리 아래에 정리한 뒤 --src src를 사용하세요.
locales/fr.jsonc를 가져온 뒤 평소 사용하는 넥스트 개발 또는 빌드 명령을 실행하세요. /about와 /fr/about를 여세요. 첫 번째는 영어 소스를 사용하고, 두 번째는 같은 제목 키에 프랑스어 번역을 사용합니다. 실제 프랑스어 텍스트와 의도적으로 누락한 항목에 적용되는 소스 폴백을 확인하세요.
내장 정적 프롭 불러오기 #
각 로캘 파일에 올바른 @src 및 @orphan 메타데이터가 유지되어 있다면, 서버 도우미로 위의 사용자 정의 getStaticProps를 대체할 수 있습니다.
import { withLingoProps } from "@lingo.dev/react-next/pages/server";
export const getStaticProps = withLingoProps({ route: "pages/about" });withLingoProps({ route, handler? })는 작업 디렉터리를 기준으로 고정된 locales/<locale>.jsonc 경로에서 파일을 읽습니다. 연결이 끊긴 항목과 다른 페이지의 항목은 걸러내고, 페이지가 아닌 소스와 @src가 없는 항목은 공유 항목으로 취급합니다. 일반적인 제이슨씨 번역은 @orphan 표시는 유지하지만 @src 주석은 제거하므로, 해당 출력에는 위의 소스 키 연결 방식을 사용하세요. 도우미는 메타데이터를 복원하지 않습니다.
파일이 없으면 {}를 반환하고 개발 환경에서는 경고를 표시합니다. 기존 파일이 유효하지 않으면 예외가 발생할 수 있습니다. 선택적으로 지정하는 비동기 처리기는 프롭을 추가하거나 리디렉션 또는 찾을 수 없음 결과를 반환합니다. 성공한 결과는 revalidate 같은 필드를 유지하고 __lingoMessages를 추가합니다. 공개 타입은 정적 프롭 컨텍스트와 결과를 사용하므로, 임의의 서버 측 요청 처리기에도 같은 규약이 적용된다고 가정하지 마세요. CLI 카탈로그 경로를 재정의해도 이 로더의 고정 디렉터리는 바뀌지 않습니다.
동적 라우트의 정적 경로 확장하기 #
동적 라우트에서는 서버 도우미가 각 매개변수 항목을 넥스트에 구성된 모든 로캘에 걸쳐 확장합니다.
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
fallback: "blocking",
});기본 폴백은 "blocking"이며, false와 true도 지원합니다. 이 확장 작업은 슬러그를 번역하지 않으며, 모든 카탈로그에 해당 라우트의 메시지가 있는지 확인하지도 않습니다.
언어 전환하고 대체 언어 링크 추가하기 #
앱 래퍼 아래에 언어 전환기를 렌더링하세요.
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
export function Languages() {
const switchLocale = useLocaleSwitch();
return (
<nav aria-label="Language">
<LingoHead baseUrl="https://example.com" />
<button onClick={() => switchLocale("en")}>English</button>
<button onClick={() => switchLocale("fr")}>Français</button>
</nav>
);
}예제의 오리진을 사이트의 실제 운영 환경에서 사용하는 절대 오리진으로 바꾸세요. LingoHead는 구성된 로캘과 x-default에 대한 대체 링크를 출력하며, 기본 로캘의 접두사는 생략합니다. 대표 주소나 오픈 그래프 메타데이터는 출력하지 않습니다. 생성된 주소가 라우트 및 쿼리 정책에 맞는지 확인하세요.
전환 콜백은 /에 SameSite=Lax를 적용해 NEXT_LOCALE를 유효 기간 1년으로 기록한 뒤, 현재 asPath를 사용해 넥스트 라우터로 이동합니다. 위 예제처럼 구성된 로캘을 전달하세요. 이 콜백은 임의의 입력이 지원 목록에 있는지 검증하지 않습니다.
초기 문서 속성 설정하기 #
기존에 사용자 정의한 문서 설정은 유지하면서 pages/_document.tsx에서 초기 속성을 설정하세요.
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";
export default class LocalizedDocument extends Document {
render() {
const locale = this.props.__NEXT_DATA__.locale ?? "en";
return (
<Html lang={locale} dir={createLingo(locale).direction}>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}withLingoApp는 로캘이 바뀐 뒤 방향을 설정하고, 초기 렌더링을 위해 오른쪽에서 왼쪽으로 표시하는 인라인 스크립트를 출력하지만 lang는 설정하지 않습니다. 위의 _app 효과는 페이지 이동 중 lang를 업데이트하고, 사용자 정의 문서는 두 속성의 초기값을 모두 제공합니다. 엄격한 콘텐츠 보안 정책은 래퍼의 인라인 스크립트를 차단할 수 있으며, 래퍼는 논스 옵션을 제공하지 않습니다. 사용자 정의 문서는 해당 스크립트에 의존하지 않고 초기 방향을 설정합니다. 페이지 이동 중에도 애플리케이션의 스크립트 정책을 확인하세요.
마지막으로 동일한 카탈로그와 명시적으로 지정한 시간 입력값을 사용해 하이드레이션을 확인하세요. 언어를 전환할 때 메시지와 문서 속성이 함께 바뀌는지도 확인하세요.