feat: Typesafe Global Formats

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#strict-typing-of-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#strict-typing-of-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#strict-typing-of-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:
 
@@ -486,6 +486,8 @@ Note that `formats` are not automatically inherited by Client Components. If you
 </Tab>
 </Tabs>
 
+To further improve your experience and ensure formatting consistency, you can [configure the typescript integration for global formats](/docs/workflows/typescript#strict-typing-of-global-formats).
+
 Once you have `formats` set up, you can use them in your components via `useFormatter`:
 
 ```tsx

docs/pages/docs/workflows/typescript.mdx

@@ -2,6 +2,8 @@ import Callout from 'components/Callout';
 
 # TypeScript integration
 
+## Strict typing of messages
+
 `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.
 
 ```json filename="messages.json"
@@ -27,7 +29,7 @@ function About() {
 
 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;
@@ -47,3 +49,76 @@ You can freely define the interface, but if you have your messages available loc
 3. The path of your `import` is correct.
 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.
+
+## Strict typing of global formats
+
+`next-intl` provides a way to define [global formats](/docs/usage/configuration#formats) for your application. You can provide the type of your formats similarly to how you [define the type of messages](#strict-typing-of-messages).
+
+First, define your formats and export them from a file:
+
+```ts filename="i18n/request.ts"
+import {getRequestConfig} from 'next-intl/server';
+import type {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 Partial<Formats>;
+
+export default getRequestConfig(async ({locale}) => {
+ // ...
+
+ return {
+ formats,
+ }
+});
+```
+
+Then in your `global.d.ts` at the root of your project, define the `IntlFormats` type:
+
+```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 {}
+}
+```
+
+Now you will have full autocompletion and type safety for your formats:
+
+```tsx filename="CurrentDate.tsx"
+function CurrentDate() {
+ const format = useFormatter();
+
+ // ✅ Valid format
+ format.number(2, "precise");
+
+ // ✅ Valid format
+ format.list(["some", "things"], "enumeration");
+
+ // ✖️ Unknown format string
+ format.dateTime(new Date(), "unknown")
+
+ // ✅ Valid format
+ return <p>{format.dateTime(new Date(), "short")}</p>;
+}
+```

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 type {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 Partial<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,11 @@ 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?:
+ | (keyof IntlFormats['dateTime'] extends string
+ ? keyof IntlFormats['dateTime']
+ : string)
+ | DateTimeFormatOptions
  ) {
  return getFormattedValue(
  formatOrOptions,
@@ -183,7 +187,11 @@ 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?:
+ | (keyof IntlFormats['dateTime'] extends string
+ ? keyof IntlFormats['dateTime']
+ : string)
+ | DateTimeFormatOptions
  ) {
  return getFormattedValue(
  formatOrOptions,
@@ -200,7 +208,11 @@ export default function createFormatter({
 
  function number(
  value: number | bigint,
- formatOrOptions?: string | NumberFormatOptions
+ formatOrOptions?:
+ | (keyof IntlFormats['number'] extends string
+ ? keyof IntlFormats['number']
+ : string)
+ | NumberFormatOptions
  ) {
  return getFormattedValue(
  formatOrOptions,
@@ -284,7 +296,11 @@ export default function createFormatter({
  type FormattableListValue = string | ReactElement;
  function list<Value extends FormattableListValue>(
  value: Iterable<Value>,
- formatOrOptions?: string | Intl.ListFormatOptions
+ formatOrOptions?:
+ | (keyof IntlFormats['list'] extends string
+ ? keyof IntlFormats['list']
+ : string)
+ | Intl.ListFormatOptions
  ): Value extends string ? string : Iterable<ReactElement> {
  const serializedValue: Array<string> = [];
  const richValues = new Map<string, Value>();