feat: Re-introduce locale argument for getRequestConfig to be used for overriding the locale

[amannn]

tldr; — Do you use i18n routing and have you already switched to await requestLocale in getRequestConfig? If yes, you can skip this.

---

Deprecation of locale in favor of await requestLocale

In next-intl 3.22, the locale argument that was passed to getRequestConfig was deprecated in favor of await requestLocale:

// i18n/request.ts

export default function getRequestConfig(async ({
-  locale
+  requestLocale
}) => {
+  const locale = await requestLocale;
  // ...
}));

This change was done in preparation for Next.js 15 where reading from headers became async. If you're using i18n routing, please upgrade to requestLocale now.

Preview: rootParams are coming to Next.js

Now, with rootParams being on the horizon, this API will allow you to read a locale without receiving any param passed to getRequestConfig:

// i18n/request.ts

import {unstable_rootParams as rootParams} from 'next/server';
import {getRequestConfig} from 'next-intl/server';
import {hasLocale} from 'next-intl';
import {routing} from './routing';
 
export default getRequestConfig(async () => {
  const params = await rootParams();
  const locale = hasLocale(routing.locales, params.locale)
    ? params.locale
    : routing.defaultLocale;
 
  // ...
});

Among other simplifications, this allows to remove manual overrides like this that were merely done for enabling static rendering:

- type Props = {
-   params: Promise<{locale: string}>;
- };
 
export async function generateMetadata(
-  {params}: Props
) {
-  const {locale} = await params;
-  const t = await getTranslations({locale, namespace: 'HomePage'});
+  const t = await getTranslations('HomePage');
 
  // ...
}

However, in some rare cases, you might want to render messages from multiple locales on the same page:

// Use messages from the current locale
const t = getTranslations();

// Use messages from 'en', regardless of what the current user locale is
const t = getTranslations({locale: 'en'});

If you're using this pattern, you'll be able to accept the overridden locale in getRequestConfig as follows:

// i18n/request.ts

import {unstable_rootParams as rootParams} from 'next/server';
import {getRequestConfig} from 'next-intl/server';
import {hasLocale} from 'next-intl';
import {routing} from './routing';
 
export default getRequestConfig(async ({locale}) => {
  // Use a locale based on these priorities:
  // 1. An override passed to the function
  // 2. A locale from the `[locale]` segment
  // 3. A default locale
  if (!locale) {
    const params = await rootParams();
    locale = hasLocale(routing.locales, params.locale)
      ? params.locale
      : routing.defaultLocale;
  }
 
  // ...
});

This is quite an edge case, but this use case will remain supported via the re-introduced locale argument. Note that await requestLocale considers a potential locale override, therefore the locale argument will only be relevant once rootParams are a thing.

I hope to have more to share on this in the future!

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
next-intl-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 20, 2024 9:38am
next-intl-example-app-router	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 20, 2024 9:38am
next-intl-example-app-router-without-i18n-routing	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 20, 2024 9:38am