Using typesafe-i18n with Next.js 13 App Directory

[AngaBlue]

Data fetching changes significantly with Next.js 13 App Directory and I'm not sure how to implement typesafe-i18n with the removal of getStaticProps. Any help would be appreciated!

[ivanhofer]

I can check if I find some time next week. Haven't used Next.js 13 yet.

[AngaBlue]

That would be greatly apprecaited. I look forward to hearing back from you!

[osdiab]

Also keen on this, thanks!

[ivanhofer]

Unfortunately I don't had time to do it until now and it also does not look that good in the next weeks.

In the end it is just making the correct calls in the correct places. You need to first understand how the whole workflow of Next.js works and then you need to call the correct functions where it makes sense. It is a bit of a trial and error approach 🙃

[billytheme]

I just did a writeup of how we achieved it, hopefully it can help you.

[AngaBlue]

A colleague of mine has figured this out. When i get the chance, I'll post an overview.

…

On Thu, 11 May 2023, 02:32 Hofer Ivan, ***@***.***> wrote: Unfortunately I don't had time to do it until now and it also does not look that good in the next weeks. In the end it is just making the correct calls in the correct places. You need to first understand how the whole workflow of Next.js works and then you need to call the correct functions where it makes sense. It is a bit of a trial and error approach 🙃 — Reply to this email directly, view it on GitHub <#580 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AJQOHJKK6SVORWNOTHSK2Z3XFPNMLANCNFSM6AAAAAAUHD3FLI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[ivanhofer]

That would be great, thanks!

[billytheme]

I am the colleague @AngaBlue mentioned. This overview might not be the best way to do this, and there may be some inconsistencies, but it does work.

This guide is for route-based locale, rather than subdomain-based locale. You could probably get it working using subdomain-based, but it would need some adaption.

The first problem is that Next.js App router has either removed support for native locale navigation, or hasn't implemented it yet (its not clear from the docs whether they intend to do so in future), so we have to implement it ourselves. The Next.js documentation on this is actually not bad, (https://nextjs.org/docs/app/building-your-application/routing/internationalization), so we can roughly follow that. Basically, it boils down to putting all your pages inside a dynamic route, like so (I've called ours lang, but it can be called whatever you want):

This allows you to catch and handle the locale from the path as part of the params on each page.

Next, we need to ensure that users always have a locale prefix in their path, otherwise it might result in some parsing errors. We can do this with middleware redirects. Put a middleware.ts file in the root of your project (next to next.config.js), and add the following code:

import { NextRequest, NextResponse } from 'next/server';
import { initAcceptLanguageHeaderDetector, initRequestCookiesDetector } from 'typesafe-i18n/detectors';
import { detectLocale, locales } from './i18n/i18n-util';

// Get the preferred locale. This is where we allow the serverside typesafe-i18n detectors to work.
function getLocale(request: NextRequest) {
    const requestCookiesDetector = initRequestCookiesDetector({
        cookies: request.cookies.toString()
    });
    const acceptLanguageHeaderDetector = initAcceptLanguageHeaderDetector(request);
    return detectLocale(requestCookiesDetector, acceptLanguageHeaderDetector);
}

export function middleware(request: NextRequest) {
    // Check if there is any supported locale in the pathname
    const { pathname } = request.nextUrl;

    const pathnameIsMissingLocale = locales.every(locale => !pathname.startsWith(`/${locale}/`) && pathname !== `/${locale}`);

    // Redirect if there is no locale
    if (pathnameIsMissingLocale) {
        const locale = getLocale(request);

        // e.g. incoming request is /products
        // The new URL is now /en-US/products
        return NextResponse.redirect(new URL(`/${locale}${pathname}`, request.url));
    }
}

export const config = {
    matcher: [
        // Skip all internal, statically exported, and locale paths
        // This regex says: do NOT run if the path contains _next, do not run if the path contains . (this is to not run on things in the public directory), do not run if the path contains en
        // This should be updated with all locales as we add them
        '/((?!_next)(?=[^\.]*$)(?!en)(?!es).*)'
    ]
};

Basically, that code checks whether the path already has a relevant locale in it, and if not, attempts to recognize the user's language selection from cookies, falls back to headers, and then falls back to the baseLocale.

The most confusing part is the regex matcher. We want to avoid locale-ing any internal next pages (_next/...), and any static exports (usually the public/ folder). In our case, we found that all our static exports had a file extension, while all our locale'd pages did not, so we could filter by the inclusion of a '.' in the filename. If that is not the case for you, you will need to change the regex. The final part of the regex filters out known locale paths. We do this because otherwise, the middleware will run any time a user visits any page. That can get very expensive, so we filter out paths that already have been redirected. Unfortunately, the matcher string must be a pure literal, meaning you cannot generate it based on you i18n files. Therefore, every time you add a locale, you will have to manually add the locale to the string. The one in the example is set up for a site with only English and Spanish translations

Next, we need to fix 404 pages. By default, if a route cannot be found, Next will render the root not-found.js file, regardless of if the path matches a higher level not-found.tsx file. Since in order to be translated, our not-found.tsx file needs to be in the [lang] folder, we will get the default 404 page, not our custom one. We can fix this by adding a catch-all route that throws the not found error when rendered, like so:

The code in here will simply be:

import { notFound } from 'next/navigation';

// Exists because not-found.tsx in a locale folder does not auto-catch 404 routes. This forces it to do so, and preserves i18n translations as well
export default function notFoundWorkaround() {
    notFound();
}

This will force invalid routes to be greeted by the [lang]/not-found.tsx file. Technically, if the user navigated to a route without a locale, this would not work, but our middleware function forces all users to navigate to pages with locales, so it will always work.

Finally, we need to implement a wrapper for <Link>. Without this, navigation would still work, but Next would be unable to link the pages for client-side navigation, resulting in a full page refresh every time a user tries to navigate between pages. This is just a component, and can be created anywhere you keep components. I've included an externalLink prop, pass that if you are linking to an external site, and therefore do not want to prepend the locale.

import { ComponentProps } from 'react';
import NextLink from 'next/link';
import { useI18nContext } from '../../i18n/i18n-react';

type LinkProps = ComponentProps<typeof NextLink>;

interface Props extends LinkProps {
    externalLink?: boolean;
}

export default function Link({ href, externalLink, ...props }: Props) {
    const { locale } = useI18nContext();

    const updatedHref = externalLink ? href : `/${locale}${href}`;

    return <NextLink href={updatedHref} {...props} />;
}

Now we have reimplemented the old Next.js internationalised routing can actually get started on loading the locale into the client. We can grab our locale using the new server components, however, to pass the information to other components we need a Context Provider, which cannot be rendered in a server component. The simple solution is to fetch the translation in a server component, pass it as a prop to a child client component, and then render the context provider there.

[lang]/layout.tsx

import { ReactNode } from 'react';
import ClientComponent from './layoutClient';
import { Locales } from '../../i18n/i18n-types';
import { loadLocaleAsync } from '../../i18n/i18n-util.async';
import { baseLocale, loadedLocales } from '../../i18n/i18n-util';

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

async function i18nDictionary(locale: Locales) {
    await loadLocaleAsync(locale);
    return {
        locale,
        dictionary: loadedLocales[locale]
    };
}

export default async function GlobalLayout({ children, params }: Props) {
    const locale = params.lang as Locales;

    const i18n = await i18nDictionary(locale ?? baseLocale);
    return (
        <html lang={i18n.locale}>
            <ClientComponent locale={i18n.locale} translation={i18n.dictionary}>
                {children}
            </ClientComponent>
        </html>
    );
}

[lang]/layoutClient.tsx

'use client';

import { ReactNode } from 'react';
import { Locales, Translation } from '../../i18n/i18n-types';
import { loadedLocales } from '../../i18n/i18n-util';
import { loadFormatters } from '../../i18n/i18n-util.sync';
import TypesafeI18n from '../../i18n/i18n-react';

interface Props {
    children: ReactNode;
    locale: Locales;
    translation: Translation;
}

export default function ClientComponent({ children, locale, translation }: Props) {
    loadedLocales[locale] = translation;
    loadFormatters(locale);

    return <TypesafeI18n locale={locale}>{children}</TypesafeI18n>;
}

Now we can use the const { LL } = useI18nContext(); in all our pages (just make sure the compoents you use them in are client components)

All of this has been dynamically loaded, but if you need static generation of all your locales, you can do that by adding a generateStaticParams to your [lang]/layout.tsx like so:

export const generateStaticParams = async () => {
    const staticLangs = locales.map(locale => ({ lang: locale }));

    return staticLangs;
};

The final thing to cover is generating translated titles and other metadata. The app router now uses either a metadata export, for static metadata, or generateMetadata function, for dynamic metadata. We need the generateMetadata since it is dynamically generated. Since this is serverside, we can load the locales as usual and use them directly.

export async function generateMetadata({ params }: MetadataParams): Promise<Metadata> {
    loadLocale(params.lang);
    const dict = loadedLocales[params.lang];

    return {
        title: dict.PAGES.SEO.BLOGS.TITLE,
        description: dict.PAGES.SEO.BLOGS.DESC
    };
}

In hindsight, I think that might break parameterised strings, but we don't use any for our page titles, so it hasn't been a problem. If you need that, you'll probably need to figure it out yourself.

[osdiab]

#697

i haven't tested this in the actual environment where the error occurred, it would be helpful if @avanderbergh you have some time to try dropping this version into your repro and see if it solves the issue. Also @ivanhofer i am unsure if there are any unintended side-effects since i don't actually know how the test coverage is in this project.

[ivanhofer]

Thanks @osdiab. I just have released version 5.25.1

[osdiab]

This was super helpful, though @billytheme / @AngaBlue did you ever figure out how to dynamically pass the proper namespaces to the provider with this approach (assuming you use namespaces in your application)? I have made it work for now by fetching them from the client after page load but that kind of sucks compared to having the namespaces already be there on the initial page load. Pretty stuck trying to figure out how to make that work.

by the way, I was also able to do away with the [...notfound] catch-all route by having the middleware also set the locale on a request header and reading from that from the root-level not-found.tsx file, in case that helps anyone.

[billytheme]

@osdiab We don't have namespaces, so that's not something I've tried to get working. Assuming your namespaces are separated by page, you should be able to load the translations in page.tsx. Not sure where you'd need to call setLocale though.

[osdiab]

Yeah, I haven't been able to make this work. I was able to get it so that the server provides the necessary namespace messages to the client per-page, but having trouble convincing NextJS to show the messages on the initial SSR.

This is what I tried:

In a client provider at the top level:

interface ProvidersProps extends PropsWithChildren {
  locale: Locales;
  rootTranslations: Omit<Translations, Namespaces>;
}
export function Providers({
  children,
  locale,
  rootTranslations,
}: ProvidersProps) {
  // bootstrap the client-side locales from the backend
  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
  loadedLocales[locale] = rootTranslations as Translations;
  loadFormatters(locale);

  return (
        <TypesafeI18n locale={locale}>
            {children}
        </TypesafeI18n>
  );
}

How I use it in the root layout:

        <Providers
          locale={locale}
          // only provide root translations without namespaces at top level
          rootTranslations={omit(loadedLocales[locale], allNamespaces)}
        >
			// ...

Then I provide a server component that's called in each page:

/**
 * Adds the i18n namespaces provided into the client
 */
export const PageI18nNamespaceProvider: FC<
  PropsWithChildren<{ namespaces: Namespaces[] }>
> = ({ namespaces, children }) => {
  const locale = getLocaleFromHeaderOnServer(); // added by middleware.ts
  const namespaceTranslations = pick(loadedLocales[locale], namespaces);
  return (
    <ClientMessageI18nProvider messages={namespaceTranslations}>
      {children}
    </ClientMessageI18nProvider>
  );
};

The referenced i18n provider client component:

/**
 * Adds the i18n namespaces provided into the client
 */
export const ClientMessageI18nProvider: FC<
  PropsWithChildren<{
    messages: Partial<Translations>;
  }>
> = ({ messages, children }) => {
  const { locale, setLocale } = useI18nContext();
  // mirrors the same thing updateDictionary does in the generated client code
  loadedLocales[locale] = { ...loadedLocales[locale], ...messages };
  setLocale(locale);
  return children;
};

Then finally in an actual page:

    <PageI18nNamespaceProvider namespaces={["some-namespace"]}>
      // ...

So this works, and only the namespaces specified per page are sent over. The problem, is that on the first page load, those translations aren't actually flushed to the SSR'd output, even though i see that the ClientMessageI18nProvider is being rendered on the server (by adding a console log and seeing it show up in my terminal output)

Which basically means that we just need to send all strings for our whole app at once if we don't want to have a flash of no content while the page is loading/hydrating, which is OK for now but not OK long-run. If anyone has any idea how to make something like this work, would be forever grateful.

Also btw @ivanhofer —in my opinion it's not ideal that i18nObject just returns an empty string if you try to call a namespace translation that isn't loaded. makes it hard to know if you're just gonna show a blank string to your users, or if there's a flash of missing content like this one. I resolved this by wrapping LL to make it throw if the namespace isn't present. But ideally that wouldn't be the only exported behavior IMO.

[HeinKoZin]

How to change the default language?

I have changed baseLocale to "mm".
It worked. But when I go to http://localhost:3000/ and then it changed into http://localhost:3000/en

[ivanhofer]

One of the worst decisions of Next.JS when implementig i18n is to make this option a static configuration option: https://nextjs.org/docs/pages/building-your-application/routing/internationalization
You also need to set it up in your next.config.js file.