This guide covers a server-rendered SolidStart application: locale detection happens on the request, pages are rendered on the server in the right language, and the <html lang>, hreflang and sitemap signals search engines need are emitted server-side.

Why Intlayer over alternatives?

Compared to main solutions like @solid-primitives/i18n or i18next, Intlayer is a solution that comes with integrated optimisations such as:

Intlayer is optimised to work perfectly with Solid by offering component-level content scoping, reactive translations, and all the features needed for scaling internationalisation (i18n).

Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps reduce your bundle and page sizes by up to 50%.

Scoping your application's content facilitates maintenance for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is fully typed to ensure your content's accuracy.

Co-locating content reduces the context needed by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a CLI to test for missing translations, LSP, MCP, and agent skills, to make the developer experience (DX) even smoother for AI agents.

Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a compiler to automate content extraction, as well as a web platform to help translate in the background.

Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimises your content loading at build time.

More than just an i18n solution, Intlayer provides a self-hosted visual editor and a full CMS to help you manage your multilingual content in real-time, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.

Step-by-Step Guide to Set Up Intlayer in a SolidStart Application

1
Install Dependencies

Install the necessary packages using npm:
bash
Copy code
Copy the code to the clipboard
npx intlayer init --interactive
npx intlayer init --interactive
the --interactive flag is optional. Use intlayer-cli init if you're an AI agent.

This command will detect your environment and install the required packages. For example:
bash
Copy code
Copy the code to the clipboard
npm install intlayer solid-intlayer vite-intlayer
npm install intlayer solid-intlayer vite-intlayer
- intlayer
  
  The core package that provides internationalisation tools for configuration management, translation, content declaration, transpilation, and CLI commands.
- solid-intlayer
  
  The package that integrates Intlayer with Solid application. It provides context providers and hooks for Solid internationalisation.
- vite-intlayer
  
  Includes the Vite plugin for integrating Intlayer with the Vite bundler, as well as the locale-routing handler that detects the user's preferred locale, manages cookies, and handles URL redirection.
vite-intlayer is a server-side concern here, not only a build-time one: it supplies the request handler that SolidStart's Nitro server runs. Keeping it in dependencies is the safe default — you can move it to devDependencies only if you deploy the built .output directory, into which Nitro inlines the handler.

Configuration of your project

Create a config file to configure the languages of your application:

intlayer.config.ts

Copy code

Copy the code to the clipboard

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Your other locales
    ],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    mode: "prefix-no-default",
  },
};

export default config;

With prefix-no-default, the default locale is served from unprefixed URLs:

plaintext

Copy code

Copy the code to the clipboard

/            /about          → English  (default locale)/fr          /fr/about       → French/es          /es/about       → Spanish

/            /about          → English  (default locale)/fr          /fr/about       → French/es          /es/about       → Spanish

Through this configuration file, you can set up localised URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the configuration documentation.

3
Integrate Intlayer in Your Vite Configuration

Add the Intlayer plugin to your configuration:
vite.config.ts
Copy code
Copy the code to the clipboard
```
import { solidStart } from "@solidjs/start/config";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [solidStart(), nitro(), intlayer()],
});
```
The intlayer() Vite plugin builds your content declaration files, watches them in development mode, and defines the Intlayer environment variables inside the application. It also provides aliases that optimise performance.

Locale routing comes with the plugin
SolidStart runs on Nitro, and intlayer() registers its locale-routing handler directly into Nitro's server pipeline (through the routing.enableProxy option, true by default). Nothing else to wire: on a built server, every request is inspected before it reaches the router, and
- the locale is read from the URL prefix, then the INTLAYER_LOCALE cookie, then the Accept-Language header;
- a non-prefixed URL is redirected to its localised counterpart when the resolved locale is not the default one (/ → /fr);
- a redundantly prefixed URL is redirected back to its canonical form (/en/about → /about);
- the locale cookie is written back on the response.
4
Declare Your Content

Create and manage your content declarations to store translations:
src/contents/home.content.ts
Copy code
Copy the code to the clipboard
```
import { type Dictionary, t } from "intlayer";

const homeContent = {
  key: "home-page",
  content: {
    title: t({
      en: "Hello world!",
      fr: "Bonjour le monde !",
      es: "¡Hola mundo!",
    }),
    metaTitle: "SolidStart + Intlayer",
    metaDescription: t({
      en: "A SolidStart application internationalized with Intlayer.",
      fr: "Une application SolidStart internationalisée avec Intlayer.",
      es: "Una aplicación SolidStart internacionalizada con Intlayer.",
    }),
    documentation: t({
      en: "Visit start.solidjs.com to learn how to build SolidStart apps.",
      fr: "Visitez start.solidjs.com pour apprendre à créer des applications SolidStart.",
      es: "Visita start.solidjs.com para aprender a crear aplicaciones SolidStart.",
    }),
  },
} satisfies Dictionary;

export default homeContent;
```
⚠️ SolidStart-specific gotcha: every .ts / .tsx file under src/routes becomes a route, and a .content.ts file has a default export, so it would be picked up as a page. Keep the content declarations of your pages outside the routes directory (src/contents/ works well). Content of components can stay co-located, since src/components is not scanned by the file-system router.

Your content declarations can be defined anywhere in your application as soon as they are included in the contentDir directory (by default, ./src), and match the content declaration file extension (by default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

For more details, refer to the content declaration documentation.

Add localized routing

The goal of this step is to give each language its own URL, which is what search engines index.

Move your pages under an optional dynamic segment. In SolidStart's file-system router, [[locale]] compiles to the :locale? path pattern:

plaintext

Copy code

Copy the code to the clipboard

src/routes/  [[locale]].tsx          ← layout that validates the segment  [[locale]]/    index.tsx             → /        and /fr        and /es    about.tsx             → /about   and /fr/about  and /es/about  [...404].tsx            → catch-all for anything else

src/routes/  [[locale]].tsx          ← layout that validates the segment  [[locale]]/    index.tsx             → /        and /fr        and /es    about.tsx             → /about   and /fr/about  and /es/about  [...404].tsx            → catch-all for anything else

The layout file's only job is to constrain the segment to a configured locale:

src/routes/[[locale]].tsx

Copy code

Copy the code to the clipboard

import type { RouteSectionProps } from "@solidjs/router";import { locales } from "intlayer";export const route = {  matchFilters: {    locale: locales,  },};export default function LocaleLayout(props: RouteSectionProps) {  return <>{props.children}</>;}

import type { RouteSectionProps } from "@solidjs/router";import { locales } from "intlayer";export const route = {  matchFilters: {    locale: locales,  },};export default function LocaleLayout(props: RouteSectionProps) {  return <>{props.children}</>;}

@solidjs/router expands :locale? into two patterns — one with the segment and one without — and tries them by descending specificity. matchFilters is what makes the difference between a working setup and a confusing one:

Show all table content

Open the table in a modal to view all data content clearly

URL	Without `matchFilters`	With `matchFilters`
`/fr/about`	French about page	French about page
`/about`	About page (static segment wins)	About page
`/unknown`	Home page, silently, with `locale=unknown`	No match → falls through to the catch-all 404

Prefer [locale] (required) over [[locale]] if you use the 'prefix-all' routing mode, and drop the segment entirely for 'no-prefix' or 'search-params'.

Provide the locale to your application

The URL is the single source of truth for the locale: the middleware has already redirected the request to its localised path, so reading the path in the root layout keeps the server render and the client hydration in agreement, and makes every client-side navigation update the locale for free.

src/app.tsx

Copy code

Copy the code to the clipboard

import { MetaProvider } from "@solidjs/meta";import { Router, useLocation } from "@solidjs/router";import { FileRoutes } from "@solidjs/start/router";import { defaultLocale, getHTMLTextDir, getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import { createEffect, type ParentProps, Suspense } from "solid-js";import { isServer } from "solid-js/web";import { Nav } from "~/components/Nav";import "./app.css";const RootLayout = (props: ParentProps) => {  const location = useLocation();  const locale = () => getLocaleFromPath(location.pathname) ?? defaultLocale;  // The server renders <html> in entry-server.tsx; client-side navigations  // between locales have to update the attributes themselves.  createEffect(() => {    if (isServer) return;    document.documentElement.lang = locale();    document.documentElement.dir = getHTMLTextDir(locale());  });  return (    <MetaProvider>      <IntlayerProvider locale={locale()}>        <Nav />        <Suspense>{props.children}</Suspense>      </IntlayerProvider>    </MetaProvider>  );};export default function App() {  return (    <Router root={RootLayout}>      <FileRoutes />    </Router>  );}

import { MetaProvider } from "@solidjs/meta";import { Router, useLocation } from "@solidjs/router";import { FileRoutes } from "@solidjs/start/router";import { defaultLocale, getHTMLTextDir, getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import { createEffect, type ParentProps, Suspense } from "solid-js";import { isServer } from "solid-js/web";import { Nav } from "~/components/Nav";import "./app.css";const RootLayout = (props: ParentProps) => {  const location = useLocation();  const locale = () => getLocaleFromPath(location.pathname) ?? defaultLocale;  // The server renders <html> in entry-server.tsx; client-side navigations  // between locales have to update the attributes themselves.  createEffect(() => {    if (isServer) return;    document.documentElement.lang = locale();    document.documentElement.dir = getHTMLTextDir(locale());  });  return (    <MetaProvider>      <IntlayerProvider locale={locale()}>        <Nav />        <Suspense>{props.children}</Suspense>      </IntlayerProvider>    </MetaProvider>  );};export default function App() {  return (    <Router root={RootLayout}>      <FileRoutes />    </Router>  );}

IntlayerProvider reacts to its locale prop, so passing the accessor call locale() inside JSX is enough — Solid compiles it to a getter, and the whole tree re-renders in the new language when the URL changes.

Set the HTML lang and dir attributes on the server

The <html> element is rendered by entry-server.tsx, outside the Router. Read the locale from the request URL instead:

src/entry-server.tsx

Copy code

Copy the code to the clipboard

// @refresh reloadimport { createHandler, StartServer } from "@solidjs/start/server";import { defaultLocale, getHTMLTextDir, getLocaleFromPath } from "intlayer";import { getRequestEvent } from "solid-js/web";export default createHandler(() => (  <StartServer    document={({ assets, children, scripts }) => {      const url = getRequestEvent()?.request.url ?? "/";      const locale = getLocaleFromPath(url) ?? defaultLocale;      return (        <html dir={getHTMLTextDir(locale)} lang={locale}>          <head>            <meta charset="utf-8" />            <meta              name="viewport"              content="width=device-width, initial-scale=1"            />            <link rel="icon" href="/favicon.ico" />            {assets}          </head>          <body>            <div id="app">{children}</div>            {scripts}          </body>        </html>      );    }}  />));

// @refresh reloadimport { createHandler, StartServer } from "@solidjs/start/server";import { defaultLocale, getHTMLTextDir, getLocaleFromPath } from "intlayer";import { getRequestEvent } from "solid-js/web";export default createHandler(() => (  <StartServer    document={({ assets, children, scripts }) => {      const url = getRequestEvent()?.request.url ?? "/";      const locale = getLocaleFromPath(url) ?? defaultLocale;      return (        <html dir={getHTMLTextDir(locale)} lang={locale}>          <head>            <meta charset="utf-8" />            <meta              name="viewport"              content="width=device-width, initial-scale=1"            />            <link rel="icon" href="/favicon.ico" />            {assets}          </head>          <body>            <div id="app">{children}</div>            {scripts}          </body>        </html>      );    }}  />));

Crawlers now receive the right language on the first byte:

html

Copy code

Copy the code to the clipboard

<html dir="ltr" lang="fr"></html>

<html dir="ltr" lang="fr"></html>

Utilize Intlayer in Your Pages

Access your content dictionaries throughout your application:

src/routes/[[locale]]/index.tsx

Copy code

Copy the code to the clipboard

import { Meta, Title } from "@solidjs/meta";import { useIntlayer } from "solid-intlayer";import Counter from "~/components/Counter";export default function Home() {  const content = useIntlayer("home-page");  return (    <main>      <Title>{content.metaTitle.value}</Title>      <Meta content={content.metaDescription.value} name="description" />      <h1>{content.title}</h1>      <Counter />      <p>{content.documentation}</p>    </main>  );}

import { Meta, Title } from "@solidjs/meta";import { useIntlayer } from "solid-intlayer";import Counter from "~/components/Counter";export default function Home() {  const content = useIntlayer("home-page");  return (    <main>      <Title>{content.metaTitle.value}</Title>      <Meta content={content.metaDescription.value} name="description" />      <h1>{content.title}</h1>      <Counter />      <p>{content.documentation}</p>    </main>  );}

In Solid, useIntlayer returns reactive content (e.g., content). You can access its properties directly.

If you want to use your content in a string attribute, such as alt, title, href, aria-label, etc., you can use the value of the function, like:
html
Copy code
Copy the code to the clipboard
<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />
<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

To learn more about the useIntlayer hook, refer to the documentation.

Content nodes are not limited to plain translations. A pluralised counter, for example:

src/components/Counter.content.ts

Copy code

Copy the code to the clipboard

import { type Dictionary, plural, t } from "intlayer";const counterContent = {  key: "counter",  content: {    clicks: plural({      one: t({        en: "{{count}} click",        fr: "{{count}} clic",        es: "{{count}} clic",      }),      other: t({        en: "{{count}} clicks",        fr: "{{count}} clics",        es: "{{count}} clics",      }),    }),  },} satisfies Dictionary;export default counterContent;

import { type Dictionary, plural, t } from "intlayer";const counterContent = {  key: "counter",  content: {    clicks: plural({      one: t({        en: "{{count}} click",        fr: "{{count}} clic",        es: "{{count}} clic",      }),      other: t({        en: "{{count}} clicks",        fr: "{{count}} clics",        es: "{{count}} clics",      }),    }),  },} satisfies Dictionary;export default counterContent;

src/components/Counter.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "solid-intlayer";import { createSignal } from "solid-js";export default function Counter() {  const [count, setCount] = createSignal(0);  const content = useIntlayer("counter");  return (    <button onClick={() => setCount(count() + 1)} type="button">      {content.clicks(count())}    </button>  );}

import { useIntlayer } from "solid-intlayer";import { createSignal } from "solid-js";export default function Counter() {  const [count, setCount] = createSignal(0);  const content = useIntlayer("counter");  return (    <button onClick={() => setCount(count() + 1)} type="button">      {content.clicks(count())}    </button>  );}

plural() selects the category through Intl.PluralRules for the active locale, so languages with more than two plural forms work without any extra code.

Create a Localized Link Component

Create a custom Link component that automatically prefixes internal URLs with the current language:

src/components/LocalizedLink.tsx

Copy code

Copy the code to the clipboard

import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";import type { ParentComponent } from "solid-js";export const LocalizedLink: ParentComponent<AnchorProps> = (props) => {  const { locale } = useLocale();  const isExternal = () => /^[a-z][a-z0-9+.-]*:/i.test(props.href);  const localizedHref = () =>    isExternal() ? props.href : getLocalizedUrl(props.href, locale());  return <A {...props} href={localizedHref()} />;};

import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";import type { ParentComponent } from "solid-js";export const LocalizedLink: ParentComponent<AnchorProps> = (props) => {  const { locale } = useLocale();  const isExternal = () => /^[a-z][a-z0-9+.-]*:/i.test(props.href);  const localizedHref = () =>    isExternal() ? props.href : getLocalizedUrl(props.href, locale());  return <A {...props} href={localizedHref()} />;};

src/components/Nav.tsx

Copy code

Copy the code to the clipboard

import { useIntlayer } from "solid-intlayer";import type { Component } from "solid-js";import { LocaleSwitcher } from "./LocaleSwitcher";import { LocalizedLink } from "./LocalizedLink";export const Nav: Component = () => {  const content = useIntlayer("nav");  return (    <nav>      <LocalizedLink href="/">{content.home}</LocalizedLink>      <LocalizedLink href="/about">{content.about}</LocalizedLink>      <LocaleSwitcher />    </nav>  );};

import { useIntlayer } from "solid-intlayer";import type { Component } from "solid-js";import { LocaleSwitcher } from "./LocaleSwitcher";import { LocalizedLink } from "./LocalizedLink";export const Nav: Component = () => {  const content = useIntlayer("nav");  return (    <nav>      <LocalizedLink href="/">{content.home}</LocalizedLink>      <LocalizedLink href="/about">{content.about}</LocalizedLink>      <LocaleSwitcher />    </nav>  );};

Writing href="/about" once now produces /about, /fr/about or /es/about depending on the active locale — no manual prefixing anywhere in your pages.

10
Create a Locale Switcher Component

Render the switcher as real anchors rather than a <select>: each language of the current page becomes a crawlable link that can be opened in a new tab, which a JavaScript-only control cannot offer.

getPathWithoutLocale strips the locale segment from the current path, and getLocalizedUrl rebuilds it for the target locale, so the links follow your routing mode without hard-coding anything. Navigation is what changes the rendered locale — the [[locale]] route derives it from the URL — while setLocale persists the choice in the INTLAYER_LOCALE cookie so a later visit to a locale-free URL resolves to the same language.
src/components/LocaleSwitcher.tsx
Copy code
Copy the code to the clipboard
```
import { A, useLocation } from "@solidjs/router";
import {
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
  getPathWithoutLocale,
} from "intlayer";
import { useIntlayer, useLocale } from "solid-intlayer";
import { type Component, For } from "solid-js";

export const LocaleSwitcher: Component = () => {
  const content = useIntlayer("locale-switcher");
  const location = useLocation();
  const { locale, setLocale, availableLocales } = useLocale();

  // Canonical (locale-free) path of the page currently displayed
  const pathWithoutLocale = () => getPathWithoutLocale(location.pathname);

  return (
    <div>
      <button
        aria-label={content.label.value}
        popoverTarget="localePopover"
        type="button"
      >
        {getLocaleName(locale())}
      </button>
      <div id="localePopover" popover="auto">
        <For each={availableLocales}>
          {(localeItem) => (
            <A
              dir={getHTMLTextDir(localeItem)}
              // Exact match only, so the default-locale link is not flagged
              // active on every page
              end
              href={getLocalizedUrl(pathWithoutLocale(), localeItem)}
              hreflang={localeItem}
              lang={localeItem}
              onClick={() => setLocale(localeItem)}
              // Ensures the "go back" browser button returns to the previous page
              replace
            >
              {/* Language in its own locale - e.g. Français */}
              {getLocaleName(localeItem)}
            </A>
          )}
        </For>
      </div>
    </div>
  );
};
```
In Solid, locale from useLocale is a signal accessor. Use locale() (with parentheses) to read its current value reactively.

getLocaleName(localeItem) renders each language in its own language — English / Français / Español. Pass a second argument to translate the names into the language currently displayed instead: getLocaleName(localeItem, locale()) gives English / French / Spanish in English, anglais / français / espagnol in French.

<A> already sets aria-current="page" on the link matching the current URL, so there is nothing to add for that. replace is read back from the rendered attribute by the router: it swaps the history entry instead of pushing one, so the browser "go back" button returns to the page visited before the switch rather than to the same page in the previous language.

dir and hreflang on each link keep right-to-left language names correctly oriented and tell assistive technologies and crawlers which language each link points to.

To learn more about the useLocale hook, refer to the documentation.

Emit canonical and hreflang links

Optional

hreflang annotations tell search engines that /about, /fr/about and /es/about are the same page in different languages. getMultilingualUrls derives them from the canonical (locale-free) path, following your routing mode, so nothing is hard-coded:

src/components/AlternateLinks.tsx

Copy code

Copy the code to the clipboard

import {  defaultLocale,  getMultilingualUrls,  getPathWithoutLocale,} from "intlayer";import { type Component, For } from "solid-js";export type AlternateLinksProps = {  /** Absolute URL of the page being rendered. */  url: string;};export const AlternateLinks: Component<AlternateLinksProps> = (props) => {  const multilingualUrls = () => {    const { origin, pathname } = new URL(props.url);    return Object.entries(      getMultilingualUrls(`${origin}${getPathWithoutLocale(pathname)}`)    );  };  const canonicalUrl = () =>    new URL(props.url).origin + new URL(props.url).pathname;  return (    <>      <link href={canonicalUrl()} rel="canonical" />      <For each={multilingualUrls()}>        {([locale, localizedUrl]) => (          <link href={localizedUrl} hreflang={locale} rel="alternate" />        )}      </For>      <link        href={          multilingualUrls().find(([locale]) => locale === defaultLocale)?.[1]        }        hreflang="x-default"        rel="alternate"      />    </>  );};

import {  defaultLocale,  getMultilingualUrls,  getPathWithoutLocale,} from "intlayer";import { type Component, For } from "solid-js";export type AlternateLinksProps = {  /** Absolute URL of the page being rendered. */  url: string;};export const AlternateLinks: Component<AlternateLinksProps> = (props) => {  const multilingualUrls = () => {    const { origin, pathname } = new URL(props.url);    return Object.entries(      getMultilingualUrls(`${origin}${getPathWithoutLocale(pathname)}`)    );  };  const canonicalUrl = () =>    new URL(props.url).origin + new URL(props.url).pathname;  return (    <>      <link href={canonicalUrl()} rel="canonical" />      <For each={multilingualUrls()}>        {([locale, localizedUrl]) => (          <link href={localizedUrl} hreflang={locale} rel="alternate" />        )}      </For>      <link        href={          multilingualUrls().find(([locale]) => locale === defaultLocale)?.[1]        }        hreflang="x-default"        rel="alternate"      />    </>  );};

Render it in the document head, where the request URL is available:

src/entry-server.tsx

Copy code

Copy the code to the clipboard

import { AlternateLinks } from "~/components/AlternateLinks";// … inside <head>, next to the other meta tags:<AlternateLinks url={url} />;

import { AlternateLinks } from "~/components/AlternateLinks";// … inside <head>, next to the other meta tags:<AlternateLinks url={url} />;

GET /fr/about then serves:

html

Copy code

Copy the code to the clipboard

<link href="https://example.com/fr/about" rel="canonical" /><link href="https://example.com/about" hreflang="en" rel="alternate" /><link href="https://example.com/fr/about" hreflang="fr" rel="alternate" /><link href="https://example.com/es/about" hreflang="es" rel="alternate" /><link href="https://example.com/about" hreflang="x-default" rel="alternate" />

<link href="https://example.com/fr/about" rel="canonical" /><link href="https://example.com/about" hreflang="en" rel="alternate" /><link href="https://example.com/fr/about" hreflang="fr" rel="alternate" /><link href="https://example.com/es/about" hreflang="es" rel="alternate" /><link href="https://example.com/about" hreflang="x-default" rel="alternate" />

Note on @solidjs/meta: at the time of writing, <Title> and <Meta> from @solidjs/meta are applied on the client after hydration but are not emitted into the server-rendered <head> in SolidStart v2. Until that is fixed upstream, render the tags that crawlers must see without JavaScript — canonical, hreflang, and if needed title / description — directly in entry-server.tsx, as shown above.

Manage not found pages

Optional

A splat route at the root of src/routes catches every path the locale segment did not match — including invalid locale prefixes rejected by matchFilters. Because the locale still comes from the URL through the root layout, the 404 page is displayed in the visitor's language:

src/routes/[...404].tsx

Copy code

Copy the code to the clipboard

import { Title } from "@solidjs/meta";import { HttpStatusCode } from "@solidjs/start";import { useIntlayer } from "solid-intlayer";import { LocalizedLink } from "~/components/LocalizedLink";export default function NotFound() {  const content = useIntlayer("not-found-page");  return (    <main>      <Title>{content.metaTitle.value}</Title>      <HttpStatusCode code={404} />      <h1>{content.title}</h1>      <LocalizedLink href="/">{content.backHome}</LocalizedLink>    </main>  );}

import { Title } from "@solidjs/meta";import { HttpStatusCode } from "@solidjs/start";import { useIntlayer } from "solid-intlayer";import { LocalizedLink } from "~/components/LocalizedLink";export default function NotFound() {  const content = useIntlayer("not-found-page");  return (    <main>      <Title>{content.metaTitle.value}</Title>      <HttpStatusCode code={404} />      <h1>{content.title}</h1>      <LocalizedLink href="/">{content.backHome}</LocalizedLink>    </main>  );}

Show all table content

Open the table in a modal to view all data content clearly

Request	Result
`/xx`	`404` — `xx` is not a configured locale
`/nonexistent`	`404` in the default locale
`/fr/nonexistent`	`404` in French (`Page introuvable`)

Generate a multilingual sitemap

Optional

Intlayer's sitemap generator expands every path into one entry per locale and wires the xhtml:link alternates between them, so the route only has to list the canonical, locale-free paths.

Unlike basic generators that only emit flat URLs, Intlayer wires bidirectional links between every localised variant of each page, which helps search engines relate localised URLs and serve the right one to the right audience.

SolidStart turns a file exporting an HTTP method into an API route, and strips the .ts extension from the path — so src/routes/sitemap.xml.ts is served at /sitemap.xml:

src/routes/sitemap.xml.ts

Copy code

Copy the code to the clipboard

import type { APIEvent } from "@solidjs/start/server";
import { generateSitemap } from "intlayer";

const SITE_URL = process.env.SITE_URL ?? "http://localhost:3000";

export const GET = (_event: APIEvent) => {
  const sitemap = generateSitemap(
    [
      { path: "/", changefreq: "daily", priority: 1.0 },
      { path: "/about", changefreq: "monthly", priority: 0.8 },
    ],
    { siteUrl: SITE_URL }
  );

  return new Response(sitemap, {
    headers: { "Content-Type": "application/xml" },
  });
};

output of GET /sitemap.xml

Copy code

Copy the code to the clipboard

<?xml version="1.0" encoding="UTF-8"?><urlset  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"  xmlns:xhtml="http://www.w3.org/1999/xhtml">  <url>    <loc>https://example.com/about</loc>    <changefreq>monthly</changefreq>    <priority>0.8</priority>    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/about"/>    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/about"/>    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/about"/>    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/about"/>  </url></urlset>

<?xml version="1.0" encoding="UTF-8"?><urlset  xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"  xmlns:xhtml="http://www.w3.org/1999/xhtml">  <url>    <loc>https://example.com/about</loc>    <changefreq>monthly</changefreq>    <priority>0.8</priority>    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/about"/>    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/about"/>    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/about"/>    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/about"/>  </url></urlset>

API routes do not support optional parameters, so keep this file at the root of src/routes, outside the [[locale]] segment. The sitemap already contains every locale.

You can build a robots.txt the same way with getMultilingualUrls, so that Disallow entries cover every localised spelling of a sensitive path:

src/routes/robots.txt.ts

Copy code

Copy the code to the clipboard

import { getMultilingualUrls } from "intlayer";

const SITE_URL = process.env.SITE_URL ?? "http://localhost:3000";

const disallowedPaths = ["/admin", "/private"].flatMap((path) =>
  Object.values(getMultilingualUrls(path))
);

export const GET = () =>
  new Response(
    [
      "User-agent: *",
      "Allow: /",
      ...disallowedPaths.map((path) => `Disallow: ${path}`),
      "",
      `Sitemap: ${SITE_URL}/sitemap.xml`,
    ].join("\n"),
    { headers: { "Content-Type": "text/plain" } }
  );

Retrieve the locale in your server functions

Optional

You may want to access the current locale from inside a server function or an API route.

In a prefix-based setup like this one, the URL is authoritative: getLocaleFromPath reads the prefix from the request URL. getLocale is the fallback for requests that carry no locale prefix — it inspects the INTLAYER_LOCALE cookie, then the x-intlayer-locale header, then negotiates Accept-Language.

src/routes/[[locale]]/index.tsx

Copy code

Copy the code to the clipboard

import { createAsync } from "@solidjs/router";import { getCookie, getIntlayer, getLocale, getLocaleFromPath } from "intlayer";import { getRequestEvent } from "solid-js/web";const loadLocalizedData = async () => {  "use server";  const request = getRequestEvent()?.request;  const locale =    getLocaleFromPath(request?.url) ??    (await getLocale({      // Get the cookie from the request (default: 'INTLAYER_LOCALE')      getCookie: (name) =>        getCookie(name, request?.headers.get("cookie") ?? ""),      // Get the header from the request (default: 'x-intlayer-locale'),      // falling back to Accept-Language negotiation      getHeader: (name) => request?.headers.get(name) ?? undefined,    }));  // Retrieve some content outside of a component using getIntlayer()  const content = getIntlayer("home-page", locale);  return { locale, title: String(content.title) };};export default function Page() {  const data = createAsync(() => loadLocalizedData());  return <p>{data()?.title}</p>;}

import { createAsync } from "@solidjs/router";import { getCookie, getIntlayer, getLocale, getLocaleFromPath } from "intlayer";import { getRequestEvent } from "solid-js/web";const loadLocalizedData = async () => {  "use server";  const request = getRequestEvent()?.request;  const locale =    getLocaleFromPath(request?.url) ??    (await getLocale({      // Get the cookie from the request (default: 'INTLAYER_LOCALE')      getCookie: (name) =>        getCookie(name, request?.headers.get("cookie") ?? ""),      // Get the header from the request (default: 'x-intlayer-locale'),      // falling back to Accept-Language negotiation      getHeader: (name) => request?.headers.get(name) ?? undefined,    }));  // Retrieve some content outside of a component using getIntlayer()  const content = getIntlayer("home-page", locale);  return { locale, title: String(content.title) };};export default function Page() {  const data = createAsync(() => loadLocalizedData());  return <p>{data()?.title}</p>;}

Do not rely on getLocale alone here: the locale cookie is only written once a visitor actively switches language, so a first visit to /fr/... would resolve to the default locale.

Extract the content of your components

Optional

If you have an existing codebase, transforming thousands of files can be time-consuming.

To ease this process, Intlayer proposes a compiler / extractor to transform your components and extract the content.

To set it up, you can add a compiler section in your intlayer.config.ts file:

intlayer.config.ts

Copy code

Copy the code to the clipboard

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Rest of your config
  compiler: {
    /**
     * Indicates if the compiler should be enabled.
     */
    enabled: true,

    /**
     * Defines the output files path
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Indicates if the components should be saved after being transformed.
     *
     * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
     *
     * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
     */
    saveComponents: false,

    /**
     * Dictionary key prefix
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

Run the extractor to transform your components and extract the content

bash

Copy code

Copy the code to the clipboard

npx intlayer extract

npx intlayer extract

Move the generated content files of your pages out of src/routes afterwards, for the reason explained in step 5.

Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

Update your vite.config.ts to include the intlayerCompiler plugin:

vite.config.ts

Copy code

Copy the code to the clipboard

import { solidStart } from "@solidjs/start/config";import { nitro } from "nitro/vite";import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   solidStart({ middleware: "src/middleware.ts" }),   nitro(),   intlayer(),   intlayerCompiler(), // Adds the compiler plugin ],});

import { solidStart } from "@solidjs/start/config";import { nitro } from "nitro/vite";import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   solidStart({ middleware: "src/middleware.ts" }),   nitro(),   intlayer(),   intlayerCompiler(), // Adds the compiler plugin ],});

bash

Copy code

Copy the code to the clipboard

npm run build # Or npm run dev

npm run build # Or npm run dev

Configure TypeScript

Intlayer uses module augmentation to get the benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types:

tsconfig.json

Copy code

Copy the code to the clipboard

{  compilerOptions: {    // ... your existing configurations  },  include: [    "src",    "*.ts",    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

{  compilerOptions: {    // ... your existing configurations  },  include: [    "src",    "*.ts",    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

Dictionary keys and content paths are now checked at compile time:

tsx

Copy code

Copy the code to the clipboard

useIntlayer("home-page"); // ✅useIntlayer("hom-page"); // ❌ Argument of type '"hom-page"' is not assignable to parameter of type 'keyof __DictionaryRegistry'

useIntlayer("home-page"); // ✅useIntlayer("hom-page"); // ❌ Argument of type '"hom-page"' is not assignable to parameter of type 'keyof __DictionaryRegistry'

Verifying your setup

Build and start the server, then check that these requests behave as expected:

bash

Copy code

Copy the code to the clipboard

npm run buildnode .output/server/index.mjs

npm run buildnode .output/server/index.mjs

Show all table content

Open the table in a modal to view all data content clearly

Request	Expected response
`GET /`	`200` — English
`GET /` with `Accept-Language: fr`	`302` → `/fr`
`GET /` with cookie `INTLAYER_LOCALE=es`	`302` → `/es`
`GET /fr`	`200` — French, `<html lang="fr">`
`GET /fr/about`	`200` — French about page
`GET /en/about`	`302` → `/about` (canonical redirect)
`GET /xx`	`404`
`GET /fr/nonexistent`	`404` in French
`GET /sitemap.xml`	`200` — multilingual XML sitemap

The rows that render a page behave identically under vite dev. The three redirect rows only apply to a built server unless you register the handler as a middleware yourself — see step 3.

Run the dev server on Node (vite dev) rather than on Bun (bun --bun vite dev): SolidStart's SSR currently fails under the Bun runtime with Expected a Response object, but received 'NodeResponse'. This is unrelated to Intlayer — it reproduces on the plain template — and only affects the dev server, not vite build.

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

.gitignore

Copy code

Copy the code to the clipboard

# Ignore the files generated by Intlayer.intlayer

# Ignore the files generated by Intlayer.intlayer

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

Autocompletion for translation keys.
Real-time error detection for missing translations.
Inline previews of translated content.
Quick actions to easily create and update translations.

Go Further

To go further, you can implement the visual editor or externalize your content using the CMS.

Documentation References

Vite and Solid

Vite and Svelte

Version History

Translate your SolidStart website using Intlayer | Internationalisation (i18n)

Table of Contents

Why Intlayer over alternatives?

Step-by-Step Guide to Set Up Intlayer in a SolidStart Application

Install Dependencies

Configuration of your project

Integrate Intlayer in Your Vite Configuration

Locale routing comes with the plugin

Declare Your Content

Add localized routing

Provide the locale to your application

Set the HTML lang and dir attributes on the server

Utilize Intlayer in Your Pages

Create a Localized Link Component

Create a Locale Switcher Component

Emit canonical and hreflang links

Manage not found pages

Generate a multilingual sitemap

Retrieve the locale in your server functions

Extract the content of your components

Configure TypeScript

Verifying your setup

Git Configuration

VS Code Extension

Go Further

Documentation References