[Docs]: Typescript instructions should include ECMAScript Modules

[ben-cook]

Link to page

https://next-intl-docs.vercel.app/docs/workflows/typescript

Describe the problem

The current typescript instructions cover how to define types using a dynamic import() to fetch the messages, like so:

// global.d.ts

type Messages = typeof import('./messages/en.json');
declare interface IntlMessages extends Messages {}

I think that the docs should also include how to define types using ECMAScript modules (ESM).

The example provided is executed in the global scope because it doesn't contain any import or export keywords (the dynamic import() is a different thing). This means that all declarations within it are visible outside the file.

When the type definitions file includes an import or export keyword, the file is executed within it's own scope. In order to edit the global scope, one must extend global by using declaration merging / global augmentation. It's common to prefer ECMAScript modules over dynamic imports, so I think that this should also be provided as an example:

// global.d.ts

import en from './messages/en.json';

type Messages = typeof en
declare global {
  interface IntlMessages extends Messages {}
}

[amannn]

Interesting, I didn't know. Do you think it would be a good idea to declare global { … } in general, making the shown example valid regardless of if import/export is used or not?