feat: Type-safe global formats (#1346)

---------

Co-authored-by: Jan Amann <jan@amann.work>

docs/pages/docs/design-principles.mdx

@@ -54,7 +54,7 @@ For text formatting, `next-intl` is based on [International Components for Unico
 
 By being based on standards, `next-intl` ensures that your internationalization code is future-proof and feels familiar to developers who have existing experience with internationalization. Additionally, relying on standards ensures that `next-intl` integrates well with translation management systems like <PartnerContentLink href="https://crowdin.com/">Crowdin</PartnerContentLink>.
 
-`next-intl` uses a [nested style](/docs/usage/messages#structuring-messages) to provide structure to messages, allowing to express hierarchies of messages without redundancy. By supporting only a single style, we can offer advanced features that rely on these assumptions like [type-safety for messages](/docs/workflows/typescript). If you're coming from a different style, you can consider migrating to the nested style (see "Can I use a different style for structuring my messages?" in [the structuring messages docs](/docs/usage/messages#structuring-messages)).
+`next-intl` uses a [nested style](/docs/usage/messages#structuring-messages) to provide structure to messages, allowing to express hierarchies of messages without redundancy. By supporting only a single style, we can offer advanced features that rely on these assumptions like [type-safety for messages](/docs/workflows/typescript#messages). If you're coming from a different style, you can consider migrating to the nested style (see "Can I use a different style for structuring my messages?" in [the structuring messages docs](/docs/usage/messages#structuring-messages)).
 
 As standards can change, `next-intl` is expected to keep up with the latest developments in the ECMAScript standard (e.g. [`Temporal`](https://tc39.es/proposal-temporal/docs/) and [`Intl.MessageFormat`](https://github.com/tc39/proposal-intl-messageformat)).
 
@@ -70,7 +70,7 @@ Typical apps require some of the following integrations:
 
 These are typically used to manage translations and to [collaborate with translators](/docs/workflows/localization-management). Services like <PartnerContentLink href="https://crowdin.com/">Crowdin</PartnerContentLink> provide a wide range of features, allowing translators to work in a web-based interface on translations, while providing different mechanisms to sync translations with your app.
 
-`next-intl` integrates well with these services as it uses ICU message syntax for defining text labels, which is a widely supported standard. The recommended way to store messages is in JSON files that are structured by locale since this is a popular format that can be imported into a TMS. While it's recommended to have at least the messages for the default locale available locally (e.g. for [type-safe messages](/docs/workflows/typescript)), you can also load messages dynamically, e.g. from a CDN that your TMS provides.
+`next-intl` integrates well with these services as it uses ICU message syntax for defining text labels, which is a widely supported standard. The recommended way to store messages is in JSON files that are structured by locale since this is a popular format that can be imported into a TMS. While it's recommended to have at least the messages for the default locale available locally (e.g. for [type-safe messages](/docs/workflows/typescript#messages)), you can also load messages dynamically, e.g. from a CDN that your TMS provides.
 
 **Content Management Systems (CMS)**
 

docs/pages/docs/usage/configuration.mdx

@@ -199,7 +199,7 @@ The most crucial aspect of internationalization is providing labels based on the
 ...
 ```
 
-Colocating your messages with app code is beneficial because it allows developers to make changes quickly and additionally, you can use the shape of your local messages for [type checking](/docs/workflows/typescript). Translators can collaborate on messages by using CI tools, such as <PartnerContentLink name="localization-management-intro" href="https://store.crowdin.com/github">Crowdin's GitHub integration</PartnerContentLink>, which allows changes to be synchronized directly into your code repository.
+Colocating your messages with app code is beneficial because it allows developers to make changes quickly and additionally, you can use the shape of your local messages for [type checking](/docs/workflows/typescript#messages). Translators can collaborate on messages by using CI tools, such as <PartnerContentLink name="localization-management-intro" href="https://store.crowdin.com/github">Crowdin's GitHub integration</PartnerContentLink>, which allows changes to be synchronized directly into your code repository.
 
 That being said, `next-intl` is agnostic to how you store messages and allows you to freely define an async function that fetches them while your app renders:
 
@@ -500,6 +500,12 @@ function Component() {
 }
 ```
 
+<Callout>
+  You can optionally [specify a global type for
+  `formats`](/docs/workflows/typescript#formats) to get autocompletion and type
+  safety.
+</Callout>
+
 Global formats for numbers, dates and times can be referenced in messages too:
 
 ```json filename="en.json"

docs/pages/docs/workflows/typescript.mdx

@@ -2,7 +2,13 @@ import Callout from 'components/Callout';
 
 # TypeScript integration
 
-`next-intl` integrates with TypeScript out-of-the box without additional setup. You can however provide the shape of your messages to get autocompletion and type safety for your namespaces and message keys.
+`next-intl` integrates seamlessly with TypeScript right out of the box, requiring no additional setup.
+
+However, you can optionally provide supplemental type definitions for your messages and formats to enable autocompletion and improve type safety.
+
+## Messages
+
+Messages can be strictly typed to ensure you're using valid keys.
 
 ```json filename="messages.json"
 {
@@ -12,7 +18,7 @@ import Callout from 'components/Callout';
 }
 ```
 
-```tsx filename="About.tsx"
+```tsx
 function About() {
   // ✅ Valid namespace
   const t = useTranslations('About');
@@ -21,13 +27,13 @@ function About() {
   t('description');
 
   // ✅ Valid message key
-  return <p>{t('title')}</p>;
+  t('title');
 }
 ```
 
 To enable this validation, add a global type definition file in your project root (e.g. `global.d.ts`):
 
-```jsx filename="global.d.ts"
+```ts filename="global.d.ts"
 import en from './messages/en.json';
 
 type Messages = typeof en;
@@ -40,10 +46,83 @@ declare global {
 
 You can freely define the interface, but if you have your messages available locally, it can be helpful to automatically create the interface based on the messages from your default locale by importing it.
 
-**If you're encountering problems, please double check that:**
+## Formats
+
+[Global formats](/docs/usage/configuration#formats) that are referenced in calls like `format.dateTime` can be strictly typed to ensure you're using valid format names across your app.
+
+```tsx
+function Component() {
+  const format = useFormatter();
+
+  // ✅ Valid format
+  format.number(2, 'precise');
+
+  // ✅ Valid format
+  format.list(['HTML', 'CSS', 'JavaScript'], 'enumeration');
+
+  // ✖️ Unknown format string
+  format.dateTime(new Date(), 'unknown');
+
+  // ✅ Valid format
+  format.dateTime(new Date(), 'short');
+}
+```
+
+To enable this validation, export the formats that you're using in your request configuration:
+
+```ts filename="i18n/request.ts"
+import {getRequestConfig} from 'next-intl/server';
+import {Formats} from 'next-intl';
+
+export const formats = {
+  dateTime: {
+    short: {
+      day: 'numeric',
+      month: 'short',
+      year: 'numeric'
+    }
+  },
+  number: {
+    precise: {
+      maximumFractionDigits: 5
+    }
+  },
+  list: {
+    enumeration: {
+      style: 'long',
+      type: 'conjunction'
+    }
+  }
+} satisfies Formats;
+
+export default getRequestConfig(async ({locale}) => {
+  // ...
+
+  return {
+    formats
+  }
+});
+```
+
+Now, a global type definition file in the root of your project can pick up the shape of your formats and use them for declaring the `IntlFormats` interface:
+
+```ts filename="global.d.ts"
+import {formats} from './src/i18n/request';
+
+type Formats = typeof formats;
+
+declare global {
+  // Use type safe formats with `next-intl`
+  interface IntlFormats extends Formats {}
+}
+```
+
+## Troubleshooting
+
+If you're encountering problems, please double check that:
 
-1. Your interface is called `IntlMessages`.
+1. Your interface uses the correct name.
 2. You're using TypeScript version 4 or later.
-3. The path of your `import` is correct.
+3. You're using correct paths for all modules you're importing into your global declaration file.
 4. Your type declaration file is included in `tsconfig.json`.
 5. Your editor has loaded the most recent type declarations. When in doubt, you can restart.

examples/example-app-router-playground/global.d.ts

@@ -1,8 +1,13 @@
 import en from './messages/en.json';
+import {formats} from './src/i18n/request';
 
 type Messages = typeof en;
+type Formats = typeof formats;
 
 declare global {
   // Use type safe message keys with `next-intl`
   interface IntlMessages extends Messages {}
+
+  // Use type safe formats with `next-intl`
+  interface IntlFormats extends Formats {}
 }

examples/example-app-router-playground/src/app/[locale]/client/ClientContent.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import {useNow, useTimeZone, useLocale} from 'next-intl';
+import {useNow, useTimeZone, useLocale, useFormatter} from 'next-intl';
 import {Link, usePathname} from '@/i18n/routing';
 
 export default function ClientContent() {
@@ -18,3 +18,23 @@ export default function ClientContent() {
     </>
   );
 }
+
+export function TypeTest() {
+  const format = useFormatter();
+
+  format.dateTime(new Date(), 'medium');
+  // @ts-expect-error
+  format.dateTime(new Date(), 'unknown');
+
+  format.dateTimeRange(new Date(), new Date(), 'medium');
+  // @ts-expect-error
+  format.dateTimeRange(new Date(), new Date(), 'unknown');
+
+  format.number(420, 'precise');
+  // @ts-expect-error
+  format.number(420, 'unknown');
+
+  format.list(['this', 'is', 'a', 'list'], 'enumeration');
+  // @ts-expect-error
+  format.list(['this', 'is', 'a', 'list'], 'unknown');
+}

examples/example-app-router-playground/src/components/AsyncComponent.tsx

@@ -1,4 +1,4 @@
-import {getTranslations} from 'next-intl/server';
+import {getTranslations, getFormatter} from 'next-intl/server';
 
 export default async function AsyncComponent() {
   const t = await getTranslations('AsyncComponent');
@@ -15,9 +15,27 @@ export default async function AsyncComponent() {
 export async function TypeTest() {
   const t = await getTranslations('AsyncComponent');
 
+  const format = await getFormatter();
+
   // @ts-expect-error
   await getTranslations('Unknown');
 
   // @ts-expect-error
   t('unknown');
+
+  format.dateTime(new Date(), 'medium');
+  // @ts-expect-error
+  format.dateTime(new Date(), 'unknown');
+
+  format.dateTimeRange(new Date(), new Date(), 'medium');
+  // @ts-expect-error
+  format.dateTimeRange(new Date(), new Date(), 'unknown');
+
+  format.number(420, 'precise');
+  // @ts-expect-error
+  format.number(420, 'unknown');
+
+  format.list(['this', 'is', 'a', 'list'], 'enumeration');
+  // @ts-expect-error
+  format.list(['this', 'is', 'a', 'list'], 'unknown');
 }

examples/example-app-router-playground/src/i18n/request.tsx

@@ -1,9 +1,31 @@
 import {headers} from 'next/headers';
 import {notFound} from 'next/navigation';
+import {Formats} from 'next-intl';
 import {getRequestConfig} from 'next-intl/server';
 import defaultMessages from '../../messages/en.json';
 import {routing} from './routing';
 
+export const formats = {
+  dateTime: {
+    medium: {
+      dateStyle: 'medium',
+      timeStyle: 'short',
+      hour12: false
+    }
+  },
+  number: {
+    precise: {
+      maximumFractionDigits: 5
+    }
+  },
+  list: {
+    enumeration: {
+      style: 'long',
+      type: 'conjunction'
+    }
+  }
+} satisfies Formats;
+
 export default getRequestConfig(async ({locale}) => {
   // Validate that the incoming `locale` parameter is valid
   if (!routing.locales.includes(locale as any)) notFound();
@@ -22,15 +44,7 @@ export default getRequestConfig(async ({locale}) => {
       globalString: 'Global string',
       highlight: (chunks) => <strong>{chunks}</strong>
     },
-    formats: {
-      dateTime: {
-        medium: {
-          dateStyle: 'medium',
-          timeStyle: 'short',
-          hour12: false
-        }
-      }
-    },
+    formats,
     onError(error) {
       if (
         error.message ===

packages/use-intl/src/core/createFormatter.tsx

@@ -163,7 +163,9 @@ export default function createFormatter({
     value: Date | number,
     /** If a time zone is supplied, the `value` is converted to that time zone.
      * Otherwise the user time zone will be used. */
-    formatOrOptions?: string | DateTimeFormatOptions
+    formatOrOptions?:
+      | Extract<keyof IntlFormats['dateTime'], string>
+      | DateTimeFormatOptions
   ) {
     return getFormattedValue(
       formatOrOptions,
@@ -183,7 +185,9 @@ export default function createFormatter({
     end: Date | number,
     /** If a time zone is supplied, the values are converted to that time zone.
      * Otherwise the user time zone will be used. */
-    formatOrOptions?: string | DateTimeFormatOptions
+    formatOrOptions?:
+      | Extract<keyof IntlFormats['dateTime'], string>
+      | DateTimeFormatOptions
   ) {
     return getFormattedValue(
       formatOrOptions,
@@ -200,7 +204,9 @@ export default function createFormatter({
 
   function number(
     value: number | bigint,
-    formatOrOptions?: string | NumberFormatOptions
+    formatOrOptions?:
+      | Extract<keyof IntlFormats['number'], string>
+      | NumberFormatOptions
   ) {
     return getFormattedValue(
       formatOrOptions,
@@ -284,7 +290,9 @@ export default function createFormatter({
   type FormattableListValue = string | ReactElement;
   function list<Value extends FormattableListValue>(
     value: Iterable<Value>,
-    formatOrOptions?: string | Intl.ListFormatOptions
+    formatOrOptions?:
+      | Extract<keyof IntlFormats['list'], string>
+      | Intl.ListFormatOptions
   ): Value extends string ? string : Iterable<ReactElement> {
     const serializedValue: Array<string> = [];
     const richValues = new Map<string, Value>();