docs: clarify docs w/ should-polyfill

website/docs/polyfills/intl-datetimeformat.md

@@ -24,13 +24,37 @@ This package requires the following capabilities:
 
 ## Usage
 
-### Polyfill
-
-To use the polyfill, just import it to make sure that a fully functional Intl.DateTimeFormat is available in your environment:
+### Simple
 
 ```tsx
 import '@formatjs/intl-datetimeformat/polyfill'
-import '@formatjs/intl-datetimeformat/locale-data/de' // Add locale data for de
+import '@formatjs/intl-datetimeformat/locale-data/en' // locale-data for en
+import '@formatjs/intl-datetimeformat/add-all-tz' // Add ALL tz data
+```
+
+### Dynamic import + capability detection
+
+```tsx
+import {shouldPolyfill} from '@formatjs/intl-datetimeformat/should-polyfill'
+function polyfill(locale: string): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  const polyfills = [
+    import('@formatjs/intl-datetimeformat/polyfill'),
+    import('@formatjs/intl-datetimeformat/add-all-tz'),
+  ]
+  switch (locale) {
+    default:
+      polyfills.push(import('@formatjs/intl-datetimeformat/locale-data/en'))
+      break
+    case 'fr':
+      polyfills.push(import('@formatjs/intl-datetimeformat/locale-data/fr'))
+      break
+  }
+  return Promise.all(polyfills)
+}
 ```
 
 ### Adding IANA Timezone Database
@@ -41,14 +65,14 @@ We provide 2 pre-processed IANA Timezone:
 
 ```tsx
 import '@formatjs/intl-datetimeformat/polyfill'
-import '@formatjs/intl-datetimeformat/add-all-tz.js'
+import '@formatjs/intl-datetimeformat/add-all-tz'
 ```
 
 #### Golden: contains popular set of timezones from IANA database
 
 ```tsx
 import '@formatjs/intl-datetimeformat/polyfill'
-import '@formatjs/intl-datetimeformat/add-golden-tz.js'
+import '@formatjs/intl-datetimeformat/add-golden-tz'
 ```
 
 ### Default Timezone

website/docs/polyfills/intl-displaynames.md

@@ -24,13 +24,31 @@ Everything in <https://github.com/tc39/proposal-intl-displaynames>.
 
 ## Usage
 
-To use this as a polyfill, override `Intl.DisplayNames` as below:
+### Simple
 
-```javascript
+```tsx
 import '@formatjs/intl-displaynames/polyfill'
 import '@formatjs/intl-displaynames/locale-data/en' // locale-data for en
-import '@formatjs/intl-displaynames/locale-data/zh' // locale-data for zh
+```
 
-new Intl.DisplayNames('en').of('zh-Hans') //=> "Simplified Chinese"
-new Intl.DisplayNames('zh', {type: 'currency'}).of('USD') //=> "美元"
+### Dynamic import + capability detection
+
+```tsx
+import {shouldPolyfill} from '@formatjs/intl-displaynames/should-polyfill'
+function polyfill(locale: string): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  const polyfills = [import('@formatjs/intl-displaynames/polyfill')]
+  switch (locale) {
+    default:
+      polyfills.push(import('@formatjs/intl-displaynames/locale-data/en'))
+      break
+    case 'fr':
+      polyfills.push(import('@formatjs/intl-displaynames/locale-data/fr'))
+      break
+  }
+  return Promise.all(polyfills)
+}
 ```

website/docs/polyfills/intl-getcanonicallocales.md

@@ -16,18 +16,23 @@ npm install @formatjs/intl-getcanonicallocales
 
 ## Usage
 
-To use the polyfill, just import it to make sure that a fully functional Intl.Locale is available in your environment:
+### Simple
 
 ```tsx
 import '@formatjs/intl-getcanonicallocales/polyfill'
 ```
 
-If Intl.Locale already exists, the polyfill will not be loaded.
-
-To use this as a ponyfill:
+### Dynamic import + capability detection
 
 ```tsx
-import getCanonicalLocales from '@formatjs/intl-getcanonicallocales'
+import {shouldPolyfill} from '@formatjs/intl-getcanonicallocales/should-polyfill'
+function polyfill(): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  return import('@formatjs/intl-getcanonicallocales/polyfill')
+}
 ```
 
 ## Tests

website/docs/polyfills/intl-listformat.md

@@ -20,26 +20,33 @@ If you're supporting IE11-, this requires [`Intl.getCanonicalLocales`](intl-getc
 
 ## Usage
 
-To use the polyfill, just import it to make sure that a fully functional Intl.ListFormat is available in your environment:
+### Simple
 
 ```tsx
 import '@formatjs/intl-listformat/polyfill'
+import '@formatjs/intl-listformat/locale-data/en' // locale-data for en
 ```
 
-If Intl.ListFormat already exists, the polyfill will not be loaded.
-
-To load locale data, you can include them on demand:
-
-```js
-import '@formatjs/intl-listformat/polyfill'
-import '@formatjs/intl-listformat/locale-data/en' // Add locale data for en
-import '@formatjs/intl-listformat/locale-data/de' // Add locale data for de
-```
-
-If you want to polyfill all locales (e.g for Node):
+### Dynamic import + capability detection
 
 ```tsx
-import '@formatjs/intl-listformat/polyfill-locales'
+import {shouldPolyfill} from '@formatjs/intl-listformat/should-polyfill'
+function polyfill(locale: string): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  const polyfills = [import('@formatjs/intl-listformat/polyfill')]
+  switch (locale) {
+    default:
+      polyfills.push(import('@formatjs/intl-listformat/locale-data/en'))
+      break
+    case 'fr':
+      polyfills.push(import('@formatjs/intl-listformat/locale-data/fr'))
+      break
+  }
+  return Promise.all(polyfills)
+}
 ```
 
 ## Tests

website/docs/polyfills/intl-locale.md

@@ -20,18 +20,23 @@ If you're supporting IE11-, this requires [`Intl.getCanonicalLocales`](intl-getc
 
 ## Usage
 
-To use the polyfill, just import it to make sure that a fully functional Intl.Locale is available in your environment:
+### Simple
 
 ```tsx
 import '@formatjs/intl-locale/polyfill'
 ```
 
-If Intl.Locale already exists, the polyfill will not be loaded.
-
-To use this as a ponyfill:
+### Dynamic import + capability detection
 
 ```tsx
-import IntlLocale from '@formatjs/intl-locale'
+import {shouldPolyfill} from '@formatjs/intl-locale/should-polyfill'
+function polyfill(locale: string): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  return import('@formatjs/intl-locale/polyfill')
+}
 ```
 
 ## Tests

website/docs/polyfills/intl-numberformat.md

@@ -25,39 +25,39 @@ This package requires the following capabilities:
 
 2. If you're supporting IE11-, this requires [`Intl.getCanonicalLocales`](intl-getcanonicallocales.md).
 
-# Features
+## Features
 
 Everything in the ES2020 Internationalization API spec (https://tc39.es/ecma402).
 
-# Usage
+## Usage
 
-To use this as a polyfill, override `Intl.NumberFormat` as below:
+### Simple
 
 ```tsx
 import '@formatjs/intl-numberformat/polyfill'
-import '@formatjs/intl-numberformat/locale-data/zh.js' // locale-data for zh
-import '@formatjs/intl-numberformat/locale-data/en.js' // locale-data for en
-
-new Intl.NumberFormat('zh', {
-  style: 'unit',
-  unit: 'kilometer-per-hour',
-  unitDisplay: 'long',
-}).format(1000) // 每小时1,000公里
-
-new Intl.NumberFormat('en-US', {
-  notation: 'engineering',
-}).format(987654321) // 987.7E6
-
-new Intl.NumberFormat('zh', {
-  style: 'currency',
-  currency: 'EUR',
-  currencySign: 'accounting',
-}).format(-100) // (€100.00)
-
-// `Number.prototype.toLocaleString` is also polyfilled.
-;(987654321).toLocaleString('en-US', {
-  notation: 'engineering',
-}) // 987.7E6
+import '@formatjs/intl-numberformat/locale-data/en' // locale-data for en
+```
+
+### Dynamic import + capability detection
+
+```tsx
+import {shouldPolyfill} from '@formatjs/intl-numberformat/should-polyfill'
+function polyfill(locale: string): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  const polyfills = [import('@formatjs/intl-numberformat/polyfill')]
+  switch (locale) {
+    default:
+      polyfills.push(import('@formatjs/intl-numberformat/locale-data/en'))
+      break
+    case 'fr':
+      polyfills.push(import('@formatjs/intl-numberformat/locale-data/fr'))
+      break
+  }
+  return Promise.all(polyfills)
+}
 ```
 
 ## Supported Units

website/docs/polyfills/intl-pluralrules.md

@@ -20,13 +20,31 @@ If you're supporting IE11-, this requires [`Intl.getCanonicalLocales`](intl-getc
 
 ## Usage
 
+### Simple
+
 ```tsx
 import '@formatjs/intl-pluralrules/polyfill'
 import '@formatjs/intl-pluralrules/locale-data/en' // locale-data for en
 ```
 
-To polyfill w/ ALL locales:
+### Dynamic import + capability detection
 
 ```tsx
-import '@formatjs/intl-pluralrules/polyfill-locales'
+import {shouldPolyfill} from '@formatjs/intl-pluralrules/should-polyfill'
+function polyfill(locale: string): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  const polyfills = [import('@formatjs/intl-pluralrules/polyfill')]
+  switch (locale) {
+    default:
+      polyfills.push(import('@formatjs/intl-pluralrules/locale-data/en'))
+      break
+    case 'fr':
+      polyfills.push(import('@formatjs/intl-pluralrules/locale-data/fr'))
+      break
+  }
+  return Promise.all(polyfills)
+}
 ```

website/docs/polyfills/intl-relativetimeformat.md

@@ -26,17 +26,33 @@ This package requires the following capabilities:
 
 ## Usage
 
-To use the polyfill, just import it to make sure that a fully functional Intl.RelativeTimeFormat is available in your environment:
+### Simple
 
 ```tsx
 import '@formatjs/intl-relativetimeformat/polyfill'
-import '@formatjs/intl-relativetimeformat/locale-data/de' // Add locale data for de
+import '@formatjs/intl-relativetimeformat/locale-data/en' // locale-data for en
 ```
 
-If you want to polyfill all locales (e.g for Node):
+### Dynamic import + capability detection
 
 ```tsx
-import '@formatjs/intl-relativetimeformat/polyfill-locales'
+import {shouldPolyfill} from '@formatjs/intl-relativetimeformat/should-polyfill'
+function polyfill(locale: string): Promise<any> {
+  // This platform already supports Intl.PluralRules
+  if (!shouldPolyfill()) {
+    return Promise.resolve()
+  }
+  const polyfills = [import('@formatjs/intl-relativetimeformat/polyfill')]
+  switch (locale) {
+    default:
+      polyfills.push(import('@formatjs/intl-relativetimeformat/locale-data/en'))
+      break
+    case 'fr':
+      polyfills.push(import('@formatjs/intl-relativetimeformat/locale-data/fr'))
+      break
+  }
+  return Promise.all(polyfills)
+}
 ```
 
 ## Tests