# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/internationalization/url-prefixes*

---

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](./overview).

## 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](#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](../security/content-security-policy#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 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:

```tsx
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()`):

```tsx
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:

| 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`:

```tsx
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:

```ts
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:

```ts
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](#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](./overview)
