Creation:2024-08-13Last update:2026-01-26

    Custom URL Rewrites Implementation

    Intlayer supports custom URL rewrites, allowing you to define locale-specific paths that differ from the standard /locale/path structure. This enables URLs like /about for English and /a-propos for French while keeping the internal application logic canonical.

    Configuration

    Custom rewrites are configured in the routing section of your intlayer.config.ts file using framework-specific formatters. These formatters provide the correct syntax for your chosen router.

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";import { nextjsRewrite } from "intlayer/routing";const config: IntlayerConfig = {  // ...  routing: {    mode: "prefix-no-default",    rewrite: nextjsRewrite({      "/[locale]/about": {        fr: "/[locale]/a-propos",        es: "/[locale]/acerca-de",      },      "/[locale]/products/[id]": {        fr: "/[locale]/produits/[id]",        es: "/[locale]/productos/[id]",      },    }),  },};export default config;

    Available Formatters

    Intlayer provides formatters for all popular frameworks:

    • nextjsRewrite: For Next.js App Router. Supports [slug], [...slug] (1+), and [[...slug]] (0+).
    • svelteKitRewrite: For SvelteKit. Supports [slug], [...path] (0+), and [[optional]] (0-1).
    • reactRouterRewrite: For React Router. Supports :slug and * (0+).
    • vueRouterRewrite: For Vue Router 4. Supports :slug, :slug? (0-1), :slug* (0+), and :slug+ (1+).
    • solidRouterRewrite: For Solid Router. Supports :slug and *slug (0+).
    • tanstackRouterRewrite: For TanStack Router. Supports $slug and * (0+).
    • nuxtRewrite: For Nuxt 3. Supports [slug] and [...slug] (0+).
    • viteRewrite: Generic formatter for any Vite-based project. Normalises syntax for the Vite proxy.

    Advanced patterns

    Intlayer internally normalises these patterns to a unified syntax, allowing sophisticated path matching and generation:

    • Optional segments: [[optional]] (SvelteKit) or :slug? (Vue/React) are supported.
    • Catch-all (zero or more): [[...slug]] (Next.js), [...path] (SvelteKit/Nuxt), or * (React/TanStack) allow matching multiple segments.
    • Mandatory catch-all (one or more): [...slug] (Next.js) or :slug+ (Vue) ensure at least one segment is present.

    Client-side URL correction: useRewriteURL

    To ensure that the browser's address bar always reflects the "pretty" localised URL, Intlayer provides the useRewriteURL hook. This hook silently updates the URL using window.history.replaceState when a user lands on a canonical path.

    Usage in Frameworks

    tsx
    'use client';import { useRewriteURL } from "next-intlayer";const MyLayout = ({ children }) => {  useRewriteURL(); // Automatically corrects /fr/about to /fr/a-propos  return <>{children}</>;};

    Router Integration & Proxies

    Intlayer's server-side proxies (Vite & Next.js) automatically handle custom rewrites to ensure SEO consistency.

    1. Internal Rewrites: When a user visits /fr/a-propos, the proxy internally maps it to /fr/about so your framework matches the correct route.
    2. Authoritative Redirects: If a user manually types in /fr/about, the proxy issues a 301/302 redirect to /fr/a-propos, ensuring search engines only index one version of the page.

    Next.js Integration

    Next.js integration is fully handled via the intlayerProxy middleware.

    middleware.ts
    import { intlayerProxy } from "next-intlayer/middleware";import { NextRequest } from "next/server";export function middleware(request: NextRequest) {  return intlayerProxy(request);}

    Vite Integration

    For SolidJS, Vue, and Svelte, the intlayerProxy Vite plugin manages the rewrites during development.

    vite.config.ts
    import { defineConfig } from "vite";import { intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [intlayerProxy()],});

    Key Features

    1. Multi-Context Rewrites

    Each formatter generates a RewriteObject containing specialised rules for different consumers:

    • url: Optimised for client-side URL generation (strips locale segments).
    • nextjs: Preserves [locale] for Next.js middleware.
    • vite: Preserves :locale for Vite proxies.

    2. Automatic Pattern Normalisation

    Intlayer internally normalises all pattern syntaxes (e.g., converting [param] to :param) so that matching remains consistent regardless of the source framework.

    3. SEO Authoritative URLs

    By enforcing redirects from canonical paths to prettier aliases, Intlayer prevents duplicate content issues and improves site discoverability.

    Core Utilities

    • getLocalizedUrl(url, locale): Generates a localised URL respecting rewrite rules.
    • getCanonicalPath(path, locale): Resolves a localised URL back to its internal canonical path.
    • getRewritePath(pathname, locale): Detects whether a pathname needs to be corrected to its prettier localised alias.
    Why Intlayer ?