Locale URL Prefixes

How /it/pricing serves the Italian page without moving any files, how bare URLs follow the cookie, and how to build localized links and redirects.

Any page can be opened with a non-default locale prefix (/it/pricing); the default locale never has one (/pricing). Bare URLs follow the visitor's cookie. Pages stay where they are: there's no pages/[locale]/ folder. With one locale configured, no URL is ever prefixed.

This page is part of the Internationalization documentation.

How It Works

apps/web/middleware/05.locale.ts reads the first path segment. If it's a configured non-default locale, it rewrites the request to the unprefixed path with c.rewrite(), uses that locale, and saves it in the locale cookie (only when the cookie differs). The browser keeps /it/pricing; Void serves pages/pricing.tsx.

RequestResult
/pricingDefault page; locale from cookie → Accept-Language → default
/it/pricingpages/pricing.tsx in Italian (rewrite); cookie set to it
/en/pricing (default locale)308 to /pricing, query kept
/dashboard with cookie itItalian, URL unchanged: bare URLs follow the cookie
/it/api/xOrdinary path: 404 (the API has no locale)
/it/logo.pngOrdinary path: plain 404 (assets aren't localized)
/fr/pricing (fr not configured)Ordinary path: the 404 page
/it/pricing with cookie enURL wins: Italian, and the cookie becomes it

The resolution order is URL prefix → cookie → Accept-Language → default, except on cached marketing pages. The cookie (1 year, path /, SameSite=Lax) is written only when the URL's locale differs from it. Client navigation with LocalizedLink and back/forward stay on the prefixed URL.

Prefixes Are Optional

The prefix is what makes a URL carry its language for someone without your cookie: a shared link, a search crawler, a cache. Visitors themselves keep their language through the cookie, which /it/… visits and the language selector set. So:

  • Public, shareable pages (marketing, pricing, blog) should link with LocalizedLink, so their URLs stay localized.
  • The signed-in app can use plain Link: /dashboard renders in the cookie's language. /it/dashboard works too; the duplicate URL is harmless for pages that aren't indexed.
  • A plain Link on a public page isn't broken: the next page is still Italian for this visitor, but its URL is the bare one.

Nothing needs configuring: there's no list of prefixed or unprefixed paths. Only /api and static assets are never prefixed.

Cached Marketing Pages

Bare marketing URLs (/, /faq: pages under apps/web/pages/(marketing)/) are shared by Void's cache between visitors who send no cookies (Cached Marketing Pages). One cached copy can't follow each visitor's language, so for those requests 05.locale.ts:

  • ignores Accept-Language: a bare URL is always the default locale, so one visitor's browser language is never cached for everyone.
  • never sets the locale cookie: a Set-Cookie would keep the page out of the cache. The language selector saves the choice in the browser (browserLocaleCookie from @kit/i18n), so later bare URLs follow it.

Prefixed marketing URLs (/it/faq) are not cached. Void's cache picks a page's lifetime from the URL before 05.locale.ts rewrites /it/faq to /faq, so /it/faq counts as an unknown page and is never stored. They render live like any other page: nonce CSP, locale cookie saved, Accept-Language irrelevant (the prefix wins). Visitors who send any cookie (a saved language or theme, a session) also get a live render.

Request without cookiesResult
/faq, Accept-Language: itEnglish (default locale), no cookie, cacheable
/it/faqItalian, locale cookie saved, rendered live with the CSP
/en/faq308 to /faq
/dashboard, Accept-Language: itItalian (not a marketing page)

A plain <Link href="/pricing"> on /it/… drops the prefix (the visitor stays in Italian through the cookie, but the URL is no longer shareable as Italian). On public pages, localize internal links:

import { LocalizedLink } from '@kit/i18n/react';
<LocalizedLink href="/pricing">…</LocalizedLink>;

LocalizedLink is @void/react's Link with the href passed through localizeHref for the current locale. In components, useLocalizeHref() returns the same function for string hrefs (a menu item, router.navigate()):

import { useLocalizeHref } from '@kit/i18n/react';
const localize = useLocalizeHref();
const href = localize('/pricing'); // '/it/pricing' in Italian; '/pricing' for the default locale; '/api/…' never prefixed

Outside components, call localizeHref({ href, locale, config }) from @kit/i18n. External URLs, #, ? and relative hrefs are returned unchanged.

Loaders, Actions and Redirects

After the rewrite, server code sees the unprefixed path:

ValueOn /it/pricing?x=1
c.req.path/pricing
c.originalUrl()URL for /it/pricing?x=1 (null when no rewrite happened)
c.get('shared').localeit

Actions. useForm('/pricing') on /it/pricing posts to /pricing, and the address bar loses the prefix. Use useLocalizedForm, which takes the same arguments and types as useForm:

import { useLocalizedForm } from '#/lib/i18n.client.ts';
const form = useLocalizedForm('/pricing', { email: '' });
const remove = useLocalizedForm('/pricing?remove', {}); // named actions too

For action(), pass a localized URL: action(localize('/pricing') as '/pricing').

Redirects. A redirect built from c.req.path loses the prefix. Use localizedRedirect in actions and handlers:

import { localizedRedirect } from '#/lib/i18n.server.ts';
return localizedRedirect({ c, href: '/pricing?saved=1' }); // "/it/pricing?saved=1" in Italian

Outside a request (an email link, a queue job), localize the target with the locale you stored:

import { localizeHref } from '@kit/i18n';
import { i18nConfig } from '#/config/i18n.config.ts';
const url = `${siteUrl}${localizeHref({ href: '/pricing', locale: user.locale, config: i18nConfig })}`;

Redirect targets come from the stripped path only, never from Host or the query, so prefixes can't create an open redirect.

Caching

  • Only the default locale is cached. Void's ISR picks the cache lifetime from the original path, before the locale rewrite, so /it/pricing is never stored; /pricing (default locale) is. A page that picks its language from the cookie or Accept-Language can't be cached per language either.
  • Requests with a Cookie header bypass ISR, and a response with Set-Cookie is never cached. So the cache only serves cookie-less visitors (crawlers, first page views), and marketing pages never set the cookie (Cached Marketing Pages). A bare URL renders in the cookie's language for everyone else, so never cache bare public pages per language.
  • Don't add Vary: Accept-Language. Void renders responses with Vary live, which disables ISR for that page.

Common Pitfalls

  • Raw <a href="/x"> or plain <Link> on a public page: the language holds (cookie), but the URL loses its prefix, so shared links and crawlers get the bare URL.
  • A redirect from c.req.path without localizeHref.
  • useForm / action() with an unlocalized URL on a prefixed page: the action runs, but the address bar drops the prefix. Use useLocalizedForm.
  • Linking to /en/…. It works through a 308, but costs a round trip; link to the unprefixed URL.
  • Expecting hreflang or a localized sitemap. They come with the marketing pages, not this feature.

Back to: Internationalization overview