본문으로 건너뛰기

국제화 (i18n)

TanStack Router는 선택적 경로 매개변수, 라우트 재작성, 타입 안전 매개변수와 같은 일반적인 국제화(i18n) 라우팅 패턴을 지원하도록 조합할 수 있는 유연하고 고도로 사용자 지정 가능한 프리미티브를 제공합니다. 이를 통해 깔끔하고 SEO 친화적인 URL, 유연한 로캘 처리, i18n 라이브러리와의 원활한 통합을 구현할 수 있습니다.

이 가이드에서는 다음을 다룹니다.

  • 접두사 기반 및 선택적 로캘 라우팅
  • i18n을 위한 고급 라우팅 패턴
  • 언어 탐색 및 전환
  • SEO 고려 사항
  • 타입 안전성
  • i18n 라이브러리(Paraglide)와의 통합 패턴

선택적 경로 매개변수를 사용하는 i18n​

이 패턴은 TanStack Router 기능만 사용합니다. 다음과 같은 경우에 적합합니다.

  • 번역을 완전히 제어하려는 경우
  • 이미 수동으로 번역을 관리하는 경우
  • 로캘 자동 감지가 필요하지 않은 경우

선택적 경로 매개변수는 라우트를 중복하지 않고 로캘 인식 라우팅을 구현하는 데 적합합니다.

/{-$locale}/about

이 단일 라우트는 다음과 일치합니다.

  • /about (default locale)
  • /en/about
  • /fr/about
  • /es/about

접두사 기반 i18n​

// Route: /{-$locale}/about
export const Route = createFileRoute('/{-$locale}/about')({
  component: AboutComponent,
})

function AboutComponent() {
  const { locale } = Route.useParams()
  const currentLocale = locale || 'en'

  const content = {
    en: { title: 'About Us' },
    fr: { title: 'À Propos' },
    es: { title: 'Acerca de' },
  }

  return <h1>{content[currentLocale].title}</h1>
}

복잡한 라우팅 패턴​

// Route: /{-$locale}/blog/{-$category}/$slug
export const Route = createFileRoute('/{-$locale}/blog/{-$category}/$slug')({
  beforeLoad: ({ params }) => {
    const locale = params.locale || 'en'
    const validLocales = ['en', 'fr', 'es', 'de']

    if (params.locale && !validLocales.includes(params.locale)) {
      throw new Error('Invalid locale')
    }

    return { locale }
  },
})

언어 전환​

<Link
  to="/{-$locale}/blog/{-$category}/$slug"
  params={(prev) => ({
    ...prev,
    locale: prev.locale === 'en' ? undefined : 'fr',
  })}
>
  Français
</Link>

타입 안전 로캘​

type Locale = 'en' | 'fr' | 'es' | 'de'

function isLocale(value?: string): value is Locale {
  return ['en', 'fr', 'es', 'de'].includes(value as Locale)
}

i18n 라이브러리 통합 패턴​

TanStack Router는 라이브러리에 종속되지 않습니다. 로캘 상태를 라우팅 동작에 매핑해 어떤 i18n 솔루션이든 통합할 수 있습니다.

다음은 Paraglide를 사용하는 권장 패턴입니다.

라이브러리를 사용하는 클라이언트 측 i18n (TanStack Router)​

이 패턴은 TanStack Router를 클라이언트 측 i18n 라이브러리와 결합합니다. 다음과 같은 경우에 적합합니다.

  • 타입 안전 번역이 필요한 경우
  • 지역화된 URL이 필요한 경우
  • 서버 측 렌더링이 필요하지 않은 경우

TanStack Router + Paraglide (클라이언트 전용)​

Paraglide는 TanStack Router와 자연스럽게 결합되는 타입 안전 번역, 로캘 감지, URL 지역화를 제공합니다.

GitHub 예시: https://github.com/TanStack/router/tree/main/examples/react/i18n-paraglide

프로젝트 설정​

npx @inlang/paraglide-js@latest init
import { paraglideVitePlugin } from '@inlang/paraglide-js'

paraglideVitePlugin({
  project: './project.inlang',
  outdir: './app/paraglide',
})

라우터 재작성을 통한 URL 지역화​

라우터의 rewrite 옵션은 양방향 URL 변환을 활성화하며, 로캘 접두사에 적합합니다. 고급 패턴을 포함한 URL 재작성에 대한 자세한 문서는 URL 재작성 가이드를 참고하세요.

import { deLocalizeUrl, localizeUrl } from './paraglide/runtime'

const router = createRouter({
  routeTree,
  rewrite: {
    input: ({ url }) => deLocalizeUrl(url),
    output: ({ url }) => localizeUrl(url),
  },
})

서버 측 i18n (TanStack Start)​

이 패턴은 라우팅 계층과 서버 계층에 i18n을 통합합니다. 다음과 같은 경우에 적합합니다.

  • TanStack Start를 사용하는 경우
  • SSR 또는 스트리밍이 필요한 경우
  • 로캘 인식 리디렉션과 메타데이터가 필요한 경우

TanStack Start + Paraglide​

GitHub 예시: https://github.com/TanStack/router/tree/main/examples/react/start-i18n-paraglide

서버 미들웨어 (SSR)​

import { paraglideMiddleware } from './paraglide/server'

export default {
  fetch(req: Request) {
    return paraglideMiddleware(req, () => handler.fetch(req))
  },
}

HTML 언어 속성​

import { getLocale } from '../paraglide/runtime'
;<html lang={getLocale()} />

오프라인 안전 리디렉션​

오프라인 또는 클라이언트 전용 환경에서는 다음과 같이 사용합니다.

import { shouldRedirect } from '../paraglide/runtime'

beforeLoad: async () => {
  const decision = await shouldRedirect({ url: window.location.href })
  if (decision.redirectUrl) {
    throw redirect({ href: decision.redirectUrl.href })
  }
}

타입 안전 번역 경로명​

모든 라우트에 번역이 있는지 확인하려면 TanStack Router 라우트 트리에서 번역된 경로명을 직접 파생할 수 있습니다.

import { FileRoutesByTo } from '../routeTree.gen'
import { Locale } from '@/paraglide/runtime'

이를 통해 다음을 보장합니다.

  • 누락된 번역 없음
  • 완전한 타입 안전성
  • 라우팅 오류에 대한 컴파일러 피드백

지역화된 라우트 프리렌더링​

import { localizeHref } from './paraglide/runtime'

export const prerenderRoutes = ['/', '/about'].map((path) => ({
  path: localizeHref(path),
  prerender: { enabled: true },
}))

추가 i18n 통합 패턴​

Intlayer (TanStack Start 통합)​

https://intlayer.org/doc/environment/tanstack-start

use-intl (TanStack Start 통합)​

https://nikuscs.com/blog/13-tanstackstart-i18n/