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

문제

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

해결 방법

언어 식별자를 /en/about 또는 /fr/about와 같이 URL 경로에 직접 넣습니다. 이렇게 하면 모든 경로가 특정 언어에 고유하게 되어 사용자와 검색 엔진 모두에 대한 모호성이 제거됩니다. 라우트 구조에 로케일 매개변수를 사용하면 각 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. 로케일을 유지하는 링크 만들기

현재 언어를 유지하면서 페이지 간 이동하려면 locale 매개변수와 함께 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 prop에 현재 로케일을 전달하면 링크가 자동으로 사용자의 현재 언어 컨텍스트와 일치하는 URL을 생성합니다. 예를 들어 프랑스어 버전을 볼 때 /fr/about와 같이 생성됩니다.