Translate your Remix 3 website using Intlayer

This guide demonstrates how to integrate Intlayer for seamless internationalization in Remix 3 applications with locale-aware routing, type-safe content declarations, server-rendered JSX components, and cross-runtime support across Node.js, Bun, Deno, and Cloudflare Workers.

What is Remix 3?

Remix 3 represents a fundamental architectural shift towards a composable, runtime-agnostic web framework built entirely on web standards. Rather than being coupled to specific bundlers or proprietary server APIs, Remix 3 is distributed as single-purpose, composable packages:

• remix/fetch-router (or remix/router): Lightweight, standard-compliant routing built on the Fetch API (Request and Response).
• remix/component: A JSX component model (jsxImportSource: "remix/component"). A component is a setup function that returns a render function, so it looks like React but keeps state in plain JavaScript closures.
• remix/middleware/render: Installs context.render(<Page />) on every request, streaming the JSX tree to an HTML Response.
• remix/node-fetch-server: Server adapters for Node.js, while natively supporting Bun, Deno, and edge runtimes.
• remix/cookie: Cryptographically secure cookie parsing and serialization.

Combined with Intlayer and the remix-intlayer package, a locale middleware plus the same useIntlayer / useDictionary / useLocale hooks as react-intlayer, bound to the Remix request context, you get a complete internationalization system that delivers compile-time safety, automated AI translations, zero-overhead server rendering, and seamless locale routing.

Table of Contents

Why Intlayer over alternatives?

Compared to traditional solutions like i18next or bespoke translation loaders, Intlayer offers an integrated developer experience optimized for modern web architecture:

Step-by-Step Guide

See the Application Template on GitHub.

1. 1

   Install Dependencies

   Install intlayer, remix-intlayer and remix (version 3) using your preferred package manager:

   bash

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   npm install intlayer remix-intlayer remix@next
   

   • intlayer: Core internationalization engine providing configuration management, dictionary declaration (t(), Dictionary), CLI tools, and runtime interpreter.
   • remix-intlayer: The Remix 3 integration: the intlayer() router middleware that resolves the locale of each request, and the useIntlayer, useDictionary and useLocale hooks that read it anywhere downstream.
   • remix: The unified Remix 3 framework package exporting remix/router, remix/routes, remix/component, remix/middleware/render, and remix/node-fetch-server.
2. 2

   Configure Intlayer

   Architecture

   In this architecture, the intlayer() middleware of remix-intlayer is registered in createRouter() ahead of the render() middleware. It strips the locale prefix before the router matches, so routes are declared once in src/routes.ts without a :locale segment, and it runs the rest of the request inside an AsyncLocalStorage scope, which is what lets useIntlayer / useLocale read the locale with no argument in route handlers and remix/component views. Content declarations are placed alongside your views in src/:

   bash

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   .
   ├── src
   │   ├── home.content.ts               # Home page content declaration
   │   ├── router.tsx                    # createRouter() with the intlayer() and render() middleware
   │   ├── routes.ts                     # Type-safe routes, declared once without locale segment
   │   ├── server.ts                     # fetch handler (Node.js, Bun, Deno, Cloudflare Workers)
   │   └── views
   │       ├── document.tsx              # HTML shell setting <html lang dir> from the locale
   │       └── home.tsx                  # Localized page using useIntlayer / useLocale
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   Configuration

   Create an intlayer.config.ts in the root of your project to declare your supported languages and internationalization settings:

   intlayer.config.ts

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

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

   For additional configuration settings (such as strict mode or routing storage preferences), refer to the configuration documentation.

   configuration documentation
3. 3

   Declare Your Multilingual Content

   Declare your localized content in a .content.ts file:

   src/home.content.ts

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { t, type Dictionary } from "intlayer";
   
   const homeContent = {
     key: "home",
     content: {
       title: t({
         en: "Welcome to Remix 3",
         fr: "Bienvenue sur Remix 3",
         es: "Bienvenido a Remix 3",
       }),
       description: t({
         en: "A composable, web-standard application with native i18n.",
         fr: "Une application composable basée sur les standards web avec i18n native.",
         es: "Una aplicación componible basada en estándares web con i18n nativa.",
       }),
       switchLanguage: t({
         en: "Switch language:",
         fr: "Changer de langue :",
         es: "Cambiar idioma:",
       }),
     },
   } satisfies Dictionary;
   
   export default homeContent;
   

   Intlayer also supports JSON, YAML, and CommonJS declaration formats. See the Content Declaration Documentation.

   Content Declaration Documentation
4. 4

   Build Intlayer Dictionaries

   Compile the dictionary definitions to generate TypeScript types and runtime registries:

   bash

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   npx intlayer build
   

   This compiles your content into the .intlayer artifact directory, enabling full TypeScript autocompletion and rapid dictionary lookup.

5. 5

   Add the Intlayer Middleware

   Remix 3 provides a composable middleware pipeline via createRouter({ middleware: [...] }).

   remix-intlayer ships the intlayer() middleware, the Remix counterpart of the next-intlayer and vite-intlayer proxies. For each incoming request it:

   1. Routes the locale, following routing.mode (prefix-no-default by default). A URL without a locale prefix is redirected to the localized URL of the detected locale (the storage cookie INTLAYER_LOCALE or custom header x-intlayer-locale, then standard Accept-Language negotiation, then your defaultLocale) unless that locale needs no prefix. A prefixed URL such as /fr/about is served from the /about route as French, /en/about is redirected to /about, and routing.rewrite rules are applied both ways (/fr/about → /fr/a-propos). Static assets and, in routing.domains setups, locale domains are handled the same way as in the other integrations.
   2. Resolves the locale into the Remix request context, as context.intlayer (or context.get(Intlayer)), with locale, defaultLocale and availableLocales.
   3. Persists the locale through the configured cookie / header, so the follow-up requests resolve the same locale.

   Because the locale prefix is stripped before the router matches, your routes are declared once, without a :locale segment, whatever the routing mode. The middleware then runs the rest of the request inside an AsyncLocalStorage scope bound to the request context, which is what lets the hooks of the package read the locale with no argument, in route handlers, views and remix/component components alike:

   typescript

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { useIntlayer, useLocale } from "remix-intlayer";
   
   // Anywhere downstream of the middleware
   const { locale, availableLocales } = useLocale();
   const { title } = useIntlayer("home");
   

   useIntlayer("home", "fr") or useIntlayer("faq", { item: 2 }) override the request locale for one call, and useDictionary(homeContent) reads an imported dictionary instead of a key. Outside of a request the hooks fall back to the default locale.

   The middleware also prepares the Intlayer dictionaries when the server starts, so a missing intlayer build does not leave the registry empty.

   Set routing.enableProxy: false in intlayer.config.ts to keep the locale resolution only and handle the routing yourself. intlayer({ ignore }) leaves the matching requests untouched (an API prefix, for instance), and intlayer({ isDevServer }) controls whether the stored locale drives redirects in the default enableProxy auto mode.

6. 6

   Define Type-Safe Routes

   Define your application routes using route() from remix/routes. Declare them once, without a locale segment. The middleware serves every locale from them:

   src/routes.ts

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { route } from "remix/routes";
   
   export const routes = route({
     home: "/",
   });
   

   Using route() gives you type-safe URL generation across your application, and getLocalizedPath applies the routing mode to it:

   typescript

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { getLocalizedPath } from "intlayer";
   
   routes.home.href(); // "/"
   getLocalizedPath(routes.home.href(), "fr"); // "/fr"
   getLocalizedPath(routes.home.href(), "en"); // "/" (default locale)
   

7. 7

   Render Localized Pages with JSX

   Remix 3 renders UI with JSX components from remix/component. A component is a setup function that receives a Handle and returns a render function. Setup runs once per instance, render runs on every update, and props are read through handle.props.

   Start with a shared Document shell that sets the <html lang="..." dir="..."> attributes from the locale resolved by the middleware:

   src/views/document.tsx

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { getHTMLTextDir } from "intlayer";
   import { useLocale } from "remix-intlayer";
   import type { Handle, RemixNode } from "remix/component";
   
   type DocumentProps = {
     title: string;
     children?: RemixNode;
   };
   
   export const Document = (handle: Handle<DocumentProps>) => () => {
     const { title, children } = handle.props;
     const { locale } = useLocale();
   
     return (
       <html lang={locale} dir={getHTMLTextDir(locale)}>
         <head>
           <meta charSet="utf-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1" />
           <title>{title}</title>
         </head>
         <body>{children}</body>
       </html>
     );
   };
   

   Then create the home page. It reads the localized dictionary with useIntlayer and renders a language switcher:

   src/views/home.tsx

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
   import { useIntlayer, useLocale } from "remix-intlayer";
   import { Document } from "./document";
   
   export const HomePage = () => () => {
     const { locale, availableLocales } = useLocale();
     const home = useIntlayer("home");
     const pathWithoutLocale = getPathWithoutLocale();
   
     return (
       <Document title={home.title}>
         <header>
           <nav aria-label="Languages">
             <span>{home.switchLanguage}</span>
             <ul>
               {availableLocales.map((localeItem) => {
                 const isActive = localeItem === locale;
   
                 return (
                   <li key={localeItem} class="p-1">
                     <a
                       href={getLocalizedUrl(pathWithoutLocale, localeItem)}
                       class={isActive ? "active" : undefined}
                       aria-current={isActive ? "page" : undefined}
                     >
                       {getLocaleName(localeItem, locale)}
                     </a>
                   </li>
                 );
               })}
             </ul>
           </nav>
         </header>
         <main>
           <h1>{home.title}</h1>
           <p>{home.description}</p>
         </main>
       </Document>
     );
   };
   

   Remix JSX is not React: class is written as-is (className is also accepted), and re-renders are triggered explicitly with handle.update(). Interpolated values are escaped automatically. The Intlayer hooks are plain functions reading the request scope, so they can be called from the setup function or the render function alike.

8. 8

   Wire Up the Router and Server

   Add the render() middleware from remix/middleware/render next to the Intlayer middleware. It installs context.render(node, init) on every request, which streams the JSX tree into an HTML Response (prepending <!DOCTYPE html> and setting the Content-Type header):

   src/router.tsx

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { intlayer } from "remix-intlayer";
   import { render } from "remix/middleware/render";
   import { createRouter } from "remix/router";
   import { routes } from "./routes";
   import { HomePage } from "./views/home";
   
   // 1. Initialize router with Intlayer + render middleware
   export const router = createRouter({
     middleware: [intlayer(), render()],
   });
   
   // 2. Map route handlers: `/`, `/fr`, `/es`… all reach `home`
   router.map(routes, {
     actions: {
       home(context) {
         return context.render(<HomePage />);
       },
     },
   });
   

   context.render accepts an optional ResponseInit as second argument, e.g. context.render(<NotFoundPage />, { status: 404 }). The resolved locale stays reachable from the handler as context.intlayer.locale, for instance to build a Response.json payload.

   Finally, expose the router through a standard fetch handler. The same router runs on Node.js, Bun, Deno, and Cloudflare Workers:

   src/server.ts

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import * as http from "node:http";
   import { createRequestListener } from "remix/node-fetch-server";
   import { router } from "./router";
   
   const PORT = Number(process.env.PORT || 3000);
   
   // Node.js
   const server = http.createServer(
     createRequestListener((request) => router.fetch(request))
   );
   
   server.listen(PORT, () => {
     console.log(`Server running at http://localhost:${PORT}`);
   });
   
   // Bun / Deno / Cloudflare Workers
   export default {
     port: PORT,
     fetch(request: Request) {
       return router.fetch(request);
     },
   };
   

9. 9

   Audit and Auto-Fill Translations

   Intlayer provides a CLI to audit for missing translations and automatically fill them using AI:

   bash

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   # Audit missing translations
   npx intlayer test
   
   # Fill missing translations using AI
   npx intlayer fill
   

TypeScript Configuration

Point JSX at the remix/component runtime and ensure that your tsconfig.json includes the generated .intlayer types:

{
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ESNext",
    "jsx": "react-jsx",
    "jsxImportSource": "remix/component",
    "skipLibCheck": true,
    "strict": true
  },
  "include": ["src/**/*", ".intlayer/**/*.ts"]
}

jsxImportSource: "remix/component" is what makes <HomePage /> resolve to Remix's createElement instead of React's.

Conclusion

With Remix 3 and Intlayer, you have a lean, fully typed, runtime-portable stack that adheres to open web standards. Your application can scale effortlessly from simple localized marketing pages to globally distributed, edge-rendered services.