Chapter 33: Internationalization (i18n)

Core Idea

TanStack Router is library-agnostic for i18n: it provides composable primitives (optional path parameters, URL rewrites, type-safe params) that let you build locale-aware routing yourself, or integrate a dedicated i18n library like Paraglide for translations, locale detection, and URL localization, in both client-only and TanStack Start (SSR) setups.

Key Concepts

• Optional-Parameter Locale Routing: A route like /{-$locale}/about matches /about (default), /en/about, /fr/about, /es/about etc. in a single route definition, avoiding duplicated route trees per locale (see Ch 26 for the underlying {-$param} mechanism).
• Router-Only Approach: Suitable when you want full control over translations, already manage them manually, and don't need automatic locale detection; relies purely on optional params plus manual content maps and locale validation in beforeLoad.
• Type-Safe Locale Guarding: A Locale union type plus a type-guard function (isLocale/validateLocale) used in beforeLoad to reject or redirect on invalid locale segments.
• Language Switching: Implemented via <Link params={(prev) => ({ ...prev, locale: ... })}>, commonly setting locale: undefined for the default language to keep URLs clean (e.g. no /en/ prefix).
• rewrite Router Option for Locale URLs: When using a client-side i18n library (e.g. Paraglide), createRouter({ rewrite: { input, output } }) deLocalizes incoming URLs before matching and re-localizes outgoing URLs, this is the same input/output rewrite mechanism from Ch 22, applied specifically to locale prefixes.
• Paraglide Integration: @inlang/paraglide-js provides type-safe translations and URL localization helpers (localizeUrl, deLocalizeUrl, localizeHref, getLocale, shouldRedirect) that plug into the router's rewrite option (client-only) or server middleware (paraglideMiddleware, TanStack Start SSR).
• Offline-Safe Redirects: shouldRedirect({ url }) checked in beforeLoad, throwing redirect({ href: decision.redirectUrl.href }) when a locale redirect decision is needed, works even in client-only/offline environments.
• Type-Safe Translated Pathnames: Deriving translated pathnames directly from the generated FileRoutesByTo route tree type ensures no route is missing a translation, with compiler feedback.
• Prerendering Localized Routes: Mapping route paths through localizeHref to generate one prerendered output per locale.

Code Examples

// 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>
}

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

• What it demonstrates: A single route serving multiple locales via optional params, and a router-level rewrite config delegating locale URL transformation to Paraglide's runtime helpers.

Key Takeaways

1. For simple, manually-managed translations, optional path parameters ({-$locale}) alone are enough, no external i18n library required.
2. For richer i18n needs (automatic detection, type-safe message catalogs, SSR-aware locale middleware), pair the router's rewrite option (client-side) or server middleware (TanStack Start) with a dedicated library like Paraglide rather than reimplementing locale URL logic by hand.
3. Always validate the locale param (type guard + beforeLoad check) since it originates from user-controllable URL input, same discipline as any other path/search param (Ch 26/27).

Connects To

• Ch 22: URL Rewrites, the input/output rewrite mechanism reused here for locale prefixes.
• Ch 26: Path Params, the {-$param} optional parameter syntax this chapter's core pattern depends on.
• Ch 23: Navigation, Link params function-style updates used for language switchers.