remix-intl

The best internationalization(i18n) library for your Remix apps.

Features:

• 🥳 Powerful and fully under your control
• 🚀 Minimal size, less dependencies

TODO

• [ ] Make setup more simple
• [ ] Unit tests and E2E tests

What does it look like?

// app/._index.tsx
import { ActionFunctionArgs, json, type MetaFunction } from '@remix-run/node';
import { Form, useActionData, useLoaderData } from '@remix-run/react';
import { useT } from 'remix-intl';
import { getT } from 'remix-intl/server';

export const meta: MetaFunction = ({ location }) => {
  const { t } = getT(location);
  return [{ title: t('title') }];
};

export default function Index() {
  const { locales } = useLoaderData<typeof loader>();
  const actionData = useActionData<typeof action>();
  const { t } = useT();

  return (
    <div>
      <h1>{t('create_todo')}</h1>
      <Form method="post">
        <input type="text" name="title" />

        {actionData?.errors?.title ? <em>{actionData?.errors.title}</em> : null}

        <button type="submit">{t('create_todo')}</button>
      </Form>
    </div>
  );
}

export async function action({ request }: ActionFunctionArgs) {
  const body = await request.formData();
  const { t } = getT(request.url);
  if (!body.get('title')) {
    return json({ errors: { title: t('required') } });
  }
}

public/locales/en/index.json

{
  "title": "Remix App",
  "hi": "Hello",
  "required": "Required",
  "create_todo": "Create Todo"
}

Table of Contents

• remix-intl
  • TODO
  • What does it look like?
  • Table of Contents
  • Installing
  • Configuration
    • 1. Create files
      • Create i18n config file
      • Create i18n cookie file
      • Create i18n navigation components file
    • 2. Update
      • Update server entry
      • Update client entry
      • Update root.tsx
    • Create i18n messages
  • Usage
    • Different mode: segment or search
    • paramKey
    • Switch different languages
    • Link, NavLink and useNavigate
    • useT and useLocale
    • getT and getLocale in meta / loader / action
  • API
    • remix-intl API
    • i18next API
  • Website and example
  • Support

Installing

# npm
npm install remix-intl i18next

# pnpm
pnpm add remix-intl i18next

# yarn
yarn add remix-intl i18next

Configuration

1. Create files

Create i18n config file

app/i18n.ts

// app/i18n.ts
import { createInstance } from 'i18next';
import type { GetLocalesRes, GetMessagesRes, IntlConfig } from 'remix-intl/types';
import { setIntlConfig } from 'remix-intl/i18n';

const defaultNS = 'remix_intl';
const i18next = createInstance({ defaultNS, ns: [defaultNS], resources: {} });
i18next.init({
  defaultNS,
  ns: [defaultNS],
  resources: {},
});

async function getLocales(): Promise<GetLocalesRes> {
  // you can fetch dynamic locales from others API
  return { locales: ['zh-CN', 'en'] };
}

async function getMessages(locale: string, ns?: string): Promise<GetMessagesRes> {
  // you can fetch dynamic messages from others API
  const messages = await fetch(
    `http://localhost:5173/locales/${locale}/${ns || 'index'}.json`
  ).then((res) => res.json());
  return { messages, locale, ns };
}

export const intlConfig: IntlConfig = {
  mode: 'search',
  paramKey: 'lang',
  cookieKey: 'remix_intl',
  defaultNS,
  clientKey: 'remix_intl',
  defaultLocale: '',
  getLocales,
  getMessages,
  i18next,
};

setIntlConfig(intlConfig);

export default i18next;

Create i18n cookie file

app/i18n.server.ts

// app/i18n.server.ts
import { createCookie } from '@remix-run/node';
import { intlConfig } from './i18n';

export const i18nCookie = createCookie(intlConfig.cookieKey);

Create i18n navigation components file

app/navigation.tsx

// app/navigation.tsx
import { createSharedPathnamesNavigation } from 'remix-intl/navigation';

const { Link, NavLink, useNavigate, SwitchLocaleLink } = createSharedPathnamesNavigation();

export { Link, NavLink, useNavigate, SwitchLocaleLink };

2. Update

Update server entry

app/entry.server.tsx: 3 changes

// app/entry.server.tsx
import { PassThrough } from 'node:stream';

import type { AppLoadContext, EntryContext } from '@remix-run/node';
import { createReadableStreamFromReadable } from '@remix-run/node';
import { RemixServer } from '@remix-run/react';
import { isbot } from 'isbot';
import { renderToPipeableStream } from 'react-dom/server';

/* --- 1.IMPORT THIS --- */
import { initIntl } from 'remix-intl/server';
import { i18nCookie } from './i18n.server';
/* --- 1.IMPORT THIS END --- */

const ABORT_DELAY = 5_000;

/* --- 2.ADD `async` --- */
export default async function handleRequest(
  /* --- 2.ADD `async` end --- */
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext,
  loadContext: AppLoadContext
) {
  /* --- 3.ADD THIS --- */
  await initIntl(request, i18nCookie);
  /* --- 3.ADD THIS END --- */

  return isbot(request.headers.get('user-agent') || '')
    ? handleBotRequest(request, responseStatusCode, responseHeaders, remixContext)
    : handleBrowserRequest(request, responseStatusCode, responseHeaders, remixContext);
}

function handleBotRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  return new Promise((resolve, reject) => {
    let shellRendered = false;
    const { pipe, abort } = renderToPipeableStream(
      <RemixServer context={remixContext} url={request.url} abortDelay={ABORT_DELAY} />,
      {
        onAllReady() {
          shellRendered = true;
          const body = new PassThrough();
          const stream = createReadableStreamFromReadable(body);

          responseHeaders.set('Content-Type', 'text/html');

          resolve(
            new Response(stream, {
              headers: responseHeaders,
              status: responseStatusCode,
            })
          );

          pipe(body);
        },
        onShellError(error: unknown) {
          reject(error);
        },
        onError(error: unknown) {
          responseStatusCode = 500;
          if (shellRendered) {
            console.error(error);
          }
        },
      }
    );

    setTimeout(abort, ABORT_DELAY);
  });
}

function handleBrowserRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  return new Promise((resolve, reject) => {
    let shellRendered = false;
    const { pipe, abort } = renderToPipeableStream(
      <RemixServer context={remixContext} url={request.url} abortDelay={ABORT_DELAY} />,
      {
        onShellReady() {
          shellRendered = true;
          const body = new PassThrough();
          const stream = createReadableStreamFromReadable(body);

          responseHeaders.set('Content-Type', 'text/html');

          resolve(
            new Response(stream, {
              headers: responseHeaders,
              status: responseStatusCode,
            })
          );

          pipe(body);
        },
        onShellError(error: unknown) {
          reject(error);
        },
        onError(error: unknown) {
          responseStatusCode = 500;
          if (shellRendered) {
            console.error(error);
          }
        },
      }
    );

    setTimeout(abort, ABORT_DELAY);
  });
}

Update client entry

app/entry.client.tsx: 2 changes

// app/entry.client.tsx
import { RemixBrowser } from '@remix-run/react';
import { startTransition, StrictMode } from 'react';
import { hydrateRoot } from 'react-dom/client';

/* --- 1.IMPORT THIS --- */
import { ClientProvider as IntlProvider } from 'remix-intl';
/* --- 1.IMPORT THIS END --- */

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      {/* --- 2.ADD THIS --- */}
      <IntlProvider>
        <RemixBrowser />
      </IntlProvider>
      {/* --- 2.ADD THIS END--- */}
    </StrictMode>
  );
});

Update root.tsx

app/root.tsx: 4 changes

// app/root.tsx

/* --- 1.IMPORT THIS --- */
import './i18n';
import { parseLocale } from 'remix-intl/server';
import { IntlScript } from 'remix-intl';
import { i18nCookie } from './i18n.server';
/* --- 1.IMPORT THIS END --- */

import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
  useLoaderData,
  json,
  redirect,
} from '@remix-run/react';
import { LoaderFunctionArgs } from '@remix-run/node';

export async function loader({ request }: LoaderFunctionArgs) {
  /* --- 2.ADD THIS --- */
  const res = await parseLocale(request, i18nCookie);
  if (res.isRedirect) {
    return redirect(res.redirectURL);
  }
  return json(res, {
    headers: {
      'Set-Cookie': await i18nCookie.serialize(res.locale),
    },
  });
  /* --- 2.ADD THIS END --- */
}

export function Layout({ children }: { children: React.ReactNode }) {
  /* --- 3.ADD THIS --- */
  const { locale, dir } = useLoaderData<typeof loader>();
  return (
    <html lang={locale} dir={dir}>
      {/* --- 3.ADD THIS END --- */}
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
        {/* --- 4.ADD THIS --- */}
        <IntlScript />
        {/* --- 4.ADD THIS END --- */}
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}

Create i18n messages

public/locales/en/index.json

{
  "hi": "Hello"
}

public/locales/zh-CN/index.json

{
  "hi": "您好"
}

Usage

Different mode: segment or search

segment mode: https://example.com/locale/path

search mode: https://example.com/path?lang=locale

Default is search mode, you can update mode in app/i18n.ts config file.

If you choose segment mode, don't forget add file prefix ($lang). to your routes files

paramKey

Default is lang, you can change to others you like.

Switch different languages

No need refresh page example:

import { SwitchLocaleLink } from '~/navigation';

const langs = [
  {
    text: 'English',
    code: 'en',
  },
  {
    text: '简体中文',
    code: 'zh-CN',
  },
];

export default function LanguageSwitcher() {
  return (
    <div>
      {langs.map((item, idx) => {
        return (
          <SwitchLocaleLink key={item.locale} locale={item.code} query={{ idx }}>
            {item.text}
          </SwitchLocaleLink>
        );
      })}
    </div>
  );
}

Refresh page example:

import { SwitchLocaleLink } from '~/navigation';

const langs = [
  {
    text: 'English',
    code: 'en',
  },
  {
    text: '简体中文',
    code: 'zh-CN',
  },
];

export default function LanguageSwitcher() {
  return (
    <div>
      {langs.map((item) => {
        return (
          <SwitchLocaleLink reloadDocument key={item.locale} locale={item.code}>
            {item.text}
          </SwitchLocaleLink>
        );
      })}
    </div>
  );
}

Link, NavLink and useNavigate

import { Link, NavLink, useNavigate } from '~/navigation';

export default function LinkNavigate() {
  const navigate = useNavigate();
  return (
    <div>
      {/* /docs?lang=[locale] */}
      <Link to="/docs">Documents</Link>
      {/* /docs?lang=[locale] */}
      <NavLink to="/docs">Documents</NavLink>
      <button
        onClick={() => {
          /* /docs?lang=[locale] */
          navigate('/docs');
        }}>
        Go to Documents
      </button>
    </div>
  );
}

useT and useLocale

In React components, we can use useLocale to get current locale code,

and useT can get t function to translate:

import { useLocale, useT } from 'remix-intl';

export default function RemixIntlExample() {
  const locale = useLocale();
  const { t, locale: sameWithLocale } = useT();
  // or const { t,  locale: sameWithLocale } = useT(namespace);

  return (
    <div>
      <h1>{t('i18n_key')}</h1>
      <p>current locale: {locale}</p>
    </div>
  );
}

getT and getLocale in meta / loader / action

Out of react components, like inside meta, loader or action, we can use getT to get t function and translate:

import { getLocale, getT } from 'remix-intl/server';

// in `meta`
export const meta: MetaFunction = ({ location }) => {
  const { t, locale } = getT(location); // `getT` can receive location object or string pathname?search
  // or const { t, locale } = getT(location, namespace);
  const sameWithLocale = getLocale(location); // `getLocale` same paramater with `getT`

  return [{ title: t('i18n_key') }];
};

// in `loader`

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { t } = getT(request.url);
  const locale = getLocale(request.url);
  return json({ title: t('i18n_key'), locale });
};

// in `action`
export async function action({ request }: ActionFunctionArgs) {
  const body = await request.formData();
  const { t } = getT(request.url);
  if (!body.get('title')) {
    return json({ errors: { title: t('required') } });
  }
  return redirect(request.url);
}

API

remix-intl API

// hooks
import { useT, useLocale } from 'remix-intl';

// components
import { ClientProvider, IntlScript } from 'remix-intl';
import {
  Link, NavLink, SwitchLocaleLink, useNavigate
} from from '~/navigation'

// api for server
import { getT, getLocale } from 'remix-intl/server';

// utils
import { isClient, stringSimilarity, acceptLanguageMatcher } from 'remix-intl/utils';

i18next API

import { getIntlConfig } from 'remix-intl/i18n';

getIntlConfig().i18next.addResouceBundle;
getIntlConfig().i18next.dir;
getIntlConfig().i18next.getResouceBundle;

More i18next API: https://www.i18next.com/

Website and example

👉 https://remix-intl.tsdk.dev (WIP 🙇🏻‍♂️)

Support

• Any questions, feel free create issues 🙌