# preact-icu

> tiny i18n provider with icu syntax for preact

Latest version **1.0.1** (published 2023-09-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install preact-icu
pnpm add preact-icu
yarn add preact-icu
bun add preact-icu
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2023-09-25 |
| First published | 2022-11-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 44.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | spurreiter |
| Maintainers | spurreiter |
| Keywords | globalization, i18n, i18next, icu, internationalization, localization, preact, translation |

## Links

- npm: https://www.npmjs.com/package/preact-icu
- Repository: https://github.com/spurreiter/preact-icu
- Homepage: https://github.com/spurreiter/preact-icu#readme
- Issues: https://github.com/spurreiter/preact-icu/issues
- npm.io page: https://npm.io/package/preact-icu

## Dependencies (2)

- [preact](https://npm.io/package/preact.md) ^10.17.1
- [intl-messageformat-tiny](https://npm.io/package/intl-messageformat-tiny.md) ^1.0.3

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2023-09-25
- 1.0.0 — 2022-11-20

## README

# 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

<!-- !toc (omit="preact-icu;Table of Contents") -->

* [installation](#installation)
* [usage](#usage)
  * [IntlProvider](#intlprovider)
  * [useTranslation](#usetranslation)
  * [Message](#message)
  * [Number](#number)
  * [DateTime](#datetime)
  * [RelativeTime](#relativetime)
* [example and storybook](#example-and-storybook)
* [license](#license)

<!-- toc! -->

# installation

```
npm i preact-icu
```

# usage

## IntlProvider

Provides the context for the translations.

```jsx
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.

```jsx
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.

```jsx
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`][Intl.NumberFormat] to format a number.

```jsx
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`][Intl.DateTimeFormat] to format a date or time.

```jsx
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`][Intl.RelativeTimeFormat] to format a relative date or time.

```jsx
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](./LICENSE)


[intl-messageformat-tiny]: https://github.com/spurreiter/intl-messageformat-tiny#readme
[ICU message syntax]: https://formatjs.io/docs/core-concepts/icu-syntax

[Intl.NumberFormat]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat
[Intl.DateTimeFormat]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat
[Intl.DateTime]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat
[Intl.RelativeTimeFormat]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat

[i18next]: https://www.i18next.com

---
_Source: https://npm.io/package/preact-icu · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._