diff --git a/docs/router/config.json b/docs/router/config.json
index 808c3fe38f9..a1fab7b8bc9 100644
--- a/docs/router/config.json
+++ b/docs/router/config.json
@@ -324,6 +324,10 @@
{
"label": "Render Optimizations",
"to": "framework/react/guide/render-optimizations"
+ },
+ {
+ "label": "Internationalization (i18n)",
+ "to": "framework/react/guide/internationalization-i18n"
}
]
},
diff --git a/docs/router/framework/react/guide/internationalization-i18n.md b/docs/router/framework/react/guide/internationalization-i18n.md
index 49397717772..06a6bd544d5 100644
--- a/docs/router/framework/react/guide/internationalization-i18n.md
+++ b/docs/router/framework/react/guide/internationalization-i18n.md
@@ -11,33 +11,16 @@ This guide covers:
- Language navigation and switching
- SEO considerations
- Type safety
-- Integration patterns with i18n libraries (Paraglide)
+- Integration patterns with i18n libraries (e.g. Paraglide)
----
-
-## i18n with Optional Path Parameters
-
-This pattern relies exclusively on TanStack Router features. It is suitable when:
-
-- You want full control over translations
-- You already manage translations manually
-- You do not need automatic locale detection
-
-Optional path parameters are ideal for implementing locale-aware routing without duplicating routes.
-
-```ts
-;/{-$locale}/abotu
-```
+## Internationalization (i18n) with Optional Path Parameters
-This single route matches:
-
-- `/about` (default locale)
-- `/en/about`
-- `/fr/about`
-- `/es/about`
+Optional path parameters are excellent for implementing internationalization (i18n) routing patterns. You can use prefix patterns to handle multiple languages while maintaining clean, SEO-friendly URLs.
### Prefix-based i18n
+Use optional language prefixes to support URLs like `/en/about`, `/fr/about`, or just `/about` (default language):
+
```tsx
// Route: /{-$locale}/about
export const Route = createFileRoute('/{-$locale}/about')({
@@ -46,86 +29,328 @@ export const Route = createFileRoute('/{-$locale}/about')({
function AboutComponent() {
const { locale } = Route.useParams()
- const currentLocale = locale || 'en'
+ const currentLocale = locale || 'en' // Default to English
const content = {
- en: { title: 'About Us' },
- fr: { title: 'À Propos' },
- es: { title: 'Acerca de' },
+ en: { title: 'About Us', description: 'Learn more about our company.' },
+ fr: {
+ title: 'À Propos',
+ description: 'En savoir plus sur notre entreprise.',
+ },
+ es: {
+ title: 'Acerca de',
+ description: 'Conoce más sobre nuestra empresa.',
+ },
}
- return {content[currentLocale].title}
+ return (
+
+
{content[currentLocale]?.title}
+
{content[currentLocale]?.description}
+
{data.title}
+
+ Category: {category || 'All'} | Language: {locale || 'en'}
+
+ {data.content}
+
+ )
+}
```
-### Language Switching
+This supports URLs like:
+
+- `/blog/tech/my-post` (default locale, tech category)
+- `/fr/blog/my-post` (French, no category)
+- `/en/blog/tech/my-post` (explicit English, tech category)
+- `/es/blog/tecnologia/mi-post` (Spanish, Spanish category)
+
+### Language Navigation
+
+Create language switchers using optional i18n parameters with function-style params:
```tsx
- ({
- ...prev,
- locale: prev.locale === 'en' ? undefined : 'fr',
- })}
->
- Français
-
+function LanguageSwitcher() {
+ const currentParams = useParams({ strict: false })
+
+ const languages = [
+ { code: 'en', name: 'English' },
+ { code: 'fr', name: 'Français' },
+ { code: 'es', name: 'Español' },
+ ]
+
+ return (
+
+ {languages.map(({ code, name }) => (
+ ({
+ ...prev,
+ locale: code === 'en' ? undefined : code, // Remove 'en' for clean URLs
+ })}
+ className={currentParams.locale === code ? 'active' : ''}
+ >
+ {name}
+
+ ))}
+
+ )
+}
```
-### Type-safe Locales
+You can also create more sophisticated language switching logic:
-```ts
-type Locale = 'en' | 'fr' | 'es' | 'de'
+```tsx
+function AdvancedLanguageSwitcher() {
+ const currentParams = useParams({ strict: false })
+
+ const handleLanguageChange = (newLocale: string) => {
+ return (prev: any) => {
+ // Preserve all existing params but update locale
+ const updatedParams = { ...prev }
+
+ if (newLocale === 'en') {
+ // Remove locale for clean English URLs
+ delete updatedParams.locale
+ } else {
+ updatedParams.locale = newLocale
+ }
+
+ return updatedParams
+ }
+ }
-function isLocale(value?: string): value is Locale {
- return ['en', 'fr', 'es', 'de'].includes(value as Locale)
+ return (
+
+
+ Français
+
+
+
+ Español
+
+
+
+ English
+
+
+ )
}
```
----
+### Advanced i18n with Optional Parameters
-## i18n Library Integration Patterns
+Organize i18n routes using optional parameters for flexible locale handling:
-TanStack Router is **library-agnostic**. You can integrate any i18n solution by mapping locale state to routing behavior.
+```tsx
+// Route structure:
+// routes/
+// {-$locale}/
+// index.tsx // /, /en, /fr
+// about.tsx // /about, /en/about, /fr/about
+// blog/
+// index.tsx // /blog, /en/blog, /fr/blog
+// $slug.tsx // /blog/post, /en/blog/post, /fr/blog/post
+
+// routes/{-$locale}/index.tsx
+export const Route = createFileRoute('/{-$locale}/')({
+ component: HomeComponent,
+})
-Below is a recommended pattern using **Paraglide**.
+function HomeComponent() {
+ const { locale } = Route.useParams()
+ const isRTL = ['ar', 'he', 'fa'].includes(locale || '')
+
+ return (
+
+
Welcome ({locale || 'en'})
+ {/* Localized content */}
+
+ )
+}
----
+// routes/{-$locale}/about.tsx
+export const Route = createFileRoute('/{-$locale}/about')({
+ component: AboutComponent,
+})
+```
+
+### SEO and Canonical URLs
+
+Handle SEO for i18n routes properly:
+
+```tsx
+export const Route = createFileRoute('/{-$locale}/products/$id')({
+ component: ProductComponent,
+ head: ({ params, loaderData }) => {
+ const locale = params.locale || 'en'
+ const product = loaderData
+
+ return {
+ title: product.title[locale] || product.title.en,
+ meta: [
+ {
+ name: 'description',
+ content: product.description[locale] || product.description.en,
+ },
+ {
+ property: 'og:locale',
+ content: locale,
+ },
+ ],
+ links: [
+ // Canonical URL (always use default locale format)
+ {
+ rel: 'canonical',
+ href: `https://example.com/products/${params.id}`,
+ },
+ // Alternate language versions
+ {
+ rel: 'alternate',
+ hreflang: 'en',
+ href: `https://example.com/products/${params.id}`,
+ },
+ {
+ rel: 'alternate',
+ hreflang: 'fr',
+ href: `https://example.com/fr/products/${params.id}`,
+ },
+ {
+ rel: 'alternate',
+ hreflang: 'es',
+ href: `https://example.com/es/products/${params.id}`,
+ },
+ ],
+ }
+ },
+})
+```
+
+### Type Safety for i18n
+
+Ensure type safety for your i18n implementations:
+
+```tsx
+// Define supported locales
+type Locale = 'en' | 'fr' | 'es' | 'de'
+
+// Type-safe locale validation
+function validateLocale(locale: string | undefined): locale is Locale {
+ return ['en', 'fr', 'es', 'de'].includes(locale as Locale)
+}
-## Client-side i18n with a Library (TanStack Router)
+export const Route = createFileRoute('/{-$locale}/shop/{-$category}')({
+ beforeLoad: async ({ params }) => {
+ const { locale } = params
-This pattern combines TanStack Router with a client-side i18n library. It is suitable when:
+ // Type-safe locale validation
+ if (locale && !validateLocale(locale)) {
+ throw redirect({
+ to: '/shop/{-$category}',
+ params: { category: params.category },
+ })
+ }
+
+ return {
+ locale: (locale as Locale) || 'en',
+ isDefaultLocale: !locale || locale === 'en',
+ }
+ },
+ component: ShopComponent,
+})
-- You want type-safe translations
-- You want localized URLs
-- You do not need server-side rendering
+function ShopComponent() {
+ const { locale, category } = Route.useParams()
+ const { isDefaultLocale } = Route.useRouteContext()
+
+ // TypeScript knows locale is Locale | undefined
+ // and we have validated it in beforeLoad
+
+ return (
+
+
Shop {category ? `- ${category}` : ''}
+
Language: {locale || 'en'}
+ {!isDefaultLocale && (
+
+ View in English
+
+ )}
+
-```
-
----
-
-## Offline-safe Redirects
-
-For offline or client-only environments:
+#### URL redirects
```ts
import { shouldRedirect } from '../paraglide/runtime'
@@ -205,44 +392,86 @@ beforeLoad: async () => {
}
```
----
+If you use TanStack Start and do not need offline capabilities, you don't need to use the shouldRedirect logic, only paraglideMiddleware in the TanStack Start Paraglide integration guide.
-## Type-safe Translated Pathnames
+#### Type-safe Translated Pathnames
-To ensure every route has translations, you can derive translated pathnames directly from the TanStack Router route tree.
+If you use translated pathnames, you can derive them directly from the TanStack Router route tree to ensure every route has translations.
```ts
-import { FileRoutesByTo } from '../routeTree.gen'
-import { Locale } from '@/paraglide/runtime'
-```
+import { Locale } from "@reland/i18n/runtime"
+import { RoutePath } from "../../types/Routes"
-This guarantees:
+const excludedPaths = ["admin", "partner", "tests", "api"] as const
-- No missing translations
-- Full type safety
-- Compiler feedback for routing mistakes
+type PublicRoutePath = Exclude<
+ RoutePath,
+ `${string}${(typeof excludedPaths)[number]}${string}`
+>
----
+type TranslatedPathname = {
+ pattern: string
+ localized: Array<[Locale, string]>
+}
-## Prerendering Localized Routes
+function toUrlPattern(path: string) {
+ return (
+ path
+ // explicit catch-all: "/$" → "/:path(.*)?"
+ .replace(/\/\$$/, "/:path(.*)?")
+ // optional params like {-$param} → ":param(.*)?"
+ .replace(/\{-\$([a-zA-Z0-9_]+)\}/g, ":$1(.*)?")
+ // normal params like $param → ":param(.*)?"
+ .replace(/\$([a-zA-Z0-9_]+)/g, ":$1(.*)?")
+ // remove any remaining braces (safety)
+ .replace(/[{}]/g, "")
+ // remove trailing slash
+ .replace(/\/+$/, "")
+ )
+}
-```ts
-import { localizeHref } from './paraglide/runtime'
+function createTranslatedPathnames(
+ input: Record