# @zerolith/i18n

Import from `@zerolith/i18n`. Generated from the source; every signature below is what the published types declare.

## Functions

### parseAcceptLanguage

```ts
function parseAcceptLanguage(header: string | null | undefined): LanguageRange[]
```

Parses an `Accept-Language` header into ranges ordered by quality, dropping those with quality zero.

Source: `packages/i18n/src/index.ts:21`

### negotiateLocale

```ts
function negotiateLocale(requested: string | readonly string[] | null | undefined, supported: readonly string[], fallback: string): string
```

Picks the supported locale that best matches what was requested: an
`Accept-Language` header, `navigator.languages`, or one tag. Each range
is tried in order of quality, first as an exact match, then by dropping
subtags from the end as RFC 4647 lookup does, then as the language of a
more specific supported locale, preferring one written in the same
script, so `zh-HK` finds `zh-TW` before `zh-CN`. `*` and no match at all
give `fallback`.

Source: `packages/i18n/src/index.ts:75`

### localeDirection

```ts
function localeDirection(locale: string): "ltr" | "rtl"
```

The writing direction of a locale, from `Intl.Locale` where the engine provides it and otherwise from its script, the likely one when the tag names none, as engines decide.

Source: `packages/i18n/src/index.ts:122`

### createLocale

```ts
function createLocale(options: LocaleOptions): LocaleState
```

Creates the locale state for an application. Throws a `TypeError` when `supported` is empty or `fallback` is not one of its locales, since the locale must always be one of them.

Source: `packages/i18n/src/index.ts:166`

### applyLocale

```ts
function applyLocale(state: LocaleState, doc?: Document): () => void
```

Keeps the document's `lang` and `dir` attributes in step with the locale; returns the effect's disposer.

Source: `packages/i18n/src/index.ts:191`

### formatters

```ts
function formatters(locale: ReadableSignal<string> | string): Formatters
```

Creates formatters over a locale, given as a signal or as a fixed tag. Instances are cached per locale and options.

Source: `packages/i18n/src/index.ts:230`

## Interfaces

### LanguageRange

```ts
interface LanguageRange
```

One entry of an `Accept-Language` header or of `navigator.languages`.

- `readonly range: string`: The language tag, or `*` for any language, as written before any `;` parameters.
- `readonly quality: number`: The entry's `q` weight between 0 and 1, rounded to three decimals; 1 when the entry gives none.

Source: `packages/i18n/src/index.ts:12`

### LocaleOptions

```ts
interface LocaleOptions
```

Options for `createLocale`.

- `supported: readonly string[]`: The locales the application ships, most preferred first.
- `fallback?: string`: The locale used when nothing matches, one of `supported`. Defaults to the first supported one.
- `initial?: string | readonly string[] | null`: What to negotiate from at first: an `Accept-Language` header, `navigator.languages`, or a tag. Defaults to the fallback.

Source: `packages/i18n/src/index.ts:142`

### LocaleState

```ts
interface LocaleState
```

The current locale as state.

- `readonly locale: ReadableSignal<string>`: The current locale, always one of `supported`.
- `readonly direction: ReadableSignal<"ltr" | "rtl">`: The writing direction of the current locale.
- `readonly supported: readonly string[]`: A copy of the `supported` option, in the same order; `set` negotiates against it.
- `set(requested: string | readonly string[]): void`: Switches locales after negotiating the request against `supported`.

Source: `packages/i18n/src/index.ts:153`

### Formatters

```ts
interface Formatters
```

Formatters for the current locale; each reads the locale signal when called, so a computed value or template re-renders on a locale change.

- `number(value: number, options?: Intl.NumberFormatOptions): string`: Formats a number with `Intl.NumberFormat`.
- `date(value: Date | number, options?: Intl.DateTimeFormatOptions): string`: Formats a `Date`, or a timestamp in milliseconds since the epoch, with `Intl.DateTimeFormat`.
- `relative(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string`: Formats a time `value` units of `unit` away from now with `Intl.RelativeTimeFormat`, such as `in 2 hours`; a negative value lies in the past.
- `list(values: Iterable<string>, options?: Intl.ListFormatOptions): string`: Joins strings into a list with `Intl.ListFormat`, such as `a, b, and c` in English.
- `plural(value: number, options?: Intl.PluralRulesOptions): Intl.LDMLPluralRule`: Selects the plural category of a number with `Intl.PluralRules`, such as `one` or `other`, for choosing a message variant.

Source: `packages/i18n/src/index.ts:201`