Translate your SvelteKit website using Intlayer | Internationalisation (i18n)

Table of Contents

Why Intlayer over alternatives?

Compared to main solutions like svelte-i18n or i18next, Intlayer is a solution that comes with integrated optimizations such as:

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

See Application Template on GitHub.

To get started, create a new SvelteKit project. Here is the final structure that we will make:

.
├── intlayer.config.ts
├── package.json
├── src
│   ├── app.d.ts
│   ├── app.html
│   ├── hooks.server.ts
│   ├── lib
│   │   ├── getLocale.ts
│   │   ├── LocaleSwitcher.svelte
│   │   └── LocalizedLink.svelte
│   ├── params
│   │   └── locale.ts
│   └── routes
│       ├── [[locale=locale]]
│       │   ├── +layout.svelte
│       │   ├── +layout.ts
│       │   ├── +page.svelte
│       │   ├── +page.ts
│       │   ├── about
│       │   │   ├── +page.svelte
│       │   │   ├── +page.ts
│       │   │   └── page.content.ts
│       │   ├── Counter.content.ts
│       │   ├── Counter.svelte
│       │   ├── Header.content.ts
│       │   ├── Header.svelte
│       │   ├── home.content.ts
│       │   └── layout.content.ts
│       ├── +layout.svelte
│       └── layout.css
├── static
│   ├── favicon.svg
│   └── robots.txt
├── svelte.config.js
├── tsconfig.json
└── vite.config.ts

1. 1

   Install Dependencies

   Install the necessary packages using npm:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   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 content

   Copy code

   Copy the code to the clipboard

   npm install intlayer svelte-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer: The core i18n package.
   • svelte-intlayer: Provides context providers and stores for Svelte/SvelteKit.
   • vite-intlayer: The Vite plugin to integrate content declarations with the build process.
2. 2

   Configuration of your project

   Create a config file in your project root:

   intlayer.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

3. 3

   Integrate Intlayer in Your Vite Configuration

   Update your vite.config.ts to include the Intlayer plugin. This plugin manages the transpilation of your content files.

   vite.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { sveltekit } from "@sveltejs/kit/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [intlayer(), sveltekit()], // order matters, Intlayer should be placed before SvelteKit
   });
   

4. 4

   Declare Your Content

   Create your content declaration files anywhere in your src folder (e.g., src/lib/content or alongside your components). These files define the translatable content for your application using the t() function for each locale.

5. 5

   Utilise Intlayer in Your Components

   Now you can use the useIntlayer function in any Svelte component. It returns a reactive store that automatically updates when the locale changes. The function will automatically respect the current locale (both during SSR and client-side navigation).

   prefix to access its reactive value (e.g., $content.title).

   src/lib/components/Component.svelte

   Copy content

   Copy code

   Copy the code to the clipboard

   <script lang="ts">
     import { useIntlayer } from "svelte-intlayer";
   
     // "hero-section" corresponds to the key defined in Step 4
     const content = useIntlayer("hero-section");
   </script>
   
   <!-- Render content as simple content  -->
   <h1>{$content.title}</h1>
   <!-- To render the content editable using the editor -->
   <h1>{@const Title = $content.title}<Title /></h1>
   <!-- To render the content as a string -->
   <div aria-label={$content.title.value}></div>
   <div aria-label={$content.title.toString()}></div>
   <div aria-label={String($content.title)}></div>
   

6. 6

   Set up routing

   Optional

   The following steps show how to set up locale-based routing in SvelteKit. This allows your URLs to include the locale prefix (e.g., /en/about, /fr/about) for better SEO and user experience.

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   .
   └─── src
       ├── app.d.ts                  # Define the locale type
       ├── hooks.server.ts           # Manage locale routing
       ├── lib
       │   └── getLocale.ts          # Check the locale from the header, cookies
       ├── params
       │   └── locale.ts             # Define the locale parameter
       └── routes
           ├── [[locale=locale]]     # Wrap in a route group to set the locale
           │   ├── +layout.svelte    # Local layout for the route
           │   ├── +layout.ts
           │   ├── +page.svelte
           │   ├── +page.ts
           │   └── about
           │       ├── +page.svelte
           │       └── +page.ts
           └── +layout.svelte         # Root layout for fonts and global styles
   

7. 7

   Handle Server-Side Locale Detection

   In SvelteKit, the server needs to know the user's locale to render the correct content during SSR. We use hooks.server.ts to detect the locale from the URL or cookies.

   Create or modify src/hooks.server.ts:

   src/hooks.server.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { Handle } from "@sveltejs/kit";
   import { getLocalizedUrl } from "intlayer";
   import { getLocale } from "$lib/getLocale";
   
   export const handle: Handle = async ({ event, resolve }) => {
     const detectedLocale = getLocale(event);
   
     // Check if the current path already starts with a locale (e.g. /fr, /en)
     const pathname = event.url.pathname;
     const targetPathname = getLocalizedUrl(pathname, detectedLocale);
   
     // If NO locale is present in the URL (e.g. user visits "/"), redirect them
     if (targetPathname !== pathname) {
       return new Response(undefined, {
         headers: { Location: targetPathname },
         status: 307, // Temporary redirect
       });
     }
   
     return resolve(event, {
       transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale),
     });
   };
   

   Then, create a helper to get the user's locale from the request event:

   src/lib/getLocale.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import {
     configuration,
     getLocaleFromStorage,
     localeDetector,
     type Locale,
   } from "intlayer";
   import type { RequestEvent } from "@sveltejs/kit";
   
   /**
    * Retrieve the user's locale from the request event.
    * This function is utilised in the `handle` hook within `src/hooks.server.ts`.
    *
    * It initially attempts to obtain the locale from the Intlayer storage (cookies or custom headers).
    * If the locale is not found, it defaults to the browser's "Accept-Language" negotiation.
    *
    * @param event - The request event from SvelteKit
    * @returns The user's locale
    */
   export const getLocale = (event: RequestEvent): Locale => {
     const defaultLocale = configuration?.internationalization?.defaultLocale;
   
     // Attempt to retrieve locale from Intlayer storage (Cookies or headers)
     const storedLocale = getLocaleFromStorage({
       // SvelteKit cookies access
       getCookie: (name: string) => event.cookies.get(name) ?? null,
       // SvelteKit headers access
       getHeader: (name: string) => event.request.headers.get(name) ?? null,
     });
   
     if (storedLocale) {
       return storedLocale;
     }
   
     // Fallback to Browser "Accept-Language" negotiation
     const negotiatorHeaders: Record<string, string> = {};
   
     // Convert SvelteKit Headers object to a plain Record<string, string>
     event.request.headers.forEach((value, key) => {
       negotiatorHeaders[key] = value;
     });
   
     // Check the locale from the `Accept-Language` header
     const userFallbackLocale = localeDetector(negotiatorHeaders);
   
     if (userFallbackLocale) {
       return userFallbackLocale;
     }
   
     // Return default locale if no match is found
     return defaultLocale;
   };
   

   getLocaleFromStorage will check the locale from header or cookie depending on your configuration. See Configuration for more details.

   The localeDetector function will process the Accept-Language header and return the best match.

   If the locale is not configured, we want to return a 404 error. To simplify this, we can create a match function to verify if the locale is valid:

   /src/params/locale.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { defaultLocale, locales, type Locale } from "intlayer";
   
   export const match = (param: Locale = defaultLocale): boolean =>
     locales.includes(param);
   

   Note: Ensure your src/app.d.ts includes the locale definition:

   typescript

   Copy content

   Copy code

   Copy the code to the clipboard

   declare global {
     namespace App {
       interface Locals {
         locale: import("intlayer").Locale;
       }
     }
   }
   

   For the +layout.svelte file, we can remove everything, to keep only static content, not related to i18n:

   src/+layout.svelte

   Copy content

   Copy code

   Copy the code to the clipboard

   <script lang="ts">
        import './layout.css';
   
       let { children } = $props();
   </script>
   
   <div class="app">
       {@render children()}
   </div>
   
   <style>
       .app {
       /*  */
       }
   </style>
   

   Then, create a new page and layout under the [[locale=locale]] group:

   src/routes/[[locale=locale]]/+layout.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { Load } from "@sveltejs/kit";
   import { defaultLocale, type Locale } from "intlayer";
   
   export const prerender = true;
   
   // Use the generic Load type
   export const load: Load = ({ params }) => {
     const locale: Locale = (params.locale as Locale) ?? defaultLocale;
   
     return {
       locale,
     };
   };
   

   src/routes/[[locale=locale]]/+layout.svelte

   Copy content

   Copy code

   Copy the code to the clipboard

   <script lang="ts">
       import type { Snippet } from 'svelte';
       import { useIntlayer, setupIntlayer } from "svelte-intlayer";
       import Header from './Header.svelte';
       import type { LayoutData } from './$types';
   
       let { children, data }: { children: Snippet, data: LayoutData } = $props();
   
       // Initialise Intlayer with the locale from the route
     $effect(() => {
         setupIntlayer(data.locale);
     });
       // Use the layout content dictionary
       const layoutContent = useIntlayer('layout');
   </script>
   
   <Header />
   
   <main>
       {@render children()}
   </main>
   
   <footer>
       <p>
           {$layoutContent.footer.prefix.value}{' '}
           <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '}
           {$layoutContent.footer.suffix.value}
       </p>
   </footer>
   
   <style>
     /*  */
   </style>
   

   src/routes/[[locale=locale]]/+page.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   export const prerender = true;
   

   src/routes/[[locale=locale]]/+page.svelte

   Copy content

   Copy code

   Copy the code to the clipboard

   <script lang="ts">
       import { useIntlayer } from "svelte-intlayer";
   
       // Use the home content dictionary
       const homeContent = useIntlayer('home');
   </script>
   
   <svelte:head>
       <title>{$homeContent.title.value}</title>
   </svelte:head>
   
   <section>
       <h1>
           {$homeContent.title}
       </h1>
   </section>
   
   <style>
     /*  */
   </style>
   

8. 8

   Internationalised Links

   Optional

   For SEO, it is recommended to prefix your routes with the locale (e.g., /en/about, /fr/about). This component automatically prefixes any link with the current locale.

   src/lib/components/LocalizedLink.svelte

   Copy content

   Copy code

   Copy the code to the clipboard

   <script lang="ts">
     import { getLocalizedUrl } from "intlayer";
     import { useLocale } from "svelte-intlayer";
   
     let { href = "" } = $props();
     const { locale } = useLocale();
   
     // Helper to prefix URL with current locale
     $: localizedHref = getLocalizedUrl(href, $locale);
   </script>
   
   <a href={localizedHref}>
     <slot />
   </a>
   

   If you use goto from SvelteKit, you can use the same logic with getLocalizedUrl to navigate to the localised URL:

   typescript

   Copy content

   Copy code

   Copy the code to the clipboard

   import { goto } from "$app/navigation";
   import { getLocalizedUrl } from "intlayer";
   import { useLocale } from "svelte-intlayer";
   
   const { locale } = useLocale();
   const localizedPath = getLocalizedUrl("/about", $locale);
   goto(localizedPath); // Navigates to /en/about or /fr/about depending on locale
   

9. 9

   Language Switcher

   Optional

   To allow users to switch languages, update the URL.

   src/lib/components/LanguageSwitcher.svelte

   Copy content

   Copy code

   Copy the code to the clipboard

   <script lang="ts">
     import { getLocalizedUrl, getLocaleName } from 'intlayer';
     import { useLocale } from "svelte-intlayer";
     import { page } from '$app/stores';
     import { goto } from '$app/navigation';
   
     const { locale, setLocale, availableLocales } = useLocale({
       onLocaleChange: (newLocale) => {
         const localizedPath = getLocalizedUrl($page.url.pathname, newLocale);
         goto(localizedPath);
       },
     });
   </script>
   
   <ul class="locale-list">
     {#each availableLocales as localeEl}
       <li>
         <a
           href={getLocalizedUrl($page.url.pathname, localeEl)}
           onclick={(e) => {
             e.preventDefault();
             setLocale(localeEl); // Will set the locale in the store and trigger onLocaleChange
           }}
           class:active={$locale === localeEl}
         >
           {getLocaleName(localeEl)}
         </a>
       </li>
     {/each}
   </ul>
   
   <style>
     /* */
   </style>
   

10. 10

    Add backend proxy

    Optional

    To add a backend proxy to your SvelteKit application, you can use the intlayerProxy function provided by the vite-intlayer plugin. This plugin will automatically detect the best locale for the user based on the URL, cookies, and browser language preferences.

    Since Intlayer v9, intlayerProxy() is bundled directly into the intlayer() plugin and enabled by default through the routing.enableProxy option (true by default). Registering it separately as shown below is now optional — it is kept for backward compatibility and for setups that need to control plugin order. Set routing.enableProxy: false to opt out. See the v9 release notes.

    vite.config.ts

    Copy content

    Copy code

    Copy the code to the clipboard

    import { defineConfig } from "vite";
    import { intlayer } from "vite-intlayer";
    import { sveltekit } from "@sveltejs/kit/vite";
    
    // https://vitejs.dev/config/
    export default defineConfig({
      plugins: [
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
        sveltekit(),
      ],],
    });
    

11. 11

    Set up the intlayer editor / CMS

    Optional

    To set up the intlayer editor, you must follow the intlayer editor documentation.

    To set up the intlayer CMS, you must follow the intlayer CMS documentation.

    To be able to visualise the intlayer editor selector, you will have to use the component syntax in your intlayer content.

    Component.svelte

    Copy content

    Copy code

    Copy the code to the clipboard

    <script lang="ts">
      import { useIntlayer } from "svelte-intlayer";
    
      const content = useIntlayer("component");
    </script>
    
    <div>
    
      <!-- Render content as simple content  -->
      <h1>{$content.title}</h1>
    
      <!-- Render content as a component (required by the editor) -->
      {@const Component = $content.component}<Component />
    </div>
    

12. 12

    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 content

    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;
    

    Extract commandBabel compiler

    Run the extractor to transform your components and extract the content

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npx intlayer extract
    

    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 content

    Copy code

    Copy the code to the clipboard

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npm run build # Or npm run dev
    

Git Configuration

It is recommended to ignore the files generated by Intlayer.

# Ignore the files generated by Intlayer
.intlayer

Go Further

• Visual Editor: Integrate the Intlayer Visual Editor to edit translations directly from the UI.
• CMS: Externalise your content management using the Intlayer CMS.

Frequently Asked Questions