Translate your Vite and Preact website using Intlayer | Internationalization (i18n)

Table of Contents

What is Intlayer?

Intlayer is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern web applications.

With Intlayer, you can:

• Easily manage translations using declarative dictionaries at the component level.
• Dynamically localize metadata, routes, and content.
• Ensure TypeScript support with autogenerated types, improving autocompletion and error detection.
• Benefit from advanced features, like dynamic locale detection and switching.

Step-by-Step Guide to Set Up Intlayer in a Vite and Preact Application

See Application Template on GitHub.

Step 1: Install Dependencies

Install the necessary packages using npm:

npm install intlayer preact-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer

  The core package that provides internationalization tools for configuration management, translation, content declaration, transpilation, and CLI commands.

• preact-intlayer The package that integrates Intlayer with Preact application. It provides context providers and hooks for Preact internationalization.

• vite-intlayer Includes the Vite plugin for integrating Intlayer with the Vite bundler, as well as middleware for detecting the user's preferred locale, managing cookies, and handling URL redirection.

Step 2: Configuration of your project

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

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Your other locales
    ],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    mode: "prefix-no-default", // Default: prefix all locales except the default locale
    storage: ["cookie", "header"], // Default: store locale in cookie and detect from header
  },
};

export default config;

Through this configuration file, you can set up localized URLs, routing modes, storage options, 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.

Step 3: Integrate Intlayer in Your Vite Configuration

Add the intlayer plugin into your configuration.

import { defineConfig } from "vite";
import preact from "@preact/preset-vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [preact(), intlayer()],
});

The intlayer() Vite plugin is used to integrate Intlayer with Vite. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Vite application. Additionally, it provides aliases to optimize performance.

Step 4: Declare Your Content

Create and manage your content declarations to store translations:

import { t, type Dictionary } from "intlayer";
import type { ComponentChildren } from "preact";

const appContent = {
  key: "app",
  content: {
    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    preactLogo: t({
      en: "Preact logo",
      fr: "Logo Preact",
      es: "Logo Preact",
    }),

    title: "Vite + Preact",

    count: t({
      en: "count is ",
      fr: "le compte est ",
      es: "el recuento es ",
    }),

    edit: t<ComponentChildren>({
      en: (
        <>
          Edit <code>src/app.tsx</code> and save to test HMR
        </>
      ),
      fr: (
        <>
          Éditez <code>src/app.tsx</code> et enregistrez pour tester HMR
        </>
      ),
      es: (
        <>
          Edita <code>src/app.tsx</code> y guarda para probar HMR
        </>
      ),
    }),

    readTheDocs: t({
      en: "Click on the Vite and Preact logos to learn more",
      fr: "Cliquez sur les logos Vite et Preact pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Preact para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

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

For more details, refer to the content declaration documentation.

If your content file includes TSX code, you might need to import import { h } from "preact"; or ensure your JSX pragma is correctly set for Preact.

Step 5: Utilize Intlayer in Your Code

Access your content dictionaries throughout your application:

import { useState } from "preact/hooks";
import type { FunctionalComponent } from "preact";
import preactLogo from "./assets/preact.svg"; // Assuming you have a preact.svg
import viteLogo from "/vite.svg";
import "./app.css"; // Assuming your CSS file is named app.css
import { IntlayerProvider, useIntlayer } from "preact-intlayer";

const AppContent: FunctionalComponent = () => {
  const [count, setCount] = useState(0);
  const content = useIntlayer("app");

  return (
    <>
      <div>
        <a href="https://vitejs.dev" target="_blank">
          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
        </a>
        <a href="https://preactjs.com" target="_blank">
          <img
            src={preactLogo}
            class="logo preact"
            alt={content.preactLogo.value}
          />
        </a>
      </div>
      <h1>{content.title}</h1>
      <div class="card">
        <button onClick={() => setCount((count) => count + 1)}>
          {content.count}
          {count}
        </button>
        <p>{content.edit}</p>
      </div>
      {/* Markdown content */}
      <div>{content.myMarkdownContent}</div>

      {/* HTML content */}
      <div>{content.myHtmlContent}</div>

      <p class="read-the-docs">{content.readTheDocs}</p>
    </>
  );
};

const App: FunctionalComponent = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

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 content

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)}" />

Note: In Preact, className is typically written as class.

To Learn more about the useIntlayer hook, refer to the documentation (The API is similar for preact-intlayer).

If your app already exists, you can use the Intlayer Compiler, as well as the extract command, to transform thousands of components in a second.

(Optional) Step 6: Change the language of your content

To change the language of your content, you can use the setLocale function provided by the useLocale hook. This function allows you to set the locale of the application and update the content accordingly.

import type { FunctionalComponent } from "preact";
import { Locales } from "intlayer";
import { useLocale } from "preact-intlayer";

const LocaleSwitcher: FunctionalComponent = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.ENGLISH)}>
      Change Language to English
    </button>
  );
};

export default LocaleSwitcher;

To Learn more about the useLocale hook, refer to the documentation (The API is similar for preact-intlayer).

(Optional) Step 7: Add localized Routing to your application

The purpose of this step is to make unique routes for each language. This is useful for SEO and SEO-friendly URLs. Example:

- https://example.com/about- https://example.com/es/about- https://example.com/fr/about

By default, the routes are not prefixed for the default locale. If you want to prefix the default locale, you can set the routing.mode option to "prefix-all" in your configuration. See the configuration documentation for more information.

To add localized routing to your application, you can create a LocaleRouter component that wraps your application's routes and handles locale-based routing. Here is an example using preact-iso:

import { localeMap } from "intlayer";
import { IntlayerProvider } from "preact-intlayer";
import { LocationProvider, Router, Route } from "preact-iso";
import type { ComponentChildren, FunctionalComponent } from "preact";

/**
 * A router component that sets up locale-specific routes.
 * It uses preact-iso to manage navigation and render localized components.
 */
export const LocaleRouter: FunctionalComponent<{
  children: ComponentChildren;
}> = ({ children }) => (
  <LocationProvider>
    <Router>
      {localeMap(({ locale, urlPrefix }) => ({ locale, urlPrefix }))
        .sort((a, b) => b.urlPrefix.length - a.urlPrefix.length)
        .map(({ locale, urlPrefix }) => (
          <Route
            key={locale}
            path={`${urlPrefix}/:rest*`}
            component={() => (
              <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
            )}
          />
        ))}
    </Router>
  </LocationProvider>
);

Then, you can use the LocaleRouter component in your application:

import { LocaleRouter } from "./components/LocaleRouter";
import type { FunctionalComponent } from "preact";

// ... Your AppContent component

const App: FunctionalComponent = () => (
  <LocaleRouter>
    <AppContent />
  </LocaleRouter>
);

export default App;

In parallel, you can also use the intlayerProxy to add server-side routing to your application. This plugin will automatically detect the current locale based on the URL and set the appropriate locale cookie. If no locale is specified, the plugin will determine the most appropriate locale based on the user's browser language preferences. If no locale is detected, it will redirect to the default locale.

Note that to use the intlayerProxy in production, you need to switch the vite-intlayer package from devDependencies to dependencies.

import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";import preact from "@preact/preset-vite";// https://vitejs.dev/config/export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    preact(),    intlayer(),  ],});

(Optional) Step 8: Change the URL when the locale changes

To change the URL when the locale changes, you can use the onLocaleChange prop provided by the useLocale hook. In parallel, you can use the route method from useLocation of preact-iso to update the URL path.

import { useLocation } from "preact-iso";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "preact-intlayer";
import type { FunctionalComponent } from "preact";

const LocaleSwitcher: FunctionalComponent = () => {
  const { url, route } = useLocation();
  const { locale, availableLocales, setLocale } = useLocale({
    onLocaleChange: (newLocale) => {
      // Construct the URL with the updated locale
      // Example: /es/about?foo=bar
      const pathWithLocale = getLocalizedUrl(url, newLocale);

      // Update the URL path
      route(pathWithLocale, true); // true for replace
    },
  });

  return (
    <div>
      <button popovertarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <a
            href={getLocalizedUrl(url, localeItem)}
            hreflang={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={(e) => {
              e.preventDefault();
              setLocale(localeItem);
              // Programmatic navigation after setting locale will be handled by onLocaleChange
            }}
            key={localeItem}
          >
            <span>
              {/* Locale - e.g. FR */}
              {localeItem}
            </span>
            <span>
              {/* Language in its own Locale - e.g. Français */}
              {getLocaleName(localeItem, localeItem)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Language in current Locale - e.g. Francés with current locale set to Locales.SPANISH */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Language in English - e.g. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </a>
        ))}
      </div>
    </div>
  );
};

export default LocaleSwitcher;

Documentation references:

- useLocale hook (API is similar for preact-intlayer)> - getLocaleName hook> - getLocalizedUrl hook> - getHTMLTextDir hook> - hreflang attribute> - lang attribute> - dir attribute> - aria-current attribute> - Popover API

Below is the updated Step 9 with added explanations and refined code examples:

(Optional) Step 9: Switch the HTML Language and Direction Attributes

When your application supports multiple languages, it's crucial to update the <html> tag's lang and dir attributes to match the current locale. Doing so ensures:

• Accessibility: Screen readers and assistive technologies rely on the correct lang attribute to pronounce and interpret content accurately.
• Text Rendering: The dir (direction) attribute ensures that text is rendered in the proper order (e.g., left-to-right for English, right-to-left for Arabic or Hebrew), which is essential for readability.
• SEO: Search engines use the lang attribute to determine the language of your page, helping to serve the right localized content in search results.

By updating these attributes dynamically when the locale changes, you guarantee a consistent and accessible experience for users across all supported languages.

Implementing the Hook

Create a custom hook to manage the HTML attributes. The hook listens for locale changes and updates the attributes accordingly:

import { useEffect } from "preact/hooks";
import { useLocale } from "preact-intlayer";
import { getHTMLTextDir } from "intlayer";

/**
 * Updates the HTML <html> element's `lang` and `dir` attributes based on the current locale.
 * - `lang`: Informs browsers and search engines of the page's language.
 * - `dir`: Ensures the correct reading order (e.g., 'ltr' for English, 'rtl' for Arabic).
 *
 * This dynamic update is essential for proper text rendering, accessibility, and SEO.
 */
export const useI18nHTMLAttributes = () => {
  const { locale } = useLocale();

  useEffect(() => {
    // Update the language attribute to the current locale.
    document.documentElement.lang = locale;

    // Set the text direction based on the current locale.
    document.documentElement.dir = getHTMLTextDir(locale);
  }, [locale]);
};

Using the Hook in Your Application

Integrate the hook into your main component so that the HTML attributes update whenever the locale changes:

import type { FunctionalComponent } from "preact";
import { IntlayerProvider } from "preact-intlayer"; // useIntlayer already imported if AppContent needs it
import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
import "./app.css";
// AppContent definition from Step 5

const AppWithHooks: FunctionalComponent = () => {
  // Apply the hook to update the <html> tag's lang and dir attributes based on the locale.
  useI18nHTMLAttributes();

  // Assuming AppContent is your main content display component from Step 5
  return <AppContent />;
};

const App: FunctionalComponent = () => (
  <IntlayerProvider>
    <AppWithHooks />
  </IntlayerProvider>
);

export default App;

By applying these changes, your application will:

• Ensure the language (lang) attribute correctly reflects the current locale, which is important for SEO and browser behavior.
• Adjust the text direction (dir) according to the locale, enhancing readability and usability for languages with different reading orders.
• Provide a more accessible experience, as assistive technologies depend on these attributes to function optimally.

(Optional) Step 10: Creating a Localized Link Component

To ensure that your application's navigation respects the current locale, you can create a custom Link component. This component automatically prefixes internal URLs with the current language.

This behavior is useful for several reasons:

• SEO and User Experience: Localized URLs help search engines index language-specific pages correctly and provide users with content in their preferred language.
• Consistency: By using a localized link throughout your application, you guarantee that navigation stays within the current locale, preventing unexpected language switches.
• Maintainability: Centralizing the localization logic in a single component simplifies the management of URLs.

Below is the implementation of a localized Link component in Preact:

import { getLocalizedUrl } from "intlayer";
import { useLocale } from "preact-intlayer";
import { forwardRef } from "preact/compat";
import type { JSX } from "preact";

export interface LinkProps extends JSX.HTMLAttributes<HTMLAnchorElement> {
  href: string;
}

/**
 * Utility function to check whether a given URL is external.
 * If the URL starts with http:// or https://, it's considered external.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * A custom Link component that adapts the href attribute based on the current locale.
 * For internal links, it uses `getLocalizedUrl` to prefix the URL with the locale (e.g., /fr/about).
 * This ensures that navigation stays within the same locale context.
 */
export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
  ({ href, children, ...props }, ref) => {
    const { locale } = useLocale();
    const isExternalLink = checkIsExternalLink(href);

    // If the link is internal and a valid href is provided, get the localized URL.
    const hrefI18n =
      href && !isExternalLink ? getLocalizedUrl(href, locale) : href;

    return (
      <a href={hrefI18n} ref={ref} {...props}>
        {children}
      </a>
    );
  }
);

Link.displayName = "Link";

How It Works

• Detecting External Links:
  The helper function checkIsExternalLink determines whether a URL is external. External links are left unchanged because they do not need localization.
• Retrieving the Current Locale:
  The useLocale hook provides the current locale (e.g., fr for French).
• Localizing the URL:
  For internal links (i.e., non-external), getLocalizedUrl is used to automatically prefix the URL with the current locale. This means that if your user is in French, passing /about as the href will transform it to /fr/about.
• Returning the Link:
  The component returns an <a> element with the localized URL, ensuring that navigation is consistent with the locale.

(Optional) Step 11: Render Markdown and HTML

Intlayer supports rendering Markdown and HTML content in Preact.

You can customize the rendering of Markdown and HTML content by using the .use() method. This method allows you to override the default rendering of specific tags.

import { useIntlayer } from "preact-intlayer";const { myMarkdownContent, myHtmlContent } = useIntlayer("my-component");// ...return (  <div>    {/* Basic rendering */}    {myMarkdownContent}    {/* Custom rendering for Markdown */}    {myMarkdownContent.use({      h1: (props) => <h1 style={{ color: "red" }} {...props} />,    })}    {/* Basic rendering for HTML */}    {myHtmlContent}    {/* Custom rendering for HTML */}    {myHtmlContent.use({      b: (props) => <strong style={{ color: "blue" }} {...props} />,    })}  </div>);

(Optional) Step 12: Extract the content of your components

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

To ease this process, Intlayer propose 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:

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;

npx intlayer extract

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

npm run build # Or npm run dev

(Optional) Sitemap and robots.txt (build-time)

Intlayer includes formatters such as generateSitemap and getMultilingualUrls that produce crawler-ready multilingual sitemap.xml and robots.txt output you can write into your project’s public/ folder. In practice you run a small Node script before Vite (for example predev / prebuild npm hooks) so those files exist when you build or serve the app.

Sitemap

Intlayer’s sitemap generator respects your locale setup and includes the usual metadata for crawlers.

The generated sitemap supports the xhtml:link namespace (hreflang XML extensions). Unlike basic generators that only emit flat URLs, Intlayer wires bidirectional links between every localized variant of each page (for example /about, /fr/about, or /about?lang=fr, depending on your routing mode), which helps search engines relate localized URLs.

Robots.txt

Use getMultilingualUrls so Disallow entries cover every localized spelling of sensitive paths.

1. Add generate-seo.mjs at the project root

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

intlayer must be installed so the script can import it. Set SITE_URL in the environment for production (for example in CI).

Prefer generate-seo.mjs for Node ESM. If you use generate-seo.js instead, ensure "type": "module" is set in package.json, or run Node with ESM enabled.

2. Run the script before Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Adjust if you use pnpm or yarn. You can also invoke the same script from CI or another step if that fits your workflow.

Configure TypeScript

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

Ensure your TypeScript configuration includes the autogenerated types.

{  // ... Your existing TypeScript configurations  "compilerOptions": {    // ...    "jsx": "react-jsx",    "jsxImportSource": "preact", // Recommended for Preact 10+    // ...  },  "include": [    // ... Your existing TypeScript configurations    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

Ensure your tsconfig.json is set up for Preact, especially jsx and jsxImportSource or jsxFactory/jsxFragmentFactory for older Preact versions if not using preset-vite's defaults.

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:

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

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

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