remix-i18next

The easiest way to translate your React Router framework mode apps.

[!IMPORTANT] If you're still on Remix v2, keep using remix-i18next v6 as the v7 is only compatible with React Router v7.

Why remix-i18next?

• Easy to set up, easy to use: setup only takes a few steps, and configuration is simple.
• No other requirements: remix-i18next simplifies internationalisation for your React Router app without extra dependencies.
• Production ready: remix-i18next supports passing translations and configuration options into routes from the loader.
• Take the control: remix-i18next doesn't hide the configuration so you can add any plugin you want or configure as pleased.

Setup

[!TIP] Check https://github.com/sergiodxa/react-router-i18next-example for an example application, if you have an issue compare your setup with the example.

Installation

The first step is to install it in your project with

1npm install remix-i18next i18next react-i18next i18next-browser-languagedetector

You will need to configure an i18next backend and language detector, in that case you can install them too, for the rest of the setup guide we'll use the fetch backend.

1npm install i18next-fetch-backend

Localization files

First let's create some translation files in app/locales:

1// app/locales/en.ts
2export default {
3  title: "remix-i18next (en)",
4  description: "A Remix + Vite + remix-i18next example",
5};

1// app/locales/es.ts
2import type en from "./en";
3
4export default {
5  title: "remix-i18next (es)",
6  description: "Un ejemplo de Remix + Vite + remix-i18next",
7} satisfies typeof en;

The type import and the satisfies are optional, but it will help us ensure that if we add or remove a key from the en locale (our default one) we will get a type error in the es locale so we can keep them in sync.

Setup the Middleware

Create a file named app/middleware/i18next.ts with the following code:

[!CAUTION] This depends on react-router@7.3.0 or later, and it's considered unstable until React Router middleware feature itself is considered stable. Breaking changes may happen in minor versions. Check older versions of the README for a guide on how to use RemixI18next class instead if you are using an older version of React Router or don't want to use the middleware.

1import { unstable_createI18nextMiddleware } from "remix-i18next/middleware";
2import en from "~/locales/en";
3import es from "~/locales/es";
4
5export const [i18nextMiddleware, getLocale, getInstance] =
6  unstable_createI18nextMiddleware({
7    detection: {
8      supportedLanguages: ["en", "es"],
9      fallbackLanguage: "en",
10    },
11    i18next: {
12      resources: { en: { translation: en }, es: { translation: es } },
13      // Other i18next options are available here
14    },
15  });

Then in your app/root.tsx setup the middleware:

1import { i18nextMiddleware } from "~/middleware/i18next";
2
3export const unstable_middleware = [i18nextMiddleware];

With this, on every request, the middleware will run, detect the language and set it in the router context.

You can access the language in your loaders and actions using getLocale(context) function.

If you need access to the underlying i18next instance, you can use getInstance(context). This is useful if you want to call the t function or any other i18next method.

Get the locale

From this point, you can go to any loader and get the locale using the getLocale function.

1import { getLocale } from "~/middleware/i18next";
2
3export async function loader({ context }: Route.LoaderArgs) {
4  let locale = getLocale(context);
5  let date = new Date().toLocaleDateString(locale, {
6    year: "numeric",
7    month: "2-digit",
8    day: "2-digit",
9  });
10  return { date };
11}

Send translated text to the UI

To send translated text to the UI, you can use the t function from i18next. You can get it from the context using getInstance(context).

1import { getInstance } from "~/middleware/i18next";
2
3export async function loader({ context }: Route.LoaderArgs) {
4  let i18next = getInstance(context);
5  return { title: i18next.t("title"), description: i18next.t("description") };
6}

The TFunction accessible from the i18next instance is already configured with the locale detected by the middleware.

If you want to use a different locale, you can use the i18next.getFixedT method.

1import { getInstance } from "~/middleware/i18next";
2
3export async function loader({ context }: Route.LoaderArgs) {
4  let i18next = getInstance(context);
5  let t = i18next.getFixedT("es");
6  return { title: t("title"), description: t("description") };
7}

This will return a new TFunction instance with the locale set to es.

Usage with react-i18next

So far this has configured the i18next instance to inside React Router loaders and actions, but in many cases we will need to use it directly in our React components.

To do this, we need to setup react-i18next.

Let's start by updating the entry.client.tsx and entry.server.tsx files to use the i18next instance created in the middleware.

[!TIP] If you don't have these files, run npx react-router reveal to generate them. They are hidden by default.

Update the root route

First of all, we want to send the locale detected serevr-side by the middleware to the UI. To do this, we will return the locale from the app/root.tsx route.

1import {
2  data,
3  Links,
4  Meta,
5  Outlet,
6  Scripts,
7  ScrollRestoration,
8} from "react-router";
9import { useChangeLanguage } from "remix-i18next/react";
10import type { Route } from "./+types/root";
11import {
12  getLocale,
13  i18nextMiddleware,
14  localeCookie,
15} from "./middleware/i18next";
16import { useTranslation } from "react-i18next";
17
18export const unstable_middleware = [i18nextMiddleware];
19
20export async function loader({ context }: Route.LoaderArgs) {
21  let locale = getLocale(context);
22  return data(
23    { locale },
24    { headers: { "Set-Cookie": await localeCookie.serialize(locale) } }
25  );
26}
27
28export function Layout({ children }: { children: React.ReactNode }) {
29  let { i18n } = useTranslation();
30
31  return (
32    <html lang={i18n.language} dir={i18n.dir(i18n.language)}>
33      <head>
34        <meta charSet="utf-8" />
35        <meta name="viewport" content="width=device-width, initial-scale=1" />
36        <Meta />
37        <Links />
38      </head>
39      <body>
40        {children}
41        <ScrollRestoration />
42        <Scripts />
43      </body>
44    </html>
45  );
46}
47
48export default function App({ loaderData }: Route.ComponentProps) {
49  useChangeLanguage(loaderData.locale);
50  return <Outlet />;
51}

We made a few changes here:

1. We added a loader that gets the locale from the context (set by the middleware) and returns it to the UI.
2. In the root Layout component, we use the useTranslation hook to get the i18n instance and set the lang attribute of the <html> tag, along the dir attribute.
3. We added the useChangeLanguage hook to set the language in the i18next instance, this will keep the language in sync with the locale detected by the middleware after a refresh of the loader data.

Client-side configuration

Now in your entry.client.tsx replace the default code with this:

1import Fetch from "i18next-fetch-backend";
2import i18next from "i18next";
3import { startTransition, StrictMode } from "react";
4import { hydrateRoot } from "react-dom/client";
5import { I18nextProvider, initReactI18next } from "react-i18next";
6import { HydratedRouter } from "react-router/dom";
7import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
8import { getInitialNamespaces } from "remix-i18next/client";
9
10async function main() {
11  await i18next
12    .use(initReactI18next)
13    .use(Fetch)
14    .use(I18nextBrowserLanguageDetector)
15    .init({
16      fallbackLng: "en",
17      ns: getInitialNamespaces(),
18      detection: { order: ["htmlTag"], caches: [] },
19      backend: { loadPath: "/api/locales/{{lng}}/{{ns}}" },
20    });
21
22  startTransition(() => {
23    hydrateRoot(
24      document,
25      <I18nextProvider i18n={i18next}>
26        <StrictMode>
27          <HydratedRouter />
28        </StrictMode>
29      </I18nextProvider>
30    );
31  });
32}
33
34main().catch((error) => console.error(error));

The getInitialNamespaces function from remix-i18next/client will return the namespaces that were used in the server-side rendering. This way, we can load them on the client-side before rendering the app.

We're also configuring i18next-browser-languagedetector to detect the language based on the lang attribute of the <html> tag. This way, we can use the same language detected by the middleware server-side.

API for locales

The app/entry.client.tsx has the i18next backend configured to load the locales from the path /api/locales/{{lng}}/{{ns}}. Feel free to customize this but for this guide we will use that path.

Now we need to create a route to serve the locales. So let's create a file app/routes/locales.ts and add the following code:

1import { data } from "react-router";
2import { cacheHeader } from "pretty-cache-header";
3import { z } from "zod";
4import enTranslation from "~/locales/en";
5import esTranslation from "~/locales/es";
6import type { Route } from "./+types/locales";
7
8const resources = {
9  en: { translation: enTranslation },
10  es: { translation: esTranslation },
11};
12
13export async function loader({ params }: Route.LoaderArgs) {
14  const lng = z
15    .string()
16    .refine((lng): lng is keyof typeof resources =>
17      Object.keys(resources).includes(lng)
18    )
19    .safeParse(params.lng);
20
21  if (lng.error) return data({ error: lng.error }, { status: 400 });
22
23  const namespaces = resources[lng.data];
24
25  const ns = z
26    .string()
27    .refine((ns): ns is keyof typeof namespaces => {
28      return Object.keys(resources[lng.data]).includes(ns);
29    })
30    .safeParse(params.ns);
31
32  if (ns.error) return data({ error: ns.error }, { status: 400 });
33
34  const headers = new Headers();
35
36  // On production, we want to add cache headers to the response
37  if (process.env.NODE_ENV === "production") {
38    headers.set(
39      "Cache-Control",
40      cacheHeader({
41        maxAge: "5m", // Cache in the browser for 5 minutes
42        sMaxage: "1d", // Cache in the CDN for 1 day
43        // Serve stale content while revalidating for 7 days
44        staleWhileRevalidate: "7d",
45        // Serve stale content if there's an error for 7 days
46        staleIfError: "7d",
47      })
48    );
49  }
50
51  return data(namespaces[ns.data], { headers });
52}

This file introduces two dependencies

1. Zod for validating the parameters passed to the route.
2. pretty-cache-header for generating cache headers.

They are not hard requirements, but they are useful for our example, feel free to change them or remove them.

Server-side configuration

Now in your entry.server.tsx replace the default code with this:

1import { PassThrough } from "node:stream";
2
3import type {
4  EntryContext,
5  unstable_RouterContextProvider,
6} from "react-router";
7import { createReadableStreamFromReadable } from "@react-router/node";
8import { ServerRouter } from "react-router";
9import { isbot } from "isbot";
10import type { RenderToPipeableStreamOptions } from "react-dom/server";
11import { renderToPipeableStream } from "react-dom/server";
12import { I18nextProvider } from "react-i18next";
13import { getInstance } from "./middleware/i18next";
14
15export const streamTimeout = 5_000;
16
17export default function handleRequest(
18  request: Request,
19  responseStatusCode: number,
20  responseHeaders: Headers,
21  entryContext: EntryContext,
22  routerContext: unstable_RouterContextProvider
23) {
24  return new Promise((resolve, reject) => {
25    let shellRendered = false;
26    let userAgent = request.headers.get("user-agent");
27
28    let readyOption: keyof RenderToPipeableStreamOptions =
29      (userAgent && isbot(userAgent)) || entryContext.isSpaMode
30        ? "onAllReady"
31        : "onShellReady";
32
33    let { pipe, abort } = renderToPipeableStream(
34      <I18nextProvider i18n={getInstance(routerContext)}>
35        <ServerRouter context={entryContext} url={request.url} />
36      </I18nextProvider>,
37      {
38        [readyOption]() {
39          shellRendered = true;
40          let body = new PassThrough();
41          let stream = createReadableStreamFromReadable(body);
42
43          responseHeaders.set("Content-Type", "text/html");
44
45          resolve(
46            new Response(stream, {
47              headers: responseHeaders,
48              status: responseStatusCode,
49            })
50          );
51
52          pipe(body);
53        },
54        onShellError(error: unknown) {
55          reject(error);
56        },
57        onError(error: unknown) {
58          responseStatusCode = 500;
59          if (shellRendered) console.error(error);
60        },
61      }
62    );
63
64    setTimeout(abort, streamTimeout + 1000);
65  });
66}

Here we are using the getInstance function from the middleware to get the i18next instance.

This way, we can re-use the instance created in the middleware and avoid creating a new one. And since the instance is already configured with the language we detected, we can use it directly in the I18nextProvider.

Finding the locale from the request URL pathname

If you want to keep the user locale on the pathname, you have two possible options.

First option is to ignore the locale detected by the middleware and manually grab the locale from the URL pathname.

Second options is to pass a findLocale function to the detection options in the middleware.

1import { unstable_createI18nextMiddleware } from "remix-i18next/middleware";
2
3export const [i18nextMiddleware, getLocale, getInstance] =
4  unstable_createI18nextMiddleware({
5    detection: {
6      supportedLanguages: ["es", "en"],
7      fallbackLanguage: "en",
8      findLocale(request) {
9        let locale = request.url.pathname.split("/").at(1);
10        return locale;
11      },
12    },
13    i18next: {
14      resources: { en: { translation: en }, es: { translation: es } },
15    },
16  });

The locale returned by findLocale will be validated against the list of supported locales, in case it's not valid the fallback locale will be used.

Querying the locale from the database

If your application stores the user locale in the database, you can use findLocale function to query the database and return the locale.

1export let i18n = new RemixI18Next({
2  detection: {
3    supportedLanguages: ["es", "en"],
4    fallbackLanguage: "en",
5    async findLocale(request) {
6      let user = await db.getUser(request);
7      return user.locale;
8    },
9  },
10});

Store the locale in a cookie

If you want to store the locale in a cookie, you can create a cookie using createCookie helper from React Router and pass the Cookie object to the middleware.

1import { createCookie } from "react-router";
2
3export const localeCookie = createCookie("lng", {
4  path: "/",
5  sameSite: "lax",
6  secure: process.env.NODE_ENV === "production",
7  httpOnly: true,
8});

Then you can pass the cookie to the middleware:

1import { unstable_createI18nextMiddleware } from "remix-i18next/middleware";
2import { localeCookie } from "~/cookies";
3
4export const [i18nextMiddleware, getLocale, getInstance] =
5  unstable_createI18nextMiddleware({
6    detection: {
7      supportedLanguages: ["es", "en"],
8      fallbackLanguage: "en",
9      cookie: localeCookie,
10    },
11    i18next: {
12      resources: { en: { translation: en }, es: { translation: es } },
13    },
14  });

now the middleware will read the locale from the cookie, if it exists, and set it in the context. If the cookie doesn't exist, it will use the Accept-Language header or the fallback language.

Then in your routes, you can use this cookie to save the user preference, a simple way is to navigate the user to the same URL with ?lng=es (replacing es with the desired language) and then in the app/root.tsx route set the cookie with the new value.

1import { data } from "react-router";
2import { localeCookie } from "~/cookies";
3import { getLocale } from "~/middleware/i18next";
4
5export async function loader({ context }: Route.LoaderArgs) {
6  let locale = getLocale(context);
7  return data(
8    { locale },
9    { headers: { "Set-Cookie": await localeCookie.serialize(locale) } }
10  );
11}

Store the locale in the session

Similarly to the cookie, you can store the locale in the session. To do this, you can create a session using createSessionStorage helpers from React Router and pass the SessionStorage object to the middleware.

1import { createCookieSessionStorage } from "react-router";
2
3export const sessionStorage = createCookieSessionStorage({
4  cookie: {
5    name: "session",
6    path: "/",
7    sameSite: "lax",
8    secure: process.env.NODE_ENV === "production",
9    httpOnly: true,
10  },
11});

Then you can pass the session to the middleware:

1import { unstable_createI18nextMiddleware } from "remix-i18next/middleware";
2import { sessionStorage } from "~/session";
3
4export const [i18nextMiddleware, getLocale, getInstance] =
5  unstable_createI18nextMiddleware({
6    detection: {
7      supportedLanguages: ["es", "en"],
8      fallbackLanguage: "en",
9      sessionStorage,
10    },
11    i18next: {
12      resources: { en: { translation: en }, es: { translation: es } },
13    },
14  });

Now the middleware will read the locale from the session, if it exists, and set it in the context. If the session doesn't exist, it will use the Accept-Language header or the fallback language.

Then in your routes, you can use this session to save the user preference, a simple way is to navigate the user to the same URL with ?lng=es (replacing es with the desired language) and then in the app/root.tsx route set the session with the new value.

1import { data } from "react-router";
2import { sessionStorage } from "~/session";
3import { getLocale } from "~/middleware/i18next";
4
5export async function loader({ request, context }: Route.LoaderArgs) {
6  let locale = getLocale(context);
7
8  let session = await sessionStorage.getSession(request.headers.get("Cookie"));
9  session.set("lng", locale);
10
11  return data(
12    { locale },
13    { headers: { "Set-Cookie": await sessionStorage.commitSession(session) } }
14  );
15}