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.
| Request | Result |
|---|---|
/pricing | Default page; locale from cookie → Accept-Language → default |
/it/pricing | pages/pricing.tsx in Italian (rewrite); cookie set to it |
/en/pricing (default locale) | 308 to /pricing, query kept |
/dashboard with cookie it | Italian, URL unchanged: bare URLs follow the cookie |
/it/api/x | Ordinary path: 404 (the API has no locale) |
/it/logo.png | Ordinary path: plain 404 (assets aren't localized) |
/fr/pricing (fr not configured) | Ordinary path: the 404 page |
/it/pricing with cookie en | URL 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:/dashboardrenders in the cookie's language./it/dashboardworks too; the duplicate URL is harmless for pages that aren't indexed. - A plain
Linkon 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-Cookiewould keep the page out of the cache. The language selector saves the choice in the browser (browserLocaleCookiefrom@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 cookies | Result |
|---|---|
/faq, Accept-Language: it | English (default locale), no cookie, cacheable |
/it/faq | Italian, locale cookie saved, rendered live with the CSP |
/en/faq | 308 to /faq |
/dashboard, Accept-Language: it | Italian (not a marketing page) |
Links
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 prefixedOutside 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:
| Value | On /it/pricing?x=1 |
|---|---|
c.req.path | /pricing |
c.originalUrl() | URL for /it/pricing?x=1 (null when no rewrite happened) |
c.get('shared').locale | it |
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 tooFor 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 ItalianOutside 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/pricingis never stored;/pricing(default locale) is. A page that picks its language from the cookie orAccept-Languagecan't be cached per language either. - Requests with a
Cookieheader bypass ISR, and a response withSet-Cookieis 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 withVarylive, 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.pathwithoutlocalizeHref. useForm/action()with an unlocalized URL on a prefixed page: the action runs, but the address bar drops the prefix. UseuseLocalizedForm.- Linking to
/en/…. It works through a308, 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