Angular Intl

This project was generated with Angular CLI version 14.1.0. The project provides the following set of standalone Angular pipes:

• intl-date
• intl-timeago
• intl-list
• intl-number
• intl-plural
• intl-sort

What is Intl?

The Intl object is the namespace for the ECMAScript Internationalization API, which provides language sensitive string comparison, number formatting, and date and time formatting. For more information, take a look at the mdm web docs.

Changelog

The latest changes are available within this repository in the project's CHANGELOG file.

intl-date

Format a date according to locale and formatting options.

Description

Just like the Angular DatePipe, IntlDatePipe is executed only when it detects a pure change to the input value. A pure change is either a change to a primitive input value (such as String, Number, Boolean, or Symbol), or a changed object reference (such as Date, Array, Function, or Object).

Note that mutating a Date object does not cause the pipe to be rendered again. To ensure that the pipe is executed, you must create a new Date object.

The default locale used for formatting is the one provided by the Angular LOCALE_ID injection token. See the I18n guide for more information. It can also be passed into the pipe as a third parameter.

The time zone of the formatted value can be specified either by passing it in as a property of the second parameter of the pipe, or by setting the default through the INTL_DATE_TIMEZONE injection token. The value that is passed in as the second parameter takes precedence over the one defined using the injection token.

Pre-defined format options

The pipe comes with a set of pre-defined format options as shown below.

| Option | Examples (given in en-US locale) | |---------------|-------------------------------------------------| | 'short' | 6/15/15, 9:03 AM | | 'medium' | Jun 15, 2015, 9:03:01 AM | | 'long' | June 15, 2015 at 9:03:01 AM GMT+1 | | 'full' | Monday, June 15, 2015 at 9:03:01 AM GMT+01:00 | | 'shortDate' | 6/15/15 | | 'mediumDate'| Jun 15, 2015 | | 'longDate' | June 15, 2015 | | 'fullDate' | Monday, June 15, 2015 | | 'shortTime' | 9:03 AM | | 'mediumTime'| 9:03:01 AM | | 'longTime' | 9:03:01 AM GMT+1 | | 'fullTime' | 9:03:01 AM GMT+01:00 |

Presets and custom configuration

You can add custom configuration and presets using the INTL_DATE_OPTIONS injection token. This allows the definition of additional presets as well as setting a default preset, which is used if no preset name is provided to the pipe.

@NgModule({
  //…,
  providers: [
    //…,
    {
      provide: INTL_DATE_OPTIONS,
      useValue: {
        defaultPreset: 'custom'
        presets: {
          custom: {
            dateStyle: 'short'
          }
        }
      }
    },
    {
      provide: INTL_DATE_TIMEZONE,
      useValue: 'America/Los_Angeles'
    }
  ]
})

API

| Parameter | Type | Description | |--------------|---------------------------------------|-----------------------| | value | Date \| string \| number \| null \| undefined | The date to be formatted, given as a JS date, string or number. | | options | string \| IntlDateLocalOptions | The name of a preset or custom formatting options. | | ...locales | string[] | A list of locale overwrites. |

Browser compatibility

See mdn web docs | Browser compatibility.

intl-timeago

Format a relative time according to locale and formatting options.

Description

Pre-defined format options

Presets and custom configuration

API

Browser compatibility

See mdn web docs | Browser compatibility (Intl.RelativeTimeFormat) and mdn web docs | Browser compatibility (Intl.DateTimeFormat).

intl-number

Format a number according to locale and formatting options.

Description

Pre-defined format options

Presets and custom configuration

API

Browser compatibility

See mdn web docs | Browser compatibility.

intl-plural

Enables plural-sensitive formatting.

Description

The IntlPluralPipe provides help for pluralization based on parameters provided in the options. The locales and options parameters customize the behavior of the pipe and let applications specify the language conventions that should be used.

Pre-defined format options

The pipe comes with a set of pre-defined sort options as shown below.

| Option | Examples (given in en-US locale) | |----------------|------------------------------------| | 'cardinal' | 3 → other | | 'ordinal' | 3 → few |

Presets and custom configuration

You can add custom configuration and presets using the INTL_PLURAL_OPTIONS injection token. This allows the definition of additional presets as well as setting a default preset, which is used if no preset name is provided to the pipe.

@NgModule({
  //…,
  providers: [
    //…,
    {
      provide: INTL_PLURAL_OPTIONS,
      useValue: {
        defaultPreset: 'custom'
        presets: {
          custom: {
            type: 'ordinal'
          }
        }
      }
    }
  ]
})

API

| Parameter | Type | Description | |--------------|------------------------------------|-----------------------| | value | number \| null | The number to be converted. | | options | string \| IntlPluralLocalOptions | The name of a preset or custom pluralization options. | | ...locales | string[] | A list of locale overwrites. |

Browser compatibility

See mdn web docs | Browser compatibility.

intl-sort

Enables language-sensitive string comparison.

Description

The IntlSortPipe sorts a list of strings based on parameters provided in the options. The locales and options parameters customize the behavior of the pipe and let applications specify the language conventions that should be used to sort the list.

Pre-defined format options

You can add custom configuration and presets using the INTL_SORT_OPTIONS injection token. This allows the definition of additional presets as well as setting a default preset, which is used if no preset name is provided to the pipe.

@NgModule({
  //…,
  providers: [
    //…,
    {
      provide: INTL_SORT_OPTIONS,
      useValue: {
        defaultPreset: 'custom'
        presets: {
          custom: {
            sensitivity: 'base'
          }
        }
      }
    }
  ]
})

Presets and custom configuration

The pipe comes with a set of pre-defined sort options as shown below.

| Option | Examples (given in en-US locale) | |----------------|------------------------------------| | 'lowerFirst' | ['a', 'e', 'z', 'Z'] | | 'upperFirst' | ['a', 'e', 'Z', 'z'] |

API

| Parameter | Type | Description | |--------------|----------------------------------|-----------------------| | value | string[] \| null | The list of strings to be sorted. | | options | string \| IntlSortLocalOptions | The name of a preset or custom sort options. | | ...locales | string[] | A list of locale overwrites. |

Browser compatibility

See mdn web docs | Browser compatibility.

Code Contributors

This project exists thanks to all the people who contribute.

License

The license is available within this repository in the LICENSE file.