서버 렌더링과 하이드레이션

요청에 사용할 로캘과 카탈로그를 정하고, 브라우저에서 페이지를 하이드레이션할 때도 같은 렌더링 입력값을 유지하세요.

서버에서 렌더링한 페이지에는 브라우저에 도착하기 전부터 사용자에게 보여 줄 메시지가 담겨 있습니다. 하이드레이션은 이 HTML에 리액트를 연결하는 과정입니다. 서버와 브라우저에서 렌더링할 때는 로캘, 카탈로그, 값이 모두 같아야 합니다. 그렇지 않으면 브라우저가 올바른 번역을 원문으로 바꾸거나 불일치를 보고할 수 있습니다.

렌더링하기 전에 지원되는 로캘을 정하고 해당 카탈로그를 불러오세요. 이 둘을 프레임워크의 데이터 전달 방식으로 클라이언트에 전달하세요. 정적 내보내기를 사용할 때도 로캘별 빌드 결과물에 같은 규칙이 적용됩니다.

하나의 상태로 페이지 구성하기 #

이 로컬 테스트 예제를 실행하려면 리액트 19가 필요합니다. 미리 정해진 카탈로그와 고정된 타임스탬프를 사용해 스페인어 제목을 렌더링합니다. 설치 방법은 리액트 빠른 시작을 참고하세요:

tsx
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를 사용하세요. 대체 언어의 절대 주소도 확인하세요. 넥스트의 도우미는 대체 언어 주소를 출력하고, 탠스택의 도우미는 표준 주소와 오픈 그래프 메타데이터도 출력합니다.