tanstack-start-intl

Internationalization (i18n) for TanStack Start, built on use-intl and aligned with next-intl semantics.

Setup

1. Install

pnpm add tanstack-start-intl use-intl
# peer: @tanstack/react-router, react

2. Config alias

In your Vite or TanStack Start config, add an alias so the package can load your request config:

// e.g. app.config.ts or vite.config.ts
export default defineConfig({
  resolve: {
    alias: {
      'tanstack-start-intl/config': resolve(__dirname, 'src/i18n/request.ts')
    }
  }
});

3. Request config

Create src/i18n/request.ts (or your chosen path):

import { getRequestConfig } from 'tanstack-start-intl/server';
import { hasLocale } from 'tanstack-start-intl';
import { routing } from './routing';

export default getRequestConfig(async ({ requestLocale }) => {
  const requested = await requestLocale;
  const locale = hasLocale(routing.locales, requested)
    ? requested
    : routing.defaultLocale;

  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default
  };
});

4. Routing config

Create src/i18n/routing.ts:

import { defineRouting } from 'tanstack-start-intl/routing';

export const routing = defineRouting({
  locales: ['en', 'fr'],
  defaultLocale: 'en',
  pathnames: {
    '/': '/',
    '/about': { en: '/about', fr: '/a-propos' }
  }
});

5. Locale layout

In your locale route (e.g. src/routes/$locale.tsx), set the request locale and wrap with the provider:

import { createFileRoute } from '@tanstack/react-router';
import { setRequestLocale, getRequestConfig } from 'tanstack-start-intl/server';
import { NextIntlClientProvider, hasLocale } from 'tanstack-start-intl';
import { routing } from '@/i18n/routing';

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

async function LocaleLayout() {
  const { locale } = Route.useParams();
  if (!hasLocale(routing.locales, locale)) {
    throw new Error('Invalid locale');
  }
  setRequestLocale(locale);
  const config = await getRequestConfig({
    requestLocale: Promise.resolve(locale)
  });

  return (
    <NextIntlClientProvider locale={config.locale} messages={config.messages}>
      <Outlet />
    </NextIntlClientProvider>
  );
}

6. Navigation (optional)

If you use pathnames and locale prefix, create navigation helpers:

// src/i18n/navigation.ts
import { createNavigation } from 'tanstack-start-intl';
import { routing } from './routing';

export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

API

• From tanstack-start-intl: NextIntlClientProvider, createNavigation, hasLocale, useTranslations, useFormatter, useLocale, useMessages, useNow, useTimeZone
• From tanstack-start-intl/server: getRequestConfig, setRequestLocale, getTranslations, getLocale, getMessages, getFormatter, getTimeZone, getNow
• From tanstack-start-intl/routing: defineRouting, routing types

Notes

• Locale is only taken from setRequestLocale(locale) in your locale layout. There is no header-based detection; call setRequestLocale before any server API use.
• Configure the alias tanstack-start-intl/config to your request file so server APIs can load messages and locale.