@getcircuit/intl-tools

@getcircuit/intl-tools

Package of i18n related tools for Circuit's web apps.

• About
• How to use
  • IntlToolsProvider instead of IntlProvider
  • useIntlTools instead of useIntl
  • IntlToolsBag instead of IntlShape
• Components
  • FormattedCurrency
• Utilities
  • getBrowserLocale()
  • getBrowserTimeZone
  • getBrowserHourFormat

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'