서버 렌더링과 하이드레이션
요청에 사용할 로캘과 카탈로그를 정하고, 브라우저에서 페이지를 하이드레이션할 때도 같은 렌더링 입력값을 유지하세요.
서버에서 렌더링한 페이지에는 브라우저에 도착하기 전부터 사용자에게 보여 줄 메시지가 담겨 있습니다. 하이드레이션은 이 HTML에 리액트를 연결하는 과정입니다. 서버와 브라우저에서 렌더링할 때는 로캘, 카탈로그, 값이 모두 같아야 합니다. 그렇지 않으면 브라우저가 올바른 번역을 원문으로 바꾸거나 불일치를 보고할 수 있습니다.
렌더링하기 전에 지원되는 로캘을 정하고 해당 카탈로그를 불러오세요. 이 둘을 프레임워크의 데이터 전달 방식으로 클라이언트에 전달하세요. 정적 내보내기를 사용할 때도 로캘별 빌드 결과물에 같은 규칙이 적용됩니다.
하나의 상태로 페이지 구성하기 #
이 로컬 테스트 예제를 실행하려면 리액트 19가 필요합니다. 미리 정해진 카탈로그와 고정된 타임스탬프를 사용해 스페인어 제목을 렌더링합니다. 설치 방법은 리액트 빠른 시작을 참고하세요:
import { renderToStaticMarkup } from "react-dom/server";
import { computeKey, createLingo, LingoProvider, useLingo } from "@lingo.dev/react";
const state = {
locale: "es",
messages: {
[computeKey("Hello, {name}.", "Greeting on the account dashboard")]:
"Hola, {name}.",
},
name: "Ana",
updatedAt: Date.parse("2026-10-10T12:00:00Z"),
};
function Page({ name, updatedAt }: { name: string; updatedAt: number }) {
const l = useLingo();
return (
<main>
<h1>{l.text("Hello, {name}.", {
context: "Greeting on the account dashboard",
values: { name },
})}</h1>
<time dateTime={new Date(updatedAt).toISOString()}>
{l.datetime(updatedAt, { timeZone: "UTC" })}
</time>
</main>
);
}
const l = createLingo(state.locale);
const html = renderToStaticMarkup(
<html lang={l.locale} dir={l.direction}>
<body>
<LingoProvider locale={state.locale} messages={state.messages}>
<Page name={state.name} updatedAt={state.updatedAt} />
</LingoProvider>
</body>
</html>,
);제목은 Hola, Ana.이고, 문서에는 lang="es" 및 dir="ltr"이 있습니다. 고정된 시점과 명시적으로 지정한 시간대를 사용하므로 날짜 입력값을 재현할 수 있습니다. 이 테스트 예제는 정적 마크업을 생성합니다. 상호작용이 가능한 애플리케이션에서는 renderToStaticMarkup 대신 프레임워크의 하이드레이션 경로를 사용하세요.
같은 입력값을 클라이언트에 전달하기 #
프레임워크의 직렬화 방식으로 브라우저에 동일한 state을 전달하세요. Messages은 단순한 문자열 맵이므로 다른 페이지 데이터와 함께 전달할 수 있습니다. 이스케이프 처리하지 않은 <script> 문자열을 이어 붙여 JSON을 삽입하지 말고, 프레임워크의 안전한 데이터 전송 방식을 사용하세요.
다음 입력값을 일치시키세요:
| 입력값 | 불일치 시 달라지는 항목 |
|---|---|
| 원문과 문맥 | 계산된 카탈로그 키. 호출 코드와 카탈로그는 서로 호환되는 리비전으로 배포하세요. |
| 로캘과 카탈로그 | 문법, 번역된 템플릿, 값의 표시 형식. |
| 플레이스홀더 값 | 화면에 표시되는 이름, 개수 또는 기타 데이터. |
| 타임스탬프와 시간대 | 표시되는 시간과, 경우에 따라 달력상의 날짜. |
| 상대 시간의 기준 시점 | 하이드레이션 중 표시되는 시간 차이. 현재 시각을 두 번 따로 읽는 대신 처음 사용한 기준 시점을 재사용하세요. |
입력값이 같아도 내장 Intl 데이터는 서버와 브라우저에서 다를 수 있습니다. 지원 환경에서 대표적인 값을 확인하세요. 하이드레이션이 끝난 뒤에는 애플리케이션에서 시간에 따라 달라지는 표시를 정상적으로 갱신할 수 있습니다.
프레임워크의 로딩 경계 사용하기 #
넥스트 페이지 라우터 활용 예제는 메시지를 __lingoMessages에 불러오고 withLingoApp을 통해 전달합니다. 이 패키지에서 내보내는 /pages, /pages/client, /pages/server은 페이지 라우터 전용입니다. 루트 경로에서 가져오는 방식이나 앱 라우터 활용 예제는 이 패키지에 포함되어 있지 않습니다.
탠스택 스타트 활용 예제는 { locale, messages }을 라우트 컨텍스트에 넣고, 이 컨텍스트를 바탕으로 루트 프로바이더와 문서 속성을 렌더링합니다. 해당 요청이 처리되는 동안 카탈로그는 바뀌지 않습니다. 언어 전환기는 다른 카탈로그를 불러올 때 전체 요청을 새로 보냅니다.
어느 방식을 사용하든 초기 HTML을 살펴본 뒤 애플리케이션에서 하이드레이션하세요. 번역된 제목이 그대로 유지되고 불일치 진단이 나타나지 않는지 확인하세요. 정적 렌더링 테스트로 서버의 결과는 확인할 수 있지만, 하이드레이션의 성공 여부까지 검증할 수는 없습니다.
언어별 주소를 별도로 확인하기 #
제목이 올바르게 표시된다고 해서 언어를 전환할 때 올바른 페이지로 이동한다는 보장은 없습니다. 쿼리 매개변수와 프래그먼트를 포함해 선택한 어댑터의 주소 처리 동작을 테스트하고, 이어지는 요청에서 그에 맞는 카탈로그를 불러오는지 확인하세요. 접두사와 주소 정규화 정책에는 locale-router를 사용하세요. 대체 언어의 절대 주소도 확인하세요. 넥스트의 도우미는 대체 언어 주소를 출력하고, 탠스택의 도우미는 표준 주소와 오픈 그래프 메타데이터도 출력합니다.