Skip to main content

Lingui with React Server Components

Lingui provides support for React Server Components (RSC) as of v4.10.0. In this tutorial, we'll learn how to add internationalization to an application with the Next.js App Router. However, the same principles are applicable to any RSC-based solution.

Hint

There's a working example available here. We will make references to the important parts of it throughout the tutorial. The example is more complete than this tutorial.

The example uses both Pages Router and App Router, so you can see how to use Lingui with both in this commit.

Before going further, please follow the React setup for installation and configuration instructions (for SWC or Babel depending on which you use - most likely it's SWC). You may also need to configure your tsconfig.json according to this visual guide. This is so that TypeScript understands the values exported from @lingui/react package.

Adding i18n support to Next.js​

Firstly, your Next.js app needs to be ready for routing and rendering of content in multiple languages. This is done through the middleware (see the example app's middleware). Please read the official Next.js docs for more information.

After configuring the middleware, make sure your page and route files are moved from app to app/[lang] folder (example: app/[lang]/layout.tsx). This enables the Next.js router to dynamically handle different locales in the route, and forward the lang parameter to every layout and page.

Next.js Config​

Secondly, add the swc-plugin to the next.config.js, so that you can use Lingui macros.

next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  // to use Lingui macros
  experimental: {
    swcPlugins: [["@lingui/swc-plugin", {}]],
  },
};

Setup with server components​

With Lingui, the experience of localizing React is the same in client and server components: Trans and useLingui can be used identically in both worlds, even though internally there are two implementations.

Under the hood

Translation strings, one way or another, are obtained from an I18n object instance. In client components, this instance is passed around using React context. Because context is not available in Server components, instead cache is used to maintain an I18n instance for each request.

To make Lingui work in both server and client components, we need to take the lang prop which Next.js passes to our layouts and pages, and create a corresponding instance of the I18n object. We then make it available to the components in our app. This is a 2-step process:

  1. given lang, take an I18n instance and store it in the cache so it can be used server-side
  2. given lang, take an I18n instance and make it available to client components via I18nProvider

This is how step (1) can be implemented:

src/app/[lang]/layout.tsx
import { setI18n } from "@lingui/react/server";
import { getI18nInstance } from "./appRouterI18n";
import { LinguiClientProvider } from "./LinguiClientProvider";

type Props = {
  params: {
    lang: string;
  };
  children: React.ReactNode;
};

export default function RootLayout({ params: { lang }, children }: Props) {
  const i18n = getI18nInstance(lang); // get a ready-made i18n instance for the given locale
  setI18n(i18n); // make it available server-side for the current request

  return (
    <html lang={lang}>
      <body>
        <LinguiClientProvider initialLocale={lang} initialMessages={i18n.messages}>
          <YourApp />
        </LinguiClientProvider>
      </body>
    </html>
  );
}

Step (2) is implemented in LinguiClientProvider, which is a client component:

LinguiClientProvider.tsx
"use client";

import { I18nProvider } from "@lingui/react";
import { type Messages, setupI18n } from "@lingui/core";
import { useState } from "react";

export function LinguiClientProvider({
  children,
  initialLocale,
  initialMessages,
}: {
  children: React.ReactNode;
  initialLocale: string;
  initialMessages: Messages;
}) {
  const [i18n] = useState(() => {
    return setupI18n({
      locale: initialLocale,
      messages: { [initialLocale]: initialMessages },
    });
  });
  return <I18nProvider i18n={i18n}>{children}</I18nProvider>;
}
tip

Why are we not passing the I18n instance directly from RootLayout to the client via LinguiClientProvider? It's because the I18n object isn't serializable, and cannot be passed from server to client.

Lastly, there's the appRouterI18n.ts file, which is only executed on server and holds one instance of I18n object for each locale of our application. See here how it's implemented in the example app.

Rendering translations in server and client components​

Below you can see an example of a React component. This component can be rendered both with RSC and on client. This is great if you're migrating a Lingui-based project from pages router to App Router because you can keep the same components working in both worlds.

In fact, if you swapped the html tags for their more universal alternatives, this component could also be used in React Native.

app/[lang]/components/SomeComponent.tsx
import { Trans, t } from "@lingui/macro";
import { useLingui } from "@lingui/react";

export function SomeComponent() {
  const { i18n } = useLingui();
  return (
    <div>
      <p>
        <Trans>Some Item</Trans>
      </p>
      <p>{t(i18n)`Other Item`}</p>
    </div>
  );
}

As you may recall, hooks are not supported in RSC, so you might be surprised that this works. Under RSC, useLingui is actually not a hook but a simple function call which reads from the React cache mentioned above.

The RSC implementation of useLingui uses getI18n, which is another way to obtain the I18n instance on the server.

Pages, Layouts and Lingui​

There's one last caveat: in a real-world app, you will need to localize many pages, and layouts. Because of the way the App Router is designed, the setI18n call needs to happen not only in layouts, but also in pages. Read more in:

This means you need to repeat the setI18n in every page and layout. Luckily, you can easily factor it out into a simple function call, or create a HOC with which you'll wrap pages and layouts as seen here. Please let us know if there's a known better way.

Changing the active language​

Most likely, your users will not need to change the language of the application because it will render in their preferred language (obtained from the accept-language header in the middleware), or with a fallback.

To change language, redirect users to a page with the new locale in the url. We do not recommend dynamic switching because server-rendered locale-dependent content would become stale.

Static Rendering Pitfall​

Next.js can use static rendering where it renders your pages only once at build time and then serves them to all users.

To ensure static rendering takes into account the supported locales, implement generateStaticParams which will build the content for all locales.

It's important that you do not create any locale-dependent strings at a place in the app where locale may not be initialized correctly at build time. This could result in the content being generated only for one locale, and for this reason we do not recommend using the global i18n object in such scenarios. For example:

import { i18n } from "@lingui/core";
import { t } from "@lingui/macro";
// 😰 if this code runs at build time, it'll always be in the locale
// which the imported global i18n object had at that time
const immutableGreeting = t(i18n)`Hello World`;

// ✅ this component will be statically rendered for each locale
// (specified with `generateStaticParams`)
export default function SomePage() {
  return (
    <>
      <Trans>Hello world</Trans> {/* this is fine */}
    </>
  );
}

Read more about lazy translation to see how to handle translation defined on the module level.

Further reading​