feat: New APIs for using next-intl outside of components (#339)

The currently available APIs for using `next-intl` outside of components
like `getTranslations` work well, but are limited to SSR. Using
`useTranslations` in components is technically also limited to SSR at
this point, but I have high hopes that React Server Context will
eventually enable those to work for SSG too.

However, React Server Context will not be available in functions like
`generateMetadata` as this happens outside of the React render as far as
I understand. Therefore we should provide APIs that anticipate this
change. In the unlikely event that React Server Context will work
somehow in these functions, we can still make the passed `locale`
optional, but the transition will be smooth here. Moving to this new API
rather sooner than later is a good idea to avoid churn.






### Upgrade guide

**Before**

```tsx
import {getTranslations, getFormatter, getNow, getTimeZone} from 'next-intl/server';

export async function generateMetadata() {
  const t = await getTranslations('LocaleLayout');
  const format = await getFormatter();
  const now = await getNow();
  const timeZone = await getTimeZone();
}
```

**After**

```tsx
import {getTranslator, getFormatter, getNow, getTimeZone} from 'next-intl/server';

export async function generateMetadata({params}) {
  // Note that this function is now called "getTranslator"
  const t = await getTranslator({
    locale: params.locale,
    namespace: 'LocaleLayout'
  });

  const format = await getFormatter({locale: params.locale});
  const now = await getNow({locale: params.locale});
  const timeZone = await getTimeZone({locale: params.locale});
}
```

examples/example-next-13-advanced/src/app/[locale]/layout.tsx

@@ -1,23 +1,36 @@
 import {Metadata} from 'next';
 import {notFound} from 'next/navigation';
 import {useLocale} from 'next-intl';
-import {getTranslations, getFormatter} from 'next-intl/server';
+import {
+  getFormatter,
+  getNow,
+  getTimeZone,
+  getTranslator
+} from 'next-intl/server';
 import {ReactNode} from 'react';
 
 type Props = {
   children: ReactNode;
   params: {locale: string};
 };
 
-export async function generateMetadata(): Promise<Metadata> {
-  const t = await getTranslations('LocaleLayout');
-  const formatter = await getFormatter();
+export async function generateMetadata({
+  params
+}: Omit<Props, 'children'>): Promise<Metadata> {
+  const t = await getTranslator({
+    namespace: 'LocaleLayout',
+    locale: params.locale
+  });
+  const formatter = await getFormatter({locale: params.locale});
+  const now = await getNow({locale: params.locale});
+  const timeZone = await getTimeZone({locale: params.locale});
 
   return {
     title: t('title'),
     description: t('description'),
     other: {
-      currentYear: formatter.dateTime(new Date(), {year: 'numeric'})
+      currentYear: formatter.dateTime(now, {year: 'numeric'}),
+      timeZone: timeZone || 'N/A'
     }
   };
 }

examples/example-next-13-advanced/src/i18n.tsx

@@ -3,7 +3,7 @@ import {getRequestConfig} from 'next-intl/server';
 
 export default getRequestConfig(async ({locale}) => {
   const now = headers().get('x-now');
-  const timeZone = headers().get('x-time-zone') ?? undefined;
+  const timeZone = headers().get('x-time-zone') ?? 'Europe/Vienna';
   const messages = (await import(`../messages/${locale}.json`)).default;
 
   return {

examples/example-next-13-advanced/tests/main.spec.ts

@@ -538,6 +538,10 @@ it('populates metadata', async ({page}) => {
   );
   await expect(page.locator('meta[name="currentYear"]')).toHaveAttribute(
     'content',
-    '2023'
+    new Date().getFullYear().toString()
+  );
+  await expect(page.locator('meta[name="timeZone"]')).toHaveAttribute(
+    'content',
+    'Europe/Vienna'
   );
 });

examples/example-next-13/src/app/[locale]/layout.tsx

@@ -2,7 +2,7 @@ import clsx from 'clsx';
 import {Inter} from 'next/font/google';
 import {notFound} from 'next/navigation';
 import {useLocale} from 'next-intl';
-import {getTranslations} from 'next-intl/server';
+import {getTranslator} from 'next-intl/server';
 import {ReactNode} from 'react';
 import Navigation from 'components/Navigation';
 
@@ -13,11 +13,14 @@ type Props = {
   params: {locale: string};
 };
 
-export async function generateMetadata() {
-  const t = await getTranslations();
+export async function generateMetadata({params}: Omit<Props, 'children'>) {
+  const t = await getTranslator({
+    locale: params.locale,
+    namespace: 'LocaleLayout'
+  });
 
   return {
-    title: t('LocaleLayout.title')
+    title: t('title')
   };
 }
 

packages/next-intl/src/react-server/useFormatter.tsx

@@ -1,10 +1,12 @@
 import type {useFormatter as useFormatterType} from 'use-intl';
 import getFormatter from '../server/getFormatter';
 import useHook from './useHook';
+import useLocale from './useLocale';
 
 export default function useFormatter(
   // eslint-disable-next-line no-empty-pattern
   ...[]: Parameters<typeof useFormatterType>
 ): ReturnType<typeof useFormatterType> {
-  return useHook('useFormatter', getFormatter());
+  const locale = useLocale();
+  return useHook('useFormatter', getFormatter({locale}));
 }

packages/next-intl/src/react-server/useLocale.tsx

@@ -1,9 +1,9 @@
 import type {useLocale as useLocaleType} from 'use-intl';
-import getLocale from '../server/getLocale';
+import getLocaleFromHeader from '../server/getLocaleFromHeader';
 
 export default function useLocale(
   // eslint-disable-next-line no-empty-pattern
   ...[]: Parameters<typeof useLocaleType>
 ): ReturnType<typeof useLocaleType> {
-  return getLocale();
+  return getLocaleFromHeader();
 }

packages/next-intl/src/react-server/useNow.tsx

@@ -1,6 +1,7 @@
 import type {useNow as useNowType} from 'use-intl';
 import getNow from '../server/getNow';
 import useHook from './useHook';
+import useLocale from './useLocale';
 
 export default function useNow(
   ...[options]: Parameters<typeof useNowType>
@@ -11,5 +12,6 @@ export default function useNow(
     );
   }
 
-  return useHook('useNow', getNow());
+  const locale = useLocale();
+  return useHook('useNow', getNow({locale}));
 }

packages/next-intl/src/react-server/useTimeZone.tsx

@@ -1,10 +1,12 @@
 import type {useTimeZone as useTimeZoneType} from 'use-intl';
 import getTimeZone from '../server/getTimeZone';
 import useHook from './useHook';
+import useLocale from './useLocale';
 
 export default function useTimeZone(
   // eslint-disable-next-line no-empty-pattern
   ...[]: Parameters<typeof useTimeZoneType>
 ): ReturnType<typeof useTimeZoneType> {
-  return useHook('useTimeZone', getTimeZone());
+  const locale = useLocale();
+  return useHook('useTimeZone', getTimeZone({locale}));
 }

packages/next-intl/src/react-server/useTranslations.tsx

@@ -1,11 +1,13 @@
 import type {useTranslations as useTranslationsType} from 'use-intl';
-import getTranslations from '../server/getTranslations';
+import getTranslator from '../server/getTranslator';
 import useHook from './useHook';
+import useLocale from './useLocale';
 
 export default function useTranslations(
   ...[namespace]: Parameters<typeof useTranslationsType>
 ): ReturnType<typeof useTranslationsType> {
-  const result = useHook('useTranslations', getTranslations(namespace));
+  const locale = useLocale();
+  const result = useHook('useTranslations', getTranslator({namespace, locale}));
 
   // The types are slightly off here and indicate that rich text formatting
   // doesn't integrate with React - this is not the case.

packages/next-intl/src/server/getConfig.tsx

@@ -1,7 +1,9 @@
 import {cache} from 'react';
 import getInitializedConfig from 'use-intl/dist/src/react/getInitializedConfig';
 import createRequestConfig from '../server/createRequestConfig';
-import getLocale from './getLocale';
+
+// Make sure `now` is consistent across the request in case none was configured
+const getDefaultNow = cache(() => new Date());
 
 const receiveRuntimeConfig = cache(
   async (locale: string, getConfig?: typeof createRequestConfig) => {
@@ -11,14 +13,12 @@ const receiveRuntimeConfig = cache(
     }
     return {
       ...result,
-      // Make sure `now` is consistent across the request in case none was configured
-      now: result?.now || new Date()
+      now: result?.now || getDefaultNow()
     };
   }
 );
 
-const getConfig = cache(async () => {
-  const locale = getLocale();
+const getConfig = cache(async (locale: string) => {
   const runtimeConfig = await receiveRuntimeConfig(locale, createRequestConfig);
   const opts = {...runtimeConfig, locale};
   return getInitializedConfig(opts);

packages/next-intl/src/server/getFormatter.tsx

@@ -1,10 +1,36 @@
 import {cache} from 'react';
 import {createFormatter} from 'use-intl/dist/src/core';
 import getConfig from './getConfig';
+import getLocaleFromHeader from './getLocaleFromHeader';
 
-const getFormatter = cache(async () => {
-  const config = await getConfig();
-  return createFormatter(config);
+let hasWarned = false;
+
+/**
+ * Returns a formatter based on the given locale.
+ *
+ * The formatter automatically receives the request config, but
+ * you can override it by passing in additional options.
+ */
+const getFormatter = cache(async (opts?: {locale: string}) => {
+  if (!opts?.locale && !hasWarned) {
+    hasWarned = true;
+    console.warn(`
+Calling \`getFormatter\` without a locale is deprecated, please update the call:
+
+// app/[locale]/layout.tsx
+export async function generateMetadata({params}) {
+  const t = await getFormatter({locale: params.locale});
+
+  // ...
+}
+
+Learn more: https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`);
+  }
+
+  const locale = opts?.locale || getLocaleFromHeader();
+  const config = await getConfig(locale);
+  return createFormatter({...config, ...opts});
 });
 
 export default getFormatter;

packages/next-intl/src/server/getIntl.tsx

@@ -1,6 +1,7 @@
 import {cache} from 'react';
 import {createIntl} from 'use-intl/dist/src/core';
 import getConfig from './getConfig';
+import getLocaleFromHeader from './getLocaleFromHeader';
 
 let hasWarned = false;
 
@@ -9,11 +10,16 @@ const getIntl = cache(async () => {
   if (!hasWarned) {
     hasWarned = true;
     console.warn(
-      '`getIntl()` is deprecated and will be removed in the next major version. Please switch to `getFormatter()`.'
+      `
+\`getIntl()\` is deprecated and will be removed in the next major version. Please switch to \`getFormatter()\`.
+
+Learn more: https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`
     );
   }
 
-  const config = await getConfig();
+  const locale = getLocaleFromHeader();
+  const config = await getConfig(locale);
   return createIntl(config);
 });
 

packages/next-intl/src/server/getLocale.tsx

@@ -1,40 +1,21 @@
-import {cookies, headers} from 'next/headers';
-import {cache} from 'react';
-import {COOKIE_LOCALE_NAME, HEADER_LOCALE_NAME} from '../shared/constants';
+import getLocaleFromHeader from './getLocaleFromHeader';
 
-const getLocale = cache(() => {
-  let locale;
+let hasWarned = false;
 
-  try {
-    // A header is only set when we're changing the locale,
-    // otherwise we reuse an existing one from the cookie.
-    const requestHeaders = headers();
-    if (requestHeaders.has(HEADER_LOCALE_NAME)) {
-      locale = requestHeaders.get(HEADER_LOCALE_NAME);
-    } else {
-      locale = cookies().get(COOKIE_LOCALE_NAME)?.value;
-    }
-  } catch (error) {
-    if (
-      error instanceof Error &&
-      (error as any).digest === 'DYNAMIC_SERVER_USAGE'
-    ) {
-      throw new Error(
-        'Usage of next-intl APIs in Server Components is currently only available for dynamic rendering (i.e. no `generateStaticParams`).\n\nSupport for static rendering is under consideration, please refer to the roadmap: https://next-intl-docs.vercel.app/docs/next-13/server-components#roadmap',
-        {cause: error}
-      );
-    } else {
-      throw error;
-    }
-  }
+export default function getLocale() {
+  if (!hasWarned) {
+    console.warn(`
+\`getLocale\` is deprecated. Please use the \`locale\` parameter from Next.js instead:
 
-  if (!locale) {
-    throw new Error(
-      'Unable to find `next-intl` locale, have you configured the middleware?`'
-    );
-  }
+// app/[locale]/layout.tsx
+export async function generateMetadata({params}) {
+  // Use \`params.locale\` here
+}
 
-  return locale;
-});
+Learn more: https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`);
+    hasWarned = true;
+  }
 
-export default getLocale;
+  return getLocaleFromHeader();
+}

packages/next-intl/src/server/getLocaleFromHeader.tsx

@@ -0,0 +1,40 @@
+import {cookies, headers} from 'next/headers';
+import {cache} from 'react';
+import {COOKIE_LOCALE_NAME, HEADER_LOCALE_NAME} from '../shared/constants';
+
+const getLocaleFromHeader = cache(() => {
+  let locale;
+
+  try {
+    // A header is only set when we're changing the locale,
+    // otherwise we reuse an existing one from the cookie.
+    const requestHeaders = headers();
+    if (requestHeaders.has(HEADER_LOCALE_NAME)) {
+      locale = requestHeaders.get(HEADER_LOCALE_NAME);
+    } else {
+      locale = cookies().get(COOKIE_LOCALE_NAME)?.value;
+    }
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      (error as any).digest === 'DYNAMIC_SERVER_USAGE'
+    ) {
+      throw new Error(
+        'Usage of next-intl APIs in Server Components is currently only available for dynamic rendering (i.e. no `generateStaticParams`).\n\nSupport for static rendering is under consideration, please refer to the roadmap: https://next-intl-docs.vercel.app/docs/next-13/server-components#roadmap',
+        {cause: error}
+      );
+    } else {
+      throw error;
+    }
+  }
+
+  if (!locale) {
+    throw new Error(
+      'Unable to find `next-intl` locale, have you configured the middleware?`'
+    );
+  }
+
+  return locale;
+});
+
+export default getLocaleFromHeader;

packages/next-intl/src/server/getNow.tsx

@@ -1,8 +1,28 @@
 import {cache} from 'react';
 import getConfig from './getConfig';
+import getLocaleFromHeader from './getLocaleFromHeader';
 
-const getNow = cache(async () => {
-  const config = await getConfig();
+let hasWarned = false;
+
+const getNow = cache(async (opts?: {locale: string}) => {
+  if (!opts?.locale && !hasWarned) {
+    hasWarned = true;
+    console.warn(`
+Calling \`getNow\` without a locale is deprecated. Please update the call:
+
+// app/[locale]/layout.tsx
+export async function generateMetadata({params}) {
+  const t = await getNow({locale: params.locale});
+
+  // ...
+}
+
+Learn more: https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`);
+  }
+
+  const locale = opts?.locale || getLocaleFromHeader();
+  const config = await getConfig(locale);
   return config.now;
 });