TanStack Start v1에서 로케일 기반 라우팅을 구현하는 방법

문제

다국어 애플리케이션을 구축할 때, 모든 것을 좌우하는 하나의 근본적인 결정이 있습니다: 애플리케이션이 어떤 언어를 표시할지 어떻게 알 수 있을까요? 명시적인 메커니즘이 없다면, /about이라는 URL은 모호해집니다—어떤 언어의 콘텐츠든 나타낼 수 있기 때문입니다. 사용자는 특정 언어 버전의 링크를 공유할 수 없고, 검색 엔진은 어떤 버전이 어떤 대상에게 속하는지 이해하기 어렵습니다. 이러한 모호성은 사용자 경험과 SEO 모두에 문제를 일으킵니다. 동일한 콘텐츠의 언어 변형을 구분할 수 있는 명확한 방법이 없기 때문입니다.

해결책

URL 경로에 직접 언어 식별자를 넣습니다. 예를 들어 /en/about 또는 /fr/about과 같이 말입니다. 이렇게 하면 모든 경로가 특정 언어에 고유하게 되어 사용자와 검색 엔진 모두에게 모호함이 사라집니다. 라우트 구조에 로케일 매개변수를 사용함으로써 각 URL은 자체 설명적이고 공유 가능해집니다. 사용자는 선호하는 언어로 된 콘텐츠의 링크를 북마크하거나 공유할 수 있으며, 검색 엔진은 각 언어 변형을 적절히 색인화할 수 있습니다.

단계

1. 로케일 레이아웃 라우트 생성하기

로케일 매개변수가 선택적인 유연한 라우팅 패턴을 만들기 위해 {-$locale} 구문을 사용하여 선택적 로케일 매개변수를 정의합니다. TanStack Start는 src/routes 디렉토리에서 라우트가 정의되는 파일 기반 라우팅을 사용합니다.

import { createFileRoute, Outlet } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}")({
  component: LocaleLayout,
});

function LocaleLayout() {
  return <Outlet />;
}

이 라우트는 /about(로케일이 정의되지 않음)과 /en/about(로케일이 "en") 모두에 일치하여 로케일 접두사가 있거나 없는 URL을 지원할 수 있게 합니다.

2. 로케일 레이아웃 아래에 하위 라우트 생성하기

TanStack Router는 중첩 라우팅을 사용하여 URL을 올바른 컴포넌트 트리와 매칭하여 렌더링합니다. 로케일 파라미터의 하위 항목으로 라우트 파일을 생성하여 URL에서 로케일을 상속받을 수 있습니다.

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}/about")({
  component: AboutPage,
});

function AboutPage() {
  const { locale } = Route.useParams();
  const currentLocale = locale || "en";

  return (
    <div>
      <h1>About Us</h1>
      <p>Current locale: {currentLocale}</p>
    </div>
  );
}

라우트 파일 구조 {-$locale}/about.tsx는 /about과 /en/about과 같은 경로를 생성하며, 두 경로 모두 로케일 파라미터에 접근할 수 있는 동일한 컴포넌트를 렌더링합니다.

3. 컴포넌트에서 로케일 파라미터 접근하기

URL에서 로케일을 읽고 표시할 언어를 결정하기 위해 useParams 훅을 사용하세요.

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}/products")({
  component: ProductsPage,
});

function ProductsPage() {
  const { locale } = Route.useParams();
  const displayLocale = locale || "en";

  return (
    <div>
      <h1>{displayLocale === "fr" ? "Produits" : "Products"}</h1>
    </div>
  );
}

로케일 파라미터가 정의되지 않은 경우, 컴포넌트는 기본 언어로 설정되어 애플리케이션이 로컬라이즈된 URL과 로컬라이즈되지 않은 URL을 모두 처리할 수 있습니다.

4. 로케일을 유지하는 링크 생성하기

현재 언어를 유지하면서 페이지 간 이동을 위해 로케일 파라미터와 함께 Link 컴포넌트를 사용하세요.

import { Link, createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}/")({
  component: HomePage,
});

function HomePage() {
  const { locale } = Route.useParams();

  return (
    <nav>
      <Link to="/{-$locale}/about" params={{ locale }}>
        About
      </Link>
      <Link to="/{-$locale}/products" params={{ locale }}>
        Products
      </Link>
    </nav>
  );
}

params 속성에 현재 로케일을 전달함으로써, 링크는 자동으로 사용자의 현재 언어 컨텍스트와 일치하는 URL을 생성합니다. 예를 들어, 프랑스어 버전을 보고 있을 때 /fr/about과 같은 URL이 생성됩니다.