Preact-icu NPM

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

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