refactor: Switch to a string argument for the locale that is passed to the non-component APIs

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

@@ -15,15 +15,12 @@ type Props = {
 };
 
 export async function generateMetadata({
-  params
+  params: {locale}
 }: 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});
+  const t = await getTranslator(locale, 'LocaleLayout');
+  const formatter = await getFormatter(locale);
+  const now = await getNow(locale);
+  const timeZone = await getTimeZone(locale);
 
   return {
     title: t('title'),

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

@@ -13,11 +13,10 @@ type Props = {
   params: {locale: string};
 };
 
-export async function generateMetadata({params}: Omit<Props, 'children'>) {
-  const t = await getTranslator({
-    locale: params.locale,
-    namespace: 'LocaleLayout'
-  });
+export async function generateMetadata({
+  params: {locale}
+}: Omit<Props, 'children'>) {
+  const t = await getTranslator(locale, 'LocaleLayout');
 
   return {
     title: t('title')

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

@@ -8,5 +8,5 @@ export default function useFormatter(
   ...[]: Parameters<typeof useFormatterType>
 ): ReturnType<typeof useFormatterType> {
   const locale = useLocale();
-  return useHook('useFormatter', getFormatter({locale}));
+  return useHook('useFormatter', getFormatter(locale));
 }

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

@@ -13,5 +13,5 @@ export default function useNow(
   }
 
   const locale = useLocale();
-  return useHook('useNow', getNow({locale}));
+  return useHook('useNow', getNow(locale));
 }

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

@@ -8,5 +8,5 @@ export default function useTimeZone(
   ...[]: Parameters<typeof useTimeZoneType>
 ): ReturnType<typeof useTimeZoneType> {
   const locale = useLocale();
-  return useHook('useTimeZone', getTimeZone({locale}));
+  return useHook('useTimeZone', getTimeZone(locale));
 }

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

@@ -7,7 +7,7 @@ export default function useTranslations(
   ...[namespace]: Parameters<typeof useTranslationsType>
 ): ReturnType<typeof useTranslationsType> {
   const locale = useLocale();
-  const result = useHook('useTranslations', getTranslator({namespace, locale}));
+  const result = useHook('useTranslations', getTranslator(locale, namespace));
 
   // 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/getFormatter.tsx

@@ -3,18 +3,41 @@ import {createFormatter} from 'use-intl/dist/src/core';
 import getConfig from './getConfig';
 import getLocaleFromHeader from './getLocaleFromHeader';
 
-let hasWarned = false;
+let hasWarnedForMissingLocale = false;
+let hasWarnedForObjectArgument = 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(`
+const getFormatter = cache(async (locale?: string | {locale: string}) => {
+  if (typeof locale === 'object') {
+    locale = locale.locale;
+    if (!hasWarnedForObjectArgument) {
+      hasWarnedForObjectArgument = true;
+      console.warn(
+        `
+DEPRECATION WARNING: Calling \`getFormatter\` with an object argument is deprecated, please update your call site accordingly.
+
+// Previously
+getFormatter({locale: 'en'});
+
+// Now
+getFormatter('en');
+
+See also https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`
+      );
+    }
+  }
+
+  if (!locale) {
+    locale = getLocaleFromHeader();
+    if (!hasWarnedForMissingLocale) {
+      hasWarnedForMissingLocale = true;
+      console.warn(`
 Calling \`getFormatter\` without a locale is deprecated, please update the call:
 
 // app/[locale]/layout.tsx
@@ -26,11 +49,11 @@ export async function generateMetadata({params}) {
 
 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});
+  return createFormatter(config);
 });
 
 export default getFormatter;

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

@@ -2,13 +2,36 @@ import {cache} from 'react';
 import getConfig from './getConfig';
 import getLocaleFromHeader from './getLocaleFromHeader';
 
-let hasWarned = false;
+let hasWarnedForMissingLocale = false;
+let hasWarnedForObjectArgument = 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:
+const getNow = cache(async (locale?: string | {locale: string}) => {
+  if (typeof locale === 'object') {
+    locale = locale.locale;
+    if (!hasWarnedForObjectArgument) {
+      hasWarnedForObjectArgument = true;
+      console.warn(
+        `
+DEPRECATION WARNING: Calling \`getNow\` with an object argument is deprecated, please update your call site accordingly.
+
+// Previously
+getNow({locale: 'en'});
+
+// Now
+getNow('en');
+
+See also https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`
+      );
+    }
+  }
+
+  if (!locale) {
+    locale = getLocaleFromHeader();
+    if (!hasWarnedForMissingLocale) {
+      hasWarnedForMissingLocale = true;
+      console.warn(`
+Calling \`getNow\` without a locale is deprecated, please update the call:
 
 // app/[locale]/layout.tsx
 export async function generateMetadata({params}) {
@@ -19,9 +42,9 @@ export async function generateMetadata({params}) {
 
 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;
 });

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

@@ -2,13 +2,36 @@ import {cache} from 'react';
 import getConfig from './getConfig';
 import getLocaleFromHeader from './getLocaleFromHeader';
 
-let hasWarned = false;
+let hasWarnedForMissingLocale = false;
+let hasWarnedForObjectArgument = false;
 
-const getTimeZone = cache(async (opts?: {locale: string}) => {
-  if (!opts?.locale && !hasWarned) {
-    hasWarned = true;
-    console.warn(`
-Calling \`getTimeZone\` without a locale is deprecated. Please update the call:
+const getTimeZone = cache(async (locale?: string | {locale: string}) => {
+  if (typeof locale === 'object') {
+    locale = locale.locale;
+    if (!hasWarnedForObjectArgument) {
+      hasWarnedForObjectArgument = true;
+      console.warn(
+        `
+DEPRECATION WARNING: Calling \`getTimeZone\` with an object argument is deprecated, please update your call site accordingly.
+
+// Previously
+getTimeZone({locale: 'en'});
+
+// Now
+getTimeZone('en');
+
+See also https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`
+      );
+    }
+  }
+
+  if (!locale) {
+    locale = getLocaleFromHeader();
+    if (!hasWarnedForMissingLocale) {
+      hasWarnedForMissingLocale = true;
+      console.warn(`
+Calling \`getTimeZone\` without a locale is deprecated, please update the call:
 
 // app/[locale]/layout.tsx
 export async function generateMetadata({params}) {
@@ -19,9 +42,9 @@ export async function generateMetadata({params}) {
 
 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.timeZone;
 });

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

@@ -13,15 +13,22 @@ import NestedKeyOf from 'use-intl/dist/src/core/utils/NestedKeyOf';
 import NestedValueOf from 'use-intl/dist/src/core/utils/NestedValueOf';
 import getConfig from './getConfig';
 
+let hasWarned = false;
+
 async function getTranslatorImpl<
   NestedKey extends NamespaceKeys<
     IntlMessages,
     NestedKeyOf<IntlMessages>
   > = never
->(opts: {
-  namespace?: NestedKey;
-  locale: string;
-}): // Explicitly defining the return type is necessary as TypeScript would get it wrong
+>(
+  locale:
+    | string
+    | {
+        namespace?: NestedKey;
+        locale: string;
+      },
+  namespace?: NestedKey
+): // Explicitly defining the return type is necessary as TypeScript would get it wrong
 Promise<{
   // Default invocation
   <
@@ -81,11 +88,33 @@ Promise<{
     key: TargetKey
   ): any;
 }> {
-  const config = await getConfig(opts.locale);
+  if (typeof locale === 'object') {
+    const opts = locale;
+    namespace = opts.namespace;
+    locale = opts.locale;
+    if (!hasWarned) {
+      console.warn(
+        `
+DEPRECATION WARNING: Calling \`getTranslator\` with an object argument is deprecated, please update your call site accordingly.
+
+// Previously
+getTranslator({locale: 'en', namespace: 'About'});
+
+// Now
+getTranslator('en', 'About');
+
+See also https://next-intl-docs.vercel.app/docs/next-13/server-components#using-internationalization-outside-of-components
+`
+      );
+      hasWarned = true;
+    }
+  }
+
+  const config = await getConfig(locale);
 
   const messagesOrError = getMessagesOrError({
     messages: config.messages as any,
-    namespace: opts.namespace,
+    namespace,
     onError: config.onError
   });
 
@@ -95,7 +124,7 @@ Promise<{
   // @ts-ignore
   return createBaseTranslator({
     ...config,
-    ...opts,
+    namespace,
     messagesOrError
   });
 }