Wrapper for
@formatjs/intl
with additional features.
Please use @braw/compact-number
and @braw/how-ago
instead. They enable the same functionality without needing to wrap the entire Intl module.
Requires CLDR data to be imported. Learn more below.
Create a convertible instances of CompactNumber
, an object representing a number formatted in compact notation, with ability to convert it to an actual number that you can use to select correct plural form — something you can't do with built-in Intl APIs. Learn more →
Use instance of CompactNumber
within formatMessage
as a value to allow for mixed use — both as a number and formatted string, but do not use #
shorthand, since then the ‘pluralisable’ number will be used:
const messages = defineMessages({
users: {
id: 'users-count',
defaultMessage: '{count, plural, one {{count} user} other {{count} users}}',
},
})
intl.formatMessage(messages.users, {
count: intl.formatCompactNumber(31_411),
})
// => '31.4K users'
intl.formatMessage(messages.users, {
count: intl.formatCompactNumber(31_411),
})
// => '31,2 тис. користувачів'
Just like with any other format methods, the result of formatCompactNumber
is bound to a specific locale.
Format any messages, even those that are not included in message maps.
import myMessage from './i18n/en-US/greeting.ast.json'
/* => [
{ type: 0, value: 'Hello, ' },
{ type: 1, value: 'targetName' },
{ type: 0, value: '!' },
] */
// ...
intl.formatCustomMessage(myMessage, {
targetName: 'world',
})
// => 'Hello, world!'
Based on the code from Omorphia project by Modrinth.
Given one-two dates, calculates time difference between them, and then formats it in most applicable unit using Intl.RelativeTimeFormat
and with numeric
option set to 'automatic'
by default.
Can also be used through alias $ago
.
intl.formatTimeDifference(Date.now() - day)
// => 'yesterday'
intl.formatCustomMessage('Published {ago}', {
ago: intl.$ago(publishedAt),
})
// => 'Published 3 hours ago'
It can be configured to cut off after or even before a certain unit, through minimumUnit
and maximumUnit
options, in which case it will fallback to formatting the initial date using dateTimeOptions
:
intl.formatCustomMessage('Updated {ago}', {
ago: intl.$ago(lastUpdatedAt, {
maximumUnit: 'months',
}),
})
// + { lastUpdatedAt: Date.now() - (2 * day) }
// => 'Updated 2 days ago'
// + { lastUpdatedAt: Date.now() - year }
// => 'Updated December 31, 2021 at 2:44 PM'
By default it uses all relative units except for quarters, however you can change it by passing excludedUnits
option:
intl.formatCustomMessage('Updated {ago}', {
ago: intl.$ago(lastUpdatedAt),
})
// + { lastUpdatedAt: Date.now() - (8 * day) }
// => 'Updated last week'
intl.formatCustomMessage('Updated {ago}', {
ago: intl.$ago(lastUpdatedAt, {
excludedUnits: ['quarters', 'weeks'],
}),
})
// + { lastUpdatedAt: Date.now() - (8 * day) }
// => 'Updated 8 days ago'
This package must be installed together with original @formatjs/intl
.
npm
npm install @formatjs/intl @braw/extended-intl
pnpm
pnpm install @formatjs/intl @braw/extended-intl
yarn
yarn add @formatjs/intl @braw/extended-intl
Since it's a wrapper on top of IntlShape
from the original package, you can replace your existing createIntl
call from @formatjs/intl
to the one in @braw/extended-intl
.
Alias for createIntlCache
is also available, and while it's identical to the original, it might be more convenient to import both functions from the same place. There should not be any breaking changes when switching the libraries.
This package is written in TypeScript and almost all methods contain documentation.
Since CompactNumber
relies on CLDR data that is not available through browser built-in APIs, additional data needs to be imported. Without it, the results of CompactNumber
will be inaccurate and the API itself is pointless.
To import locale data import one of the files from /locale-data
:
// The first imported locale is considered the fallback if data is missing
import '@braw/extended-intl/locale-data/en'
import '@braw/extended-intl/locale-data/uk'
import { setDefaultNumberFormatDataLocale } from '@braw/extended-intl'
setDefaultNumberFormatDataLocale('uk') // set alternative fallback data
This project is fully powered by the works of Format.JS authors.