refactor(RSC): Refactor async APIs to make the locale optional

[amannn]

Change (tldr)

Before:

import {getTranslator} from 'next-intl/server';

const t = await getTranslator(locale, namespace?);

After:

import {getTranslations} from 'next-intl/server';

// Simplified usage in async components
const t = await getTranslations(namespace?);

// Optionally integrate with static rendering in the 
// Metadata API by passing an explicit locale.
const t = await getTranslations({locale, namespace}); 

Apart from getTranslations, also the other async APIs have been streamlined to accept an optional object with the locale:

• getFormatter({locale})
• getMessages({locale})
• getNow({locale})
• getTimeZone({locale})

In case you use dynamic rendering, or you're using unstable_setRequestLocale, you can omit the object argument with the locale.

See this commit for an example of how to upgrade: 1aac2e7

Background

I've always been quite vocal about why I think the hooks-based useTranslations API is favorable over an async alternative for components, mainly due to the resulting components qualifying as shared components and generally to reduce the APIs you have to learn.

A popular user request over the RSC beta period has always been to use translations in async components. We've recently aligned (await getTranslator()).rich with useTranslations().rich and therefore made getTranslator usable in React components.

I gave the topic another critical look and based on recent developments on the Next.js side like PPR, it seems like async components will likely appear also in nested, deeper places in your server component tree (see also How Next.js is delivering React’s vision for the future by Sam Selikoff). Having multiple async components in your server tree, along with suspense boundaries, can be beneficial, therefore next-intl should make it easy to work with this pattern.

Based on this, I think there's a need for first-class support for using translations in async components.

To achieve this, this PR includes the following changes:

1. Rename getTranslator to getTranslations for API similarity with useTranslations (and to make this change non-breaking for users of previous release candidate versions)
2. Switch getTranslator to an API where the locale is optional, making the consumption in components easier.
3. Allow to pass an explicit locale to getTranslations via an object, for easier static rendering support in the Metadata API.
4. Update the docs to include documentation both for async as well as non-async components (see the current draft).

In case Next.js adds support for reading the locale at arbitrary places in the React tree (see facebook/react#27424 (comment)), the new API furthermore provides an opportunity to deprecate the object form altogether—this wouldn't be possible with the previous API due to ambiguity of the string arguments locale and namespace.

[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	Nov 6, 2023 9:02pm
next-intl-example-next-13	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 6, 2023 9:02pm