preact-icu

A tiny i18n provider with icu syntax for preact

• Focuses on tiny footprint (~10kb instead of ~120kb if using i18next).
• Uses extended ICU message syntax provided by intl-messageformat-tiny.
• Fetches translations by language and namespace
• Stores users language selection in cookie

Table of Contents

• installation
• usage
  • IntlProvider
  • useTranslation
  • Message
  • Number
  • DateTime
  • RelativeTime
• example and storybook
• license

installation

npm i preact-icu

usage

IntlProvider

Provides the context for the translations.

import { IntlProvider } from 'preact-icu'

const options = { // all settings are optional
  backendPath: '/locales/{lng}/{ns}.json?v={version}', // path to load translations 
    // lng, ns, version are templated values which will be replaced
  debug: false, // set debug mode
  log: console, // set logger function `{ debug, error }`
  supportedLngs: ['en', 'en-GB', 'de'], // list of supported languages
  version: '1.0.0', // version of translations
  cookie: {
    name: 'i18nLocale', // cookie name for storing user selection
    path: '/', // path cookie
    domain: 'domain.my' // domain cookie
  },
  resources: { // initial translations (optional)
    en: { Truck: 'Truck' },
    'en-GB': { Truck: 'Lorry' },
    de: { Truck: 'LKW',
      '{lng} selected': 'Gewählte Sprache: {lng}'  
    }
  }
}

function App (props) {
  <IntlProvider 
    lngs={['en', 'de']} 
    options={options}   
    fallback={<div>translations are loading...</div>}
  >
    {props.children}
  </IntlProvider>
}

props

| property | type | description | | --------- | ------------ | ------------------------------------------------------------------------------------------ | | fallback? | AnyComponent | fallback component which is rendered while new language settings are loading, e.g. spinner | | options? | object | init options | | lngs? | string[] | Array of languages which are loaded on initialization | | ns? | string[] | Array of namespaces which are loaded on initialization |

useTranslation

Grants access to the IntlProvider context.

import { useTranslation } from 'preact-icu'

function Test () {
  const { 
    t, // the translation function
    changeLanguage, // change language
    lng, // the selected language
    i18n // access to the instance
  } = useTranslation()

  return (
    <>
      <button onClick={() => changeLanguage('de')}>{t('Change to German')}</button>
      <p>t('{lng} selected', { lng })</p>
      <p>t('Truck')
    </>
  )
}

Message

Message which supports intl-messageformat-tiny syntax.

import { Message } from 'preact-icu'

const Hello = () => <Message label="Hello {name}!" name="Elsa" />
// <Hello/> -> "Hello Elsa!"

const Persons = ({ value = 0 }) => <Message 
  label="{value, plural, zero {No Persons} one {One Person} other {# Persons}}" 
  value={value} />
// <Persons value={0}> -> "No Persons"
// <Persons value={1}> -> "One Person"
// <Persons value={7}> -> "7 Persons"

props

| property | type | description | | -------- | ------ | ------------------------------ | | label | string | the translation label | | lng? | string | overrides the default language | | ns? | string | uses a different namespace (ensure to have the translations loaded before first use) | | ... | string | the placeholder value(s) |

Number

Uses Intl.NumberFormat to format a number.

import { Message } from 'preact-icu'

const MyNumber = () => <Number value={123456.012} />
// "1,234,567.089" for lng=en
// "1.234.567,089" for lng=de
const MyCurrency = () => <Number value={123456.012} currency="EUR" style="currency" />
// "€123,456.01"  for lng=en
// "123.456,01 €" for lng=de

props

| property | type | description | | -------- | ------ | ------------------------------------- | | value | number | the number to translate | | lng? | string | overrides the default language | | ... | any | see Intl.NumberFormat for all options. |

DateTime

Uses Intl.DateTimeFormat to format a date or time.

import { DateTime } from 'preact-icu'

const DateTimeShort = () => <DateTime value={new Date('2020-03-12')} />
// "3/12/2020" for lng='en-US'
// "12/03/2020" for lng='en-GB'
const DateTimeLong = () => <DateTime value={new Date()} weekday='long' year='numeric' month='long' day='numeric' />
// "Thursday, March 12, 2020" for lng='en-US'
// "Thursday, 12 March, 2020 "for lng='en-GB'

props

| property | type | description | | -------- | ------- | -------------------------------------------------------- | | value | number | the Date or Time to translate | | lng? | string | overrides the default language | | date? | boolean | if true show only date | | time? | boolean | if true show only time | | hour12? | boolean | if true show time in in 12 hour format with am, pm | | ... | any | see Intl.DateTimeFormat for all options. |

RelativeTime

Uses Intl.RelativeTimeFormat to format a relative date or time.

import { DateTime } from 'preact-icu'

const MyRelativeTime = () => <RelativeTime value="2022-01-01" />
// "7 months ago" for lng=en
const MyRelativeTime2 = () => <RelativeTime value="1" unit="day" />
// "tomorrow" for lng=en

props

| property | type | description | | -------- | ------------ | --------------------------------------- | | value | Date|number | the number to translate | | lng? | string | overrides the default language | | ... | any | see Intl.DateTimeFormat for all options. |

example and storybook

npm run dev

Then access http://localhost:5173

license

MIT licensed