TanStack Router

Create the localized route folder

Mirror HTTP prefix always with a dynamic segment in the file tree:

src/routes/
  __root.tsx
  {-$locale}/
    index.tsx       # /en/, /ar/
    about.tsx       # /en/about, /ar/about
    pricing.tsx

Route ids in the generated tree include the locale prefix — e.g. `/{-$locale}/about`. Set url.segment in config if you rename the segment (URL prefix modes).

Map de-localized paths — createToLocalizedRoute

App code should not hard-code "/en/about". Create a mapper from config:

// src/i18n/routes.ts
import { createToLocalizedRoute } from "@Wadiou/tanstack-i18n/react-router"; // or /solid-router
import { config } from "../locale-config";

export const toLocalizedRoute = createToLocalizedRoute(config);

Usage in the marketing site:

toLocalizedRoute("/");       // → "/{-$locale}"
toLocalizedRoute("/about");   // → "/{-$locale}/about"
toLocalizedRoute("/pricing");

Type helpers (DeLocalizedTo, etc.) keep to props aligned with your route tree while you author paths without the locale prefix.

Localized links

Create navigation helpers once:

import { createNavigation } from "@Wadiou/tanstack-i18n/react-router"; // or /solid-router

export const { LocalizedLink, useLocalizedNavigate, localizedRedirect } =
  createNavigation({ toLocalizedRoute });

Replace header nav links:

// Before
<Link to="/$locale/about" params={{ locale: "en" }}>About</Link>

// After — active locale comes from routing + getLocale()
<LocalizedLink to="/about">About</LocalizedLink>

LocalizedLink accepts the same props as TanStack Router Link except to is de-localized.

Programmatic navigation

CTA button on the marketing home page:

function StartTrialButton() {
  const navigate = useLocalizedNavigate();
  return (
    <button type="button" onClick={() => navigate({ to: "/pricing" })}>
      Start trial
    </button>
  );
}

The helper maps /pricing → `/{-$locale}/pricing` using the current route context.

Loader redirects

Protect a dashboard route — redirect anonymous users to login with a de-localized target:

// routes/{-$locale}/dashboard.tsx
export const Route = createFileRoute("/{-$locale}/dashboard")({
  beforeLoad: ({ context }) => {
    if (!context.user) {
      throw localizedRedirect({ to: "/login" });
    }
  },
});

localizedRedirect throws TanStack Router redirect() with the mapped route id.

If you use prefix: "as-needed", de-localized "/about" still maps correctly — the helper uses route ids, not raw HTTP paths. When links 404 after a prefix change, re-check URL prefix modes and that toLocalizedRoute uses the same config as defineLocaleConfig.

Keep config and helpers in one module

Export everything from src/i18n/routes.ts so layout, CTAs, and loaders share one toLocalizedRoute:

export { toLocalizedRoute, LocalizedLink, useLocalizedNavigate, localizedRedirect };

Importing createToLocalizedRoute in multiple files with different config slices causes subtle route id mismatches on the marketing site.

Solid apps

A dedicated @Wadiou/tanstack-i18n/solid-router subpath is fully supported! It exports the exact same createNavigation API, but wraps Solid Router's Link, useNavigate, and redirect with idiomatic Solid JS patterns. Use it exactly as shown above.