FormatJS

https://formatjs.github.io/docs
Admin
FormatJS is an internationalization library that provides tools for formatting and localizing...
Tokens:200,235
Snippets:1,756
Trust Score:8.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install py_intl package

Source: https://formatjs.github.io/docs/python/

Install the py_intl package using pip. This is the recommended way to get the Python bindings.

```bash
python -m pip install py_intl
```

--------------------------------

### Install @formatjs/intl-listformat via npm

Source: https://formatjs.github.io/docs/polyfills/intl-listformat/

Install the polyfill package using npm. The command is shown in the Installation section.

```bash
npm i @formatjs/intl-listformat
```

--------------------------------

### Install @formatjs/intl-localematcher with npm

Source: https://formatjs.github.io/docs/polyfills/intl-localematcher/

Install the package using npm. This is the primary installation command shown in the documentation.

```bash
npm i @formatjs/intl-localematcher
```

--------------------------------

### Install @formatjs/intl with npm

Source: https://formatjs.github.io/docs/intl/

Install the @formatjs/intl package using npm. This is the standard installation command for the library.

```bash
npm i -S @formatjs/intl
```

--------------------------------

### Install @formatjs/intl-datetimeformat with npm

Source: https://formatjs.github.io/docs/polyfills/intl-datetimeformat/

Install the polyfill package using npm. This is the primary installation command shown in the documentation.

```bash
npm i @formatjs/intl-datetimeformat
```

--------------------------------

### Install with npm

Source: https://formatjs.github.io/docs/polyfills/intl-getcanonicallocales/

Install the polyfill package using npm.

```bash
npm i @formatjs/intl-getcanonicallocales
```

--------------------------------

### Install @formatjs/intl-pluralrules with npm

Source: https://formatjs.github.io/docs/polyfills/intl-pluralrules/

Install the polyfill package using npm.

```bash
npm i @formatjs/intl-pluralrules
```

--------------------------------

### Install @formatjs/intl-locale with npm

Source: https://formatjs.github.io/docs/polyfills/intl-locale/

Install the polyfill package using npm. This is the standard installation command for the package.

```bash
npm i @formatjs/intl-locale
```

--------------------------------

### Example messages/en.json

Source: https://formatjs.github.io/docs/guides/nextjs-app-router/

Example English messages file with home.title and home.description keys.

```json
{
  "home.title": "Welcome to our app",
  "home.description": "The best internationalized app"
}
```

--------------------------------

### Install @formatjs/intl-numberformat with npm

Source: https://formatjs.github.io/docs/polyfills/intl-numberformat/

Install the polyfill package using npm.

```bash
npm i @formatjs/intl-numberformat
```

--------------------------------

### Install @formatjs/intl-relativetimeformat via npm

Source: https://formatjs.github.io/docs/polyfills/intl-relativetimeformat/

Install the polyfill package using npm. The command is shown in the Installation section.

```bash
npm i @formatjs/intl-relativetimeformat
```

--------------------------------

### Install native Rust CLI from Cargo and verify

Source: https://formatjs.github.io/docs/tooling/cli/

Installs the formatjs_cli crate via Cargo and checks the installed version.

```bash
cargo install formatjs_cli
formatjs --version
```

--------------------------------

### Install @formatjs/intl-supportedvaluesof with npm

Source: https://formatjs.github.io/docs/polyfills/intl-supportedvaluesof/

Install the polyfill package using npm. This is the first step before importing the polyfill.

```bash
npm i @formatjs/intl-supportedvaluesof
```

--------------------------------

### Install @formatjs/intl-displaynames with npm

Source: https://formatjs.github.io/docs/polyfills/intl-displaynames/

Install the polyfill package using npm. The command is shown under the npm tab.

```bash
npm i @formatjs/intl-displaynames
```

--------------------------------

### Install Vitest and testing dependencies

Source: https://formatjs.github.io/docs/guides/testing-with-react-intl/

Install Vitest, @testing-library/react, @testing-library/jest-dom, and happy-dom as dev dependencies.

```bash
npm install -D vitest @testing-library/react @testing-library/jest-dom happy-dom
```

--------------------------------

### Install @formatjs/intl-durationformat with npm

Source: https://formatjs.github.io/docs/polyfills/intl-durationformat/

Install the polyfill package using npm. Requires Intl.ListFormat and Intl.NumberFormat or their polyfills.

```bash
npm i @formatjs/intl-durationformat
```

--------------------------------

### Install @swc/plugin-formatjs with npm

Source: https://formatjs.github.io/docs/tooling/swc-plugin/

Install the plugin as a dev dependency. Ensure the version matches your @swc/core version.

```bash
npm i -D @swc/plugin-formatjs
```

--------------------------------

### Installation

Source: https://formatjs.github.io/docs/polyfills/intl-collator/

Install the @formatjs/intl-collator package via npm.

```APIDOC
## Installation

### Command
```bash
npm i @formatjs/intl-collator
```
```

--------------------------------

### Install FormatJS packages

Source: https://formatjs.github.io/docs/guides/migrate-from-i18next/

Commands to install react-intl and @formatjs/cli as dev dependency.

```bash
npm i react-intl
npm i -D @formatjs/cli
```

--------------------------------

### Install py_intl

Source: https://formatjs.github.io/docs/python/

Install the py_intl package using pip.

```APIDOC
## Install py_intl

### Description
Install the py_intl package using pip.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Request Example
```
python -m pip install py_intl
```

### Response
N/A
```

--------------------------------

### Install @formatjs/intl-segmenter with npm

Source: https://formatjs.github.io/docs/polyfills/intl-segmenter/

Install the polyfill package using npm. The command is shown under the 'npm' tab.

```bash
npm i @formatjs/intl-segmenter
```

--------------------------------

### Install @formatjs/svelte-intl with npm

Source: https://formatjs.github.io/docs/svelte-intl/

Install the @formatjs/svelte-intl package using npm. The command is shown under the 'npm' tab.

```bash
npm i -S @formatjs/svelte-intl
```

--------------------------------

### Install react-intl with npm

Source: https://formatjs.github.io/docs/getting-started/installation/

Install the react-intl package as a dependency for your project.

```bash
npm i -S react react-intl
```

--------------------------------

### Install babel-plugin-formatjs with npm

Source: https://formatjs.github.io/docs/getting-started/installation/

Install the babel-plugin-formatjs package as a dev dependency.

```bash
npm i -D babel-plugin-formatjs
```

--------------------------------

### Install FormatJS polyfills for React Native Hermes

Source: https://formatjs.github.io/docs/guides/react-native-hermes/

Install the required FormatJS polyfill packages and react-intl using npm. Only install the polyfills your app requires.

```bash
npm i @formatjs/intl-locale @formatjs/intl-pluralrules @formatjs/intl-numberformat @formatjs/intl-datetimeformat @formatjs/intl-relativetimeformat @formatjs/intl-getcanonicallocales react-intl
```

--------------------------------

### Install vue-intl with npm

Source: https://formatjs.github.io/docs/vue-intl/

Install the vue-intl package using npm. The command is `npm i -S vue-intl`.

```bash
npm i -S vue-intl
```

--------------------------------

### Install ember-intl and @ember-intl/vite

Source: https://formatjs.github.io/docs/ember-intl/

Install the required packages for using ember-intl with Vite-based Ember apps.

```bash
npm i -S ember-intl @ember-intl/vite
```

--------------------------------

### Install @formatjs/intl-collator with npm

Source: https://formatjs.github.io/docs/polyfills/intl-collator/

Install the polyfill package using npm. This is the first step before using the polyfill in your project.

```bash
npm i @formatjs/intl-collator
```

--------------------------------

### Install eslint-plugin-formatjs with npm

Source: https://formatjs.github.io/docs/tooling/linter/

Install the plugin as a dev dependency using npm.

```bash
npm i -D eslint-plugin-formatjs
```

--------------------------------

### Install eslint-plugin-formatjs with npm

Source: https://formatjs.github.io/docs/guides/develop/

Install the formatjs ESLint plugin and ESLint as dev dependencies using npm.

```bash
npm i -D eslint-plugin-formatjs eslint
```

--------------------------------

### Install @formatjs/cli with npm

Source: https://formatjs.github.io/docs/getting-started/message-extraction/

Install the @formatjs/cli package as a dev dependency using npm. This is the first step before configuring the extraction script.

```bash
npm i -D @formatjs/cli
```

--------------------------------

### Custom Formatter Example

Source: https://formatjs.github.io/docs/tooling/cli/

Example of a custom formatter implementation using the FormatFn, CompileFn, and Comparator types.

```APIDOC
## Custom Formatter Example

### Description
Example of a custom formatter implementation using the FormatFn, CompileFn, and Comparator types.

### Code
```javascript
export const format: FormatFn = msgs => msgs

// Sort key reverse alphabetically
export const compareMessages = (el1, el2) => {
  return el1.key < el2.key ? 1 : -1
}

export const compile: CompileFn = msgs => {
  const results: Record<string, string> = {}
  for (const k in msgs) {
    results[k] = msgs[k].defaultMessage!
  }
  return results
}
```
```

--------------------------------

### formatDateTimeRange live editor example

Source: https://formatjs.github.io/docs/react-intl/api/

Live editor example showing how to call formatDateTimeRange with two Date objects.

```tsx
intl.formatDateTimeRange(new Date('2020-1-1'), new Date('2020-1-15'))
```

--------------------------------

### Date/Time Skeleton Example

Source: https://formatjs.github.io/docs/intl-messageformat/

Demonstrates the use of a Date/Time skeleton to customize date formatting. The example formats a date with the 'yyyyMMdd' pattern.

```APIDOC
## [METHOD] new IntlMessageFormat('Today is: {now, date, ::yyyyMMdd}', 'en-GB').format({now: new Date()})

### Description
Formats a message using a Date/Time skeleton to customize date formatting. The skeleton 'yyyyMMdd' formats the date as year, month, and day.

### Method
Constructor and format method

### Endpoint
new IntlMessageFormat(message, locale).format(values)

### Parameters
#### Constructor Parameters
- **message** (string) - Required - The ICU message format string to compile and format.
- **locale** (string) - Required - The locale to use for formatting (e.g., 'en-GB').

#### Format Method Parameters
- **values** (object) - Required - An object containing values for placeholders in the message.
  - **now** (Date) - Required - The date to format.

### Request Example
```tsx
new IntlMessageFormat('Today is: {now, date, ::yyyyMMdd}', 'en-GB').format({
  now: new Date(),
})
```

### Response
#### Success Response
Returns the formatted string with the date formatted according to the skeleton.

#### Response Example
```
Today is: 20231005
```
```

--------------------------------

### formatDisplayName for language code

Source: https://formatjs.github.io/docs/intl/

Example of using formatDisplayName to get the localized display name for a language code.

```ts
intl.formatDisplayName('zh-Hans-SG', {type: 'language'})
```

--------------------------------

### Complete example: extract, compile, and verify

Source: https://formatjs.github.io/docs/tooling/bazel/

A complete example showing how to extract messages, compile them for production, compile translations, and verify translation completeness.

```starlark
load("@rules_formatjs//formatjs:defs.bzl", "formatjs_extract", "formatjs_library", "formatjs_verify")

# Extract messages from source files
formatjs_extract(
    name = "extract_en",
    srcs = glob([
        "src/**/*.ts",
        "src/**/*.tsx",
    ]),
    out = "lang/en.json",
    id_interpolation_pattern = "[sha512:contenthash:base64:6]",
    extract_from_format_message_call = True,
)

# Compile for production
formatjs_library(
    name = "compile_en",
    src = ":extract_en",
    out = "lang/en-compiled.json",
    ast = True,
)

# Compile translations
formatjs_library(
    name = "compile_es",
    src = "translations/es.json",
    out = "lang/es-compiled.json",
    ast = True,
)

# Verify translations are complete
formatjs_verify(
    name = "verify_es",
    reference = ":extract_en",
    translations = ["translations/es.json"],
)
```

--------------------------------

### formatDisplayName for region code

Source: https://formatjs.github.io/docs/intl/

Example of using formatDisplayName to get the localized display name for an ISO-3166 region code.

```ts
// ISO-3166 two letters region code to localized display name
intl.formatDisplayName('UN', {type: 'region'})
```

--------------------------------

### formatDisplayName for currency code

Source: https://formatjs.github.io/docs/intl/

Example of using formatDisplayName to get the localized display name for an ISO-4217 currency code.

```ts
// ISO-4217 currency code to localized display name
intl.formatDisplayName('CNY', {type: 'currency'})
```

--------------------------------

### formatDisplayName for script code

Source: https://formatjs.github.io/docs/intl/

Example of using formatDisplayName to get the localized display name for an ISO-15924 script code.

```ts
// ISO-15924 four letters script code to localized display name
intl.formatDisplayName('Deva', {type: 'script'})
```

--------------------------------

### Resolve locale with resolvedOptions()

Source: https://formatjs.github.io/docs/intl-messageformat/

Call resolvedOptions() on an instance to get the resolved locale. The example shows that 'en-us' is normalized to 'en-US'.

```tsx
new IntlMessageFormat('', 'en-us').resolvedOptions().locale
```

--------------------------------

### Global import

Source: https://formatjs.github.io/docs/polyfills/intl-locale/

Import the polyfill globally to use Intl.Locale. This example shows creating locales, accessing properties, maximizing/minimizing, and getting locale capabilities.

```APIDOC
## Global import

### Description
Import the polyfill globally to use Intl.Locale. This example shows creating locales, accessing properties, maximizing/minimizing, and getting locale capabilities.

### Import
```
import '@formatjs/intl-locale/polyfill.js'
```

### Usage
```js
// Create locale
const locale = new Intl.Locale('en-US')
locale.language // "en"
locale.region // "US"
locale.baseName // "en-US"

// With Unicode extensions
const localeWithExt = new Intl.Locale('en-US-u-ca-buddhist-nu-thai')
localeWithExt.calendar // "buddhist"
localeWithExt.numberingSystem // "thai"

// Maximize/minimize
const minimal = new Intl.Locale('en')
const maximized = minimal.maximize()
maximized.toString() // "en-Latn-US"

const full = new Intl.Locale('en-Latn-US')
const minimized = full.minimize()
minimized.toString() // "en"

// Get locale capabilities
locale.getCalendars() // ["gregory"]
locale.getNumberingSystems() // ["latn"]
locale.getHourCycles() // ["h12"]
locale.getTimeZones() // ["America/Adak", "America/Anchorage", ...]

// Text and week info
locale.getTextInfo() // {direction: "ltr"}
locale.getWeekInfo() // {firstDay: 7, weekend: [6, 7]}
```

### Notes
- The global import does not include TypeScript type declarations. For TypeScript projects, use ES module imports instead.
- If using global import, manually include the corresponding type declaration files (.d.ts) to prevent type errors.
```

--------------------------------

### Polyfill setup for Intl.PluralRules and Intl.RelativeTimeFormat

Source: https://formatjs.github.io/docs/react-intl/upgrade-guide-3.x/

Recommended polyfill imports for browsers lacking native Intl.PluralRules (e.g., IE11, Safari 12-) and Intl.RelativeTimeFormat (e.g., IE11, Edge, Safari 13-). Includes locale data for German (de) as an example.

```javascript
require('@formatjs/intl-pluralrules/polyfill')
require('@formatjs/intl-pluralrules/locale-data/de') // Add locale data for de

require('@formatjs/intl-relativetimeformat/polyfill')
require('@formatjs/intl-relativetimeformat/locale-data/de') // Add locale data for de
```

--------------------------------

### Global Import Usage

Source: https://formatjs.github.io/docs/polyfills/intl-displaynames/

Example usage of the polyfill via global import, demonstrating how to create Intl.DisplayNames instances for various types and options.

```APIDOC
## Global Import

### Description
Import the polyfill globally to use `Intl.DisplayNames` with all supported types and options.

### Import
```js
import '@formatjs/intl-displaynames/polyfill.js'
```

### Usage Examples

#### Language names
```js
const languageNames = new Intl.DisplayNames(['en'], {type: 'language'})
languageNames.of('en') // "English"
languageNames.of('fr') // "French"
languageNames.of('zh') // "Chinese"
```

#### Region names
```js
const regionNames = new Intl.DisplayNames(['en'], {type: 'region'})
regionNames.of('US') // "United States"
regionNames.of('GB') // "United Kingdom"
regionNames.of('JP') // "Japan"
```

#### Currency names
```js
const currencyNames = new Intl.DisplayNames(['en'], {type: 'currency'})
currencyNames.of('USD') // "US Dollar"
currencyNames.of('EUR') // "Euro"
currencyNames.of('JPY') // "Japanese Yen"
```

#### Script names
```js
const scriptNames = new Intl.DisplayNames(['en'], {type: 'script'})
scriptNames.of('Latn') // "Latin"
scriptNames.of('Arab') // "Arabic"
scriptNames.of('Hans') // "Simplified Chinese"
```

#### Calendar names
```js
const calendarNames = new Intl.DisplayNames(['en'], {type: 'calendar'})
calendarNames.of('gregory') // "Gregorian Calendar"
calendarNames.of('islamic') // "Islamic Calendar"
```

#### Date/time field names
```js
const fieldNames = new Intl.DisplayNames(['en'], {type: 'dateTimeField'})
fieldNames.of('hour') // "hour"
fieldNames.of('minute') // "minute"
fieldNames.of('day') // "day"
```

#### Different styles
```js
const shortRegions = new Intl.DisplayNames(['en'], {
  type: 'region',
  style: 'short',
})
shortRegions.of('US') // "US"

const narrowRegions = new Intl.DisplayNames(['en'], {
  type: 'region',
  style: 'narrow',
})
narrowRegions.of('US') // "🇺🇸" (or similar compact form)
```

#### Language display options
```js
const dialectNames = new Intl.DisplayNames(['en'], {
  type: 'language',
  languageDisplay: 'dialect',
})
dialectNames.of('en-CA') // "Canadian English"

const standardNames = new Intl.DisplayNames(['en'], {
  type: 'language',
  languageDisplay: 'standard',
})
standardNames.of('en-CA') // "English"
```

### Note
This global import does not include TypeScript type declarations. For TypeScript projects, use ES module imports instead. If you use the global import, you must manually include the corresponding type declaration files (.d.ts) to prevent type errors.
```

--------------------------------

### Install @formatjs/unplugin with npm

Source: https://formatjs.github.io/docs/tooling/unplugin/

Install the plugin as a dev dependency. Requires unplugin 3.4.0 or newer, which is installed automatically.

```bash
npm i -D @formatjs/unplugin
```

--------------------------------

### IntlProvider onWarn prop example

Source: https://formatjs.github.io/docs/react-intl/upgrade-guide-6.x/

Shows how to use the onWarn prop to handle warning messages. Available from 6.x.

```jsx
<IntlProvider locale="en" onWarn={msg => console.warn(msg)}>
  {children}
</IntlProvider>
```

--------------------------------

### Create vitest.setup.ts for global test utilities

Source: https://formatjs.github.io/docs/guides/testing-with-react-intl/

Create a vitest.setup.ts file to import @testing-library/jest-dom/vitest for custom matchers.

```typescript
import '@testing-library/jest-dom/vitest'
```

--------------------------------

### Using formatjs.configs.recommended in ESLint flat config

Source: https://formatjs.github.io/docs/tooling/linter/

Example of using the recommended shareable config in an ESLint flat config. The comment '// Other configs...' is part of the original example.

```javascript
export default [
  formatjs.configs.recommended,
  // Other configs...
]

```

--------------------------------

### formatTime usage example

Source: https://formatjs.github.io/docs/intl/

Example call to formatTime with no options, using the default options. The comment shows an example output: "4:03 PM".

```tsx
intl.formatTime(Date.now()) // "4:03 PM"
```

--------------------------------

### formatTime usage example

Source: https://formatjs.github.io/docs/react-intl/api/

Example of calling intl.formatTime with the current date.

```tsx
intl.formatTime(Date.now())
```

--------------------------------

### Install react-intl and SWC plugin dependencies

Source: https://formatjs.github.io/docs/guides/nextjs-app-router/

Install react-intl and the SWC plugin and CLI as dev dependencies. Use npm, yarn, or pnpm.

```bash
npm i react-intl
npm i -D @swc/plugin-formatjs @formatjs/cli
```

--------------------------------

### Provider setup in App.svelte

Source: https://formatjs.github.io/docs/svelte-intl/

In the root component (e.g., App.svelte), create an intl instance with createIntl and provide it to the component tree using provideIntl. This uses Svelte's Context API.

```svelte
<script>
  import {createIntl, provideIntl} from '@formatjs/svelte-intl'

  const intl = createIntl({
    locale: 'en',
    defaultLocale: 'en',
    messages: {
      greeting: 'Hello, {name}!',
    },
  })

  provideIntl(intl)
</script>

<slot />
```

--------------------------------

### Download pre-built native CLI binary for macOS (Apple Silicon)

Source: https://formatjs.github.io/docs/tooling/cli/

Downloads, installs, and verifies the pre-built native CLI binary for macOS Apple Silicon.

```bash
# Download and install
curl -L https://github.com/formatjs/formatjs/releases/download/<version>/formatjs_cli-darwin-arm64 -o formatjs
chmod +x formatjs
sudo mv formatjs /usr/local/bin/

# Verify
formatjs --version
```

--------------------------------

### ES Module Import Usage

Source: https://formatjs.github.io/docs/polyfills/intl-displaynames/

Example usage of the polyfill via ES module imports, demonstrating how to create DisplayNames instances.

```APIDOC
## ES Module Import

### Description
Import the `DisplayNames` class from the package to use the polyfill in ES module environments.

### Import
```js
import {DisplayNames} from '@formatjs/intl-displaynames'
```

### Usage Example
```js
// Language names
const languageNames = new DisplayNames(['en'], {type: 'language'})
languageNames.of('en') // "English"
```
```

--------------------------------

### Install @formatjs/ts-transformer with npm

Source: https://formatjs.github.io/docs/getting-started/installation/

Install the @formatjs/ts-transformer package as a dev dependency for TypeScript compilation.

```bash
npm i -D @formatjs/ts-transformer
```

--------------------------------

### Output of minimal application

Source: https://formatjs.github.io/docs/getting-started/installation/

The rendered HTML output of the minimal application example.

```html
<p>
  Aujourd'hui, nous sommes le 23/07/2020
  <br />
  19,00 €
</p>
```

--------------------------------

### Initialize VueIntl plugin with createIntl

Source: https://formatjs.github.io/docs/vue-intl/

Initialize the VueIntl plugin by calling createIntl with an IntlConfig object and passing it to app.use(). This sets up the intl context for the Vue app.

```javascript
const app = createApp(App)
app.use(
  createIntl({
    locale: 'en',
    defaultLocale: 'en',
    messages: {
      foo: 'bar',
    },
  })
)
```

--------------------------------

### Run Intl.DateTimeFormat benchmark with Bazel

Source: https://formatjs.github.io/docs/polyfills/intl-datetimeformat/

Execute this command from the repository root to run the benchmark. It uses fixed UTC inputs and native controls for format, formatRange, and formatRangeToParts, including same-date, cross-date, and collapsed ranges. Each timed task batches 16 calls; construction and locale-data registration are excluded.

```bash
bazel run //packages/intl-datetimeformat:benchmark
```
Tokens:
Raw