TanStack Start 애플리케이션 번역하기

로캘 접두사가 붙은 요청을 처리하고 해당 카탈로그를 불러온 뒤, 표준 URL과 언어 전환기를 갖춘 번역 페이지를 렌더링합니다.

/about 같은 애플리케이션 경로는 언어와 무관하게 유지하면서 사용자는 /en/about 또는 /de/about로 접속하게 하세요. @lingo.dev/react-tanstack는 이 URL 정책을 요청 컨텍스트 및 카탈로그와 연결합니다. 경로는 여전히 /about와 일치하며, 요청의 로캘에 따라 메시지와 해당 경로에서 생성되는 URL이 결정됩니다.

이 가이드에서는 React 19, TanStack Router 1.170 이상, Start 1.168 이상을 사용하는 기존 TanStack Start 애플리케이션에 영어와 독일어를 추가합니다. Start는 선택적 피어 의존성으로 선언되어 있지만, 패키지의 루트 모듈에서 Start의 createIsomorphicFn를 가져옵니다. 일반 Router 애플리케이션에서 URL을 명시적으로 제공하더라도 Start를 어댑터와 함께 설치하세요.

로캘 정책과 카탈로그 정의하기 #

패키지를 설치하세요.

sh
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-tanstack@1.17.1 @lingo.dev/locale-router@0.2.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latest

카탈로그 불러오기에 나오는 loadMatchedMessages 함수를 src/catalog.ts로 추가하세요. 그런 다음 src/i18n.ts를 만드세요.

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";
import type { Catalog } from "@lingo.dev/react-tanstack";
import source from "../locales/en.jsonc?raw";
import { loadMatchedMessages } from "./catalog";

export const locales = createLocaleRouter(["en", "de"] as const, {
  defaultLocale: "en",
  exclude: ["api", "assets"],
});

const targets = import.meta.glob<string>("../locales/*.jsonc", {
  query: "?raw",
  import: "default",
});

export const catalog: Catalog = async (locale) => {
  const load = targets[`../locales/${locale}.jsonc`];
  if (!load) throw new Error(`Missing catalog for ${locale}`);
  return loadMatchedMessages(source, await load());
};

이 Vite 로더는 원본 파일을 검증하고 대응하는 영어 소스에서 활성 키를 선택합니다. 따라서 주석이 없는 번역 결과에서도 더 이상 쓰이지 않는 키가 다시 활성화되지 않습니다. 파일이 없거나 형식이 잘못되면 아무 경고 없이 빈 맵을 제공하는 대신 오류를 발생시킵니다. 아래 추출 단계에서는 애플리케이션이 시작되기 전에 가져올 소스 파일을 생성합니다.

라우터 생성 전에 요청 처리하기 #

기존 미들웨어는 그대로 두고 src/start.ts에 접두사 없는 경로를 처리할 미들웨어를 등록하세요.

ts
import { createStart } from "@tanstack/react-start";
import { localeMiddleware } from "@lingo.dev/react-tanstack/server";
import { locales } from "./i18n";

export const startInstance = createStart(() => ({
  requestMiddleware: [localeMiddleware(locales)],
}));

src/router.tsx에서 요청 처리로 결정된 로캘과 메시지를 라우터 컨텍스트로 사용하세요.

tsx
import { createRouter } from "@tanstack/react-router";
import { lingoContext, localeRewrite } from "@lingo.dev/react-tanstack";
import { routeTree } from "./routeTree.gen";
import { catalog, locales } from "./i18n";

export async function getRouter() {
  const state = await lingoContext(locales, catalog);
  return createRouter({
    routeTree,
    context: state,
    rewrite: localeRewrite(locales, state.locale),
  });
}

declare module "@tanstack/react-router" {
  interface Register {
    router: Awaited<ReturnType<typeof getRouter>>;
  }
}

애플리케이션의 다른 라우터 설정은 유지하세요. lingoContext는 인식된 URL 접두사를 사용하고, 인식된 접두사가 없으면 기본 로캘을 사용합니다. 서버에서는 요청 URL을, 브라우저에서는 location.href를 읽습니다. 선택 사항인 세 번째 인수 URL로 이 입력을 명시할 수도 있습니다. 이 함수 자체는 언어 수락 헤더를 통한 언어 협상을 수행하지 않습니다. 조건에 맞는 접두사 없는 경로 요청은 미들웨어가 언어 협상을 수행한 뒤 302 리디렉션으로 응답합니다.

localeRewrite는 경로를 매칭할 때 인식된 접두사를 제거하고, 생성되는 경로 중 조건에 맞는 경로에는 요청 로캘을 추가합니다. 경로 정의에는 접두사를 붙이지 말고, 위와 같이 API 및 정적 자산 경로는 로컬라이제이션에서 제외하세요.

요청 컨텍스트로 루트 렌더링하기 #

src/routes/__root.tsx에서 프레임워크 셸을 유지하면서 프로바이더를 제공하세요.

tsx
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";

type LocaleContext = { locale: "en" | "de"; messages: Messages };

export const Route = createRootRouteWithContext<LocaleContext>()({
  component: Outlet,
  shellComponent: ({ children }) => {
    const { locale, messages } = Route.useRouteContext();
    return (
      <html lang={locale} dir={createLingo(locale).direction}>
        <head>
          <HeadContent />
        </head>
        <body>
          <LingoProvider locale={locale} messages={messages}>
            {children}
          </LingoProvider>
          <Scripts />
        </body>
      </html>
    );
  },
});

이제 텍스트, 서식, 문서 속성에 동일한 컨텍스트가 적용됩니다. 하이드레이션 중에도 이 컨텍스트를 유지하세요. 메시지를 빈 클라이언트 맵으로 바꾸면 렌더링된 페이지가 달라집니다.

번역 페이지와 헤드 메타데이터 추가하기 #

src/routes/about.tsx를 만드세요.

tsx
import { createFileRoute } from "@tanstack/react-router";
import { useLingo } from "@lingo.dev/react";
import { getLingo, lingoHead } from "@lingo.dev/react-tanstack";
import { locales } from "../i18n";

export const Route = createFileRoute("/about")({
  head: (options) => {
    const l = getLingo(options);
    const localized = lingoHead({
      router: locales,
      locale: options.match.context.locale,
      pathname: options.match.pathname,
      origin: "https://example.com",
    });
    return {
      meta: [{ title: l.text("About us", { context: "About page title" }) }, ...localized.meta],
      links: localized.links,
    };
  },
  component: About,
});

function About() {
  const l = useLingo();
  return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}

예시 오리진을 신뢰할 수 있는 사이트 오리진으로 바꾸세요. head에서 추출 대상 호출에 앞서 const l = getLingo(options)를 바인딩하세요. getLingo(options).text(...)를 연쇄 호출하는 방식은 지원되는 추출 패턴이 아닙니다.

헤드 메타데이터 #

lingoHead는 각 로캘의 표준 링크와 대체 링크, x-default, og:url/og:locale를 담은 { meta, links }를 반환합니다. 접두사, 쿼리, 해시가 없는 경로명을 제공하세요. 이 정책에서 독일어 /about의 표준 URL은 https://example.com/de/about이며, 기본 영어 대체 URL은 /en/about입니다.

이 헬퍼는 루트가 아닌 경로의 끝에서 슬래시 하나를 제거합니다. 오픈 그래프 로캘은 de_DE처럼 언어와 지역 정보를 최대한 확장한 값에서 도출됩니다. 선택 사항인 ogLocale 재정의로 플랫폼별 표기 차이를 처리할 수 있습니다. LingoHead는 결과 타입이며, Next 어댑터의 JSX 컴포넌트가 아닙니다.

카탈로그 추출 및 가져오기 #

npx lingo extract --src src --source-locale en를 실행하세요. 새 구성이라면 대상 de를 지정해 locales/en.jsonc를 초기화하세요. 그런 다음 인증을 완료하고 로컬라이제이션 엔진을 연결한 뒤 첫 번째 대상 카탈로그를 가져오세요.

sh
npx lingo init --source en --targets de --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

기존 구성이라면 바인딩과 고급 설정을 유지하세요. 추출 후 기존 대상의 일반 업데이트를 완료하고, 가져온 결과를 확인하세요. 그런 다음 소스 리비전을 고정한 상태에서 de를 추가하고 누락분을 채우세요. 이 경우에는 카탈로그 불러오기와 언어 추가 절차를 따르세요. locales/en.jsonc와 사용하려는 locales/de.jsonc가 모두 준비된 뒤에만 애플리케이션을 시작하세요. /en/about와 /de/about에 접속해 본문 제목과 페이지 제목을 살펴보고, 각각의 표준 URL과 대체 URL을 확인하세요.

새 요청으로 언어 전환하기 #

tsx
import { useLocaleSwitch } from "@lingo.dev/react-tanstack";
import { locales } from "./i18n";

export function Languages() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <a key={option.locale} href={option.href} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </a>
      ))}
    </nav>
  );
}

이 컴포넌트를 src 아래에 배치하고 라우팅되는 애플리케이션 안에서 렌더링하세요. 각 옵션에는 locale, 해당 언어로 표기한 언어 이름인 label, href, current가 포함됩니다. 일반 앵커 링크는 새 요청을 보내 해당 로캘의 카탈로그를 불러옵니다. 클라이언트 전용 경로 링크를 사용하면 이전 요청의 메시지가 남을 수 있습니다. 언어 전환기는 쿼리와 해시를 유지하며, 선택 가능한 언어에서 x-default를 제외합니다.

내장 카탈로그 및 서버 헬퍼 #

createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" })는 메타데이터를 그대로 사용할 수 있는 파일을 위해 캐시된 Catalog를 제공합니다. 각 모듈은 문자열 default 내보내기가 있는 객체로 해석되어야 합니다. 이 헬퍼는 해당 파일에서 더 이상 쓰이지 않는 키를 걸러내고 로캘마다 프로미스 하나를 캐시합니다. 모듈이 없거나 로딩 또는 파싱 오류가 발생하면 {}를 반환합니다. sourceLocale를 설정하면 프로덕션에서 해당 로캘의 파일을 건너뛰고 소스를 대체값으로 사용합니다. 문자열 값으로 이루어진 평면 구조 검증, 경로별 필터링, 손실된 메타데이터 복원은 수행하지 않습니다. 번역된 JSONC에 이러한 처리가 필요하면 위의 소스 결합 로더를 사용하세요.

서버 진입점은 localeMiddleware와 canonicalSearch를 내보냅니다. 미들웨어는 검색 매개변수를 유지하되 TanStack의 기본 방식으로 다시 직렬화합니다. 서버 요청에는 브라우저 해시가 없습니다. 이미 접두사가 붙어 있거나, 제외 대상이거나, 별도의 표준화 처리 대상인 경로는 next()로 전달됩니다. 접두사와 표준화의 정확한 동작은 로캘 라우터를 참고하세요.

일반 TanStack Router 애플리케이션은 루트 패키지의 Start 의존성을 유지하면서 lingoContext에 URL를 제공하고 자체 리디렉션을 구현할 수 있습니다. 이 가이드의 미들웨어와 요청 셸은 Start 전용입니다.