Getting TypeScript/IntelliSense autocomplete to work with next-intl's <NextIntlClientProvider />

[codesfromshad]

According to next-intl's docs, next-intl recommends that you use lodash's pick() function to pass only the messages required by the <NextIntlClientProvider /> instead of the entire message object:

import pick from 'lodash/pick';
import {NextIntlClientProvider, useMessages} from 'next-intl';
import ClientCounter from './ClientCounter';
 
export default function Counter() {
  // Receive messages provided in `i18n.ts` …
  const messages = useMessages();
 
  return (
    <NextIntlClientProvider
      messages={
        // … and provide the relevant messages
        pick(messages, 'ClientCounter')
      }
    >
      <ClientCounter />
    </NextIntlClientProvider>
  );
}

However, the above approach doesn't work with TypeScript and Intellisense autocomplete. To have it working, I came up with the following solution.

Step 1: Configure Global Types

First, define your message types globally as recommended by the next-intl documentation. This ensures type safety for your message keys. Add the following to your global.d.ts file:

// Use type safe message keys with `next-intl`
type Messages = typeof import("~/translations/en-US.json");
declare interface IntlMessages extends Messages {}

Also, include global.d.ts in your tsconfig.json to ensure TypeScript recognizes these global types:

{
  "compilerOptions": {
    // ... other options
  },
  "include": [
    "next-env.d.ts", 
    "global.d.ts",
    // ... other files and patterns
  ],
  "exclude": ["node_modules"]
}

Step 2: Define MessageKeys Type

Create a MessageKeys.ts file in your types directory (e.g., /src/types). This file will define the MessageKeys type, which helps in leveraging TypeScript's type checking:

import type { NamespaceKeys, NestedKeyOf } from "next-intl";

// Define `MessageKeys` for the `useMessages()` hook of `next-intl`
type MessageKeys = NamespaceKeys<IntlMessages, NestedKeyOf<IntlMessages>>;

export type { MessageKeys };

Step 3: Use <NextIntlClientProvider /> with TypeScript

When using the <NextIntlClientProvider />, ensure that the messages are correctly typed. This facilitates autocomplete and type checking:

// locale-selector-container.tsx

import pick from "lodash/pick";
import { NextIntlClientProvider, useMessages } from "next-intl";

import type { MessageKeys } from "~/types/MessageKeys";

import { default as LocaleSelector, type LocaleSwitcherProps } from "./locale-selector";

export default function LocaleSelectorContainer(props: LocaleSwitcherProps) {
  // Type cast `useMessages()` for TypeScript support
  const messages = useMessages() as Record<MessageKeys, string>;

  return (
    <NextIntlClientProvider
      messages={pick(
        messages, 
        ["common.internationalization.localeSelector"] as MessageKeys[] // Use as an `array` of `MessageKeys`
      )}
    >
      <LocaleSelector {...props} />
    </NextIntlClientProvider>
  );
}

// locale-selector.tsx

"use client";

// ... other imports
import { type Locale, locales } from "i18n.config";
import { useLocale, useTranslations } from "next-intl";
import * as React from "react";

// ... local component imports

// ... some locally scoped helper functions

export default function LocaleSelector({
  // ... some props
}: LocaleSwitcherProps) {
  // ... some other `hooks`/`const` called/defined
  const t = useTranslations();
  // ... some more `hooks`/`const` called/defined

  // ... some side effects

  return (
    <Select defaultValue={currentLocale} onValueChange={onSelectChange}>
      <SelectTrigger
        className={// ... some classes}
        aria-label={t("common.internationalization.localeSelector.ariaLabel")}
      >
        <SelectValue
          placeholder={t("common.internationalization.localeSelector.placeholder")}
        >
          // ... other components; nested
        </SelectValue>
      </SelectTrigger>
      // ... some other components for the `<Select />` component
    </Select>
  );
}

// index.ts

export { default as LocaleSelector } from "./locale-selector-container";

Directory structure:

.
├── ...
├── public
├── src/
│   ├── app
│   ├── ...
│   ├── components/
│   │   ├── ...
│   │   ├── features
│   │   │   └── internationalization/
│   │   │       └── locale-selector/
│   │   │           ├── index.ts
│   │   │           ├── locale-selector.tsx
│   │   │           └── locale-selector-container.tsx
│   │   └── ...
│   │
│   └── ...
└── ...

End result: