Getting Started Internationalising (i18n) with Intlayer and Vite and Preact

This package is in development. See the issue for more information. Show your interest in Intlayer for Preact by liking the issue

See Application Template on GitHub.

Why Intlayer over alternatives?

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

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

1. 1

   Install Dependencies

   Install the necessary packages using npm:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

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

   • intlayer

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

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

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

2. 2

   Configuration of your project

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

   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,
         // 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 localised 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.

3. 3

   Integrate Intlayer in Your Vite Configuration

   Add the intlayer plugin into your configuration.

   vite.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   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 optimise performance.

4. 4

   Declare Your Content

   Create and manage your content declarations to store translations:

   src/app.content.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   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> and 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 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}).

   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.

5. 5

   Utilise Intlayer in Your Code

   Access your content dictionaries throughout your application:

   src/app.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

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

6. 6

   Change the language of your content

   Optional

   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.

   src/components/LocaleSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

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

7. 7

   Add localised Routing to your application

   Optional

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

   plaintext

   Copy content

   Copy code

   Copy the code to the clipboard

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

   src/components/LocaleRouter.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

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

   src/app.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { LocaleRouter } from "./components/LocaleRouter";
   import type { FunctionalComponent } from "preact";
   
   // ... Your AppContent component
   
   const App: FunctionalComponent = () => (
     <LocaleRouter>
       <AppContent />
     </LocaleRouter>
   );
   
   export default App;

8. 8

   Change the URL when the locale changes

   Optional

   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.

   src/components/LocaleSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   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

9. 9

   Switch the HTML Language and Direction Attributes

   Optional

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

   src/hooks/useI18nHTMLAttributes.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   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:

   src/app.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   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;

10. 10

    Creating a Localised Link Component

    Optional

    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 behaviour is useful for several reasons:

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

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

    src/components/Link.tsx

    Copy content

    Copy code

    Copy the code to the clipboard

    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 localised 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 localisation.
    • Retrieving the Current Locale:
      The useLocale hook provides the current locale (e.g., fr for French).
    • Localising 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 localised URL, ensuring that navigation is consistent with the locale.
11. 11

    Render Markdown and HTML

    Optional

    Intlayer supports rendering Markdown and HTML content in Preact.

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

    tsx

    Copy content

    Copy code

    Copy the code to the clipboard

    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) 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 uses module augmentation to get the 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 externalise your content using the CMS.