@getcircuit/intl-tools v15.18.0
@getcircuit/intl-tools
Package of i18n related tools for Circuit's web apps.
About
Circuit has its specific requirements regarding i18n. Our i18n approach is based react-intl, but we have a few additional requirements that are not supported natively by it.
@getcircuit/intl-tools
is a wrapper around react-intl that provides a few additional features that will be explained in the following sections.
How to use
This package is supposed to work exactly like react-intl, so make sure to check out their documentation.
The main key differences are the following:
IntlToolsProvider
instead of IntlProvider
Instead of using IntlProvider
from react-intl
, use IntlToolsProvider
from @getcircuit/intl-tools
.
-import { IntlProvider } from 'react-intl'
+import { IntlToolsProvider } from '@getcircuit/intl-tools'
const App = () => {
return (
- <IntlProvider locale="en" messages={messages}>
+ <IntlToolsProvider locale="en" messages={messages} preferredHourFormat="24-hour">
<App />
+ </IntlToolsProvider>
- </IntlProvider>
)
}
useIntlTools
instead of useIntl
Instead of using intl
from react-intl
, use intlTools
from @getcircuit/intl-tools
.
-import { useIntl } from 'react-intl'
+import { useIntlTools } from '@getcircuit/intl-tools'
const MyComponent = () => {
- const intl = useIntl()
+ const intlTools = useIntlTools()
const { preferredHourFormat, formatEpochTime, formatEpochDate, formatCurrency } = intlTools
// ...
}
IntlToolsBag
instead of IntlShape
The object exposed by the IntlToolsProvider
and read via useIntlTools
is not the same as the one provided by react-intl
. It's composed of a reduced version of the original IntlShape
object, plus a few extra properties.
type IntlToolsBag = {
// Picked, original properties
locale: string
timeZone?: string
messages: Record<string, string>
textComponent: React.ElementType
formatDate
formatDateToParts
formatTime
formatTimeToParts
formatRelativeTime
formatNumber
formatPlural
formatMessage
formatList
// Extra properties
preferredHourFormat: '12-hour' | '24-hour'
formatEpochTime
formatEpochDate
formatCurrency
}
This decision was done to provide an easier-to-use API for Circuit's use case. We can always add more properties to the
IntlToolsBag
object if needed. What's important is that we have control over this object and we can add/remove properties as we see fit.
And that's it, really. The rest of the API is the same as react-intl.
Components
@getcircuit/intl-tools
provides the same components as react-intl
, plusa few additional ones.
import {
// Original components
FormattedDate,
FormattedDateToParts,
FormattedTime,
FormattedTimeToParts,
FormattedNumber,
FormattedMessage,
FormattedList,
FormattedPlural,
FormattedRelativeTime,
// Additional components
FormattedCurrency,
} from '@getcircuit/intl-tools'
The original components documentation can be found in react-intl's page.
FormattedCurrency
Formats a number as the specified currency. It takes the same props as react-intl's FormattedNumber
, but it also takes into account the user's preferences and some other Circuit specific requirements.
import { FormattedCurrency } from '@getcircuit/intl-tools'
const MyComponent = () => {
return (
<FormattedCurrency value={1000} currency="USD" currencyDisplay="symbol" />
)
}
FormattedEpochTime
Formats an epoch timestamp as time.
import { FormattedEpochTime } from '@getcircuit/intl-tools'
const MyComponent = () => {
return <FormattedEpochTime value={1679064790} /> // 15:53
}
FormattedEpochDate
Formats an epoch timestamp as date.
import { FormattedEpochDate } from '@getcircuit/intl-tools'
const MyComponent = () => {
return <FormattedEpochDate value={1679064790} /> // 2023-03-17
}
FormattedSecondsTime
Formats a number of seconds as time.
import { FormattedSecondsTime } from '@getcircuit/intl-tools'
const MyComponent = () => {
return <FormattedSecondsTime value={3600} /> // 01:00
}
Utilities
@getcircuit/intl-tools
provides a few handy utilities.
getBrowserLocale()
Returns the browser's locale.
import { getBrowserLocale } from '@getcircuit/intl-tools'
const locale = getBrowserLocale() // 'en-GB'
getBrowserTimeZone
Returns the browser's time zone.
import { getBrowserTimeZone } from '@getcircuit/intl-tools'
const timeZone = getBrowserTimeZone() // 'Europe/London'
getBrowserHourFormat
Returns the browser's hour format in Circuit's 12-hour
or 24-hour
format.
Note ⚠️: this method doesn't work in Firefox. Make sure to provide a fallback value if you need to support Firefox.
import { getBrowserHourFormat } from '@getcircuit/intl-tools'
const hourFormat = getBrowserHourFormat() // '12-hour'
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago