Setting up i18n in Remix

Background

For the past few months, I’ve been working on my side project, and one of the biggest game changers has been using Remix instead of Next.js. While my day job involves Next.js (Page Router), I found Remix—especially when paired with Vite—to be a breath of fresh air. The performance gains alone make it worth the switch, but what I love most is how Remix keeps things simple and close to web fundamentals.

That said, one challenge I ran into was setting up internationalization (i18n). Remix’s official i18n guide provides a good starting point, but when I started integrating i18n into my app, I hit several roadblocks that weren’t covered. So I decided to document my approach—what worked, what didn’t, and the solutions I ended up using.

The i18n Challenges I Encountered in Remix

While setting up i18n in Remix, these were the key issues I ran into:

  1. Vite warnings when loading locale files from the public/ folder
  2. Handling translations in Storybook
  3. Avoiding duplication when managing translation files
  4. Preventing the flash of untranslated content (FOUC) on page load

Let’s go through each challenge and how I solved them.

Dynamically Importing Translation Files

Rather than manually defining my translation resources, I leveraged Vite’s import.meta.glob to dynamically import all JSON files:

// app/i18n.resources.ts
import type { Resource } from "i18next";

const translationModules = import.meta.glob("./locales/*/*.json", {
  eager: true,
  import: "default",
});

export const resources = Object.entries(translationModules).reduce<Resource>(
  (acc, [path, module]) => {
    const [, , locale, namespace] = path.split("/");
    const ns = namespace.replace(".json", "");

    if (!acc[locale]) {
      acc[locale] = {};
    }
    acc[locale][ns] = module as any;
    return acc;
  },
  {},
);

With this, I no longer have to manually update my translation setup when adding new locales—it’s all handled dynamically.

Moving Locale Files Inside the App Directory

Many i18n tutorials suggest placing translation files in public/, but this won't work with the dynamic setup that I shared on the previous section.

In Remix (with Vite), this causes warnings because Vite treats public/ as a static asset folder and doesn’t expect dynamic imports from it.

My Solution: Store Locales in app/locales/

Instead of using public/, I moved my locale files to app/locales/ and created a dedicated API route to serve them dynamically.

New Directory Structure:

app/
├── locales/
│   ├── en/
│   │   ├── common.json
│   │   └── home.json
│   └── ja/
│       ├── common.json
│       └── home.json

Custom Route for Fetching Locales:

// app/routes/locales.$lng.$ns.ts
import { json } from "@remix-run/cloudflare";
import type { LoaderFunctionArgs } from "@remix-run/cloudflare";
import { resources } from "~/i18n.resources";

export async function loader({ params }: LoaderFunctionArgs) {
  const { lng, ns } = params;

  if (!lng || !ns) {
    return json({ error: "Missing language or namespace" }, { status: 400 });
  }

  if (!resources[lng]?.[ns]) {
    return json({ error: "Resource not found" }, { status: 404 });
  }

  return json(resources[lng][ns]);
}

Now, instead of fetching translation files from public/locales/en/common.json, I request them from /locales/en/common. This avoids Vite warnings and gives me more control over error handling and transformations.

Configuring i18next to Use the Custom Route

Now that I had a custom route serving translations, I updated my i18next setup to fetch translations from it:

// app/i18n.client.ts
import i18next from "i18next";
import Backend from "i18next-http-backend";
import { initReactI18next } from "react-i18next";
import { resources } from "./i18n.resources";

const instance = i18next.use(initReactI18next).use(Backend);

instance.init({
  resources, // Preload resources to prevent FOUC
  fallbackLng: "en",
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}",
  },
});

This ensures translations are loaded smoothly and avoids a flash of untranslated content.

Making Storybook Work with i18n

Storybook needs access to translation files, so I updated my Storybook config to serve them properly:

// .storybook/main.ts
const config = {
  staticDirs: ["../public", { from: "../app/locales", to: "locales" }],
};
export default config;

This ensures Storybook finds the translation files in the correct location.

Preventing Flash of Untranslated Content (FOUC)

One of the most frustrating things about client-side i18n is seeing untranslated keys flash before the translations load. To prevent this, I did two things:

1. Preloading Translations on the Server

// app/entry.server.tsx
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next";
import { resources } from "./i18n.resources";

const instance = createInstance();
await instance.use(initReactI18next).init({
  resources,
  lng: "en",
});

2. Wrapping the App in I18nextProvider

// app/root.tsx
import { I18nextProvider } from 'react-i18next'
import i18next from '~/i18n.client'

export default function App() {
  return (
    <I18nextProvider i18n={i18next}>
      <html>
        {/* App content */}
      </html>
    </I18nextProvider>
  )
}

This ensures translations are ready from the start and prevents flickering.

Final Thoughts

Setting up i18n in Remix was trickier than I expected, but after going through the process, here are my key takeaways:

  • Store locale files in app/locales/ instead of public/ to avoid Vite warnings
  • Create a dedicated API route for translations instead of fetching static JSON files
  • Use import.meta.glob to dynamically import translations
  • Configure Storybook to find translations properly
  • Preload translations on the server to prevent FOUC

Hopefully, this helps if you're setting up i18n in Remix. Let me know if you run into similar challenges—I’d love to hear how you solved them!

Latest Posts