TanStack Start i18n · TypeScript
Palamedes connects TanStack Start's type-safe router and server functions to one source-string-first translation workflow. Locale routing stays in TanStack; macro transforms, catalogs, diagnostics, and runtime access stay coherent across the request.
Transforms macros before the React and Start pipeline.
With TanStack Router 1.170 and Vite 8.
Request data activates the matching server runtime.
Cookie, route, subdomain, and top-level domain.
@palamedes/tanstackv1.17.3679 downloads / month01 — The framework problem
TanStack Router can model localized URLs precisely. An i18n integration still has to carry that decision into SSR, server functions, browser hydration, and later client interactions without turning the router into a translation store.
02 — The Palamedes model
The integration composes at the Vite and request boundaries. It does not replace TanStack Router's route tree, rewrites, params, or metadata APIs.
The Palamedes plugin runs in the existing TanStack Start toolchain and compiles TypeScript macros plus imported PO catalogs.
A server function validates its locale input, activates a request-local i18n instance, and then uses the same t macro as application code.
Use required, optional, or rewritten locale params in TanStack Router. Palamedes follows the resolved locale instead of prescribing the URL.
03 — In TypeScript
vite.config.ts + server-functions.ts
// vite.config.ts
import { tanstackStart } from "@tanstack/react-start/plugin/vite"
import react from "@vitejs/plugin-react"
import { palamedes } from "@palamedes/vite-plugin"
export default {
plugins: [
tanstackStart(),
palamedes(),
react(),
],
}
// server-functions.ts
export const getStatus = createServerFn({ method: "GET" })
.validator((data: { locale: Locale }) => data)
.handler(async ({ data }) => {
activateServerI18n(data.locale)
return t`Server function confirmed locale ${data.locale}.`
})The checked route example derives the locale from a typed route param, passes it into server functions, and initializes the browser runtime for subsequent navigation.
04 — Locale strategy
TanStack Router supports several localized URL patterns, including optional path params and rewrites. The Palamedes matrix keeps message handling identical while each example changes only the locale-resolution strategy.
One URL for all locales. Best for apps behind login where SEO is irrelevant and switching should be instant.
/de/checkout-style paths. The SEO-friendly default for public content with indexable localized pages.
de.example.com. Clean separation per market, works well with regional CDNs and analytics splits.
example.de vs example.com. Maximum market trust; Palamedes maps each domain to its locale.
◌ local / CIsource →
05 — Proof and boundaries
The browser flow checks more than rendered text. It proves that route resolution, client switching, and server work agree on one active locale.
Accept-Language reaches the configured locale URL.
Localized content is present before client interaction.
A later server function returns translated output.
Every locale strategy has source and CI coverage.
06 — Questions
The short version of the decisions that usually block an implementation.
07 — Keep exploring