locale

Create reactive locale metadata and platform-native formatter factories.


Package	`@vizejs/composable/locale`
Own the source	`vize lib pull composable:locale`
Runtime exports	`useLocale`
Gzip budget	2048 B

Usage

import { useLocale } from "@vizejs/composable/locale";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useLocale`	i18n	experimental	deterministic-fallback	caller-managed	none	web, server, worker, native, desktop, terminal	`Intl`, `navigator`	—

API

`useLocale`

Create reactive locale metadata and platform-native formatter factories. Equivalent formatter options reuse instances. The bounded cache follows the active locale automatically and prevents repeated constructor overhead in reactive render paths. Detection is lazy and guarded: the default detector reads navigator.language behind a typeof check at call time, so importing and calling this during server rendering is safe, and runtimes without a navigator resolve to the fallback locale. The composable owns no timers or listeners, so no scope cleanup is required.

function useLocale( source?: MaybeRefOrGetter<Intl.Locale | string | null | undefined>, options: UseLocaleOptions = {}, ): LocaleControls

Types

`UseLocaleOptions`

Locale selection options for useLocale.

Member	Type	Description
`detect`?	`() => Intl.Locale \| string \| null \| undefined`	Locale detector used when the reactive source has no value.
`fallback`?	`Intl.Locale \| string`	Locale used when neither the source nor detector provides one.

`LocaleControls`

Reactive locale metadata and cached formatter factories. Formatter factories propagate TypeError and RangeError from the platform Intl constructors when the supplied options are invalid.

Member	Type	Description
`locale`	`ComputedRef<string>`	Canonical Unicode locale identifier.
`details`	`ComputedRef<Intl.Locale>`	Parsed locale details supplied by the internationalization runtime.
`direction`	`ComputedRef<TextDirection>`	Native writing direction for the active locale.
`number`	`(options?: Intl.NumberFormatOptions) => Intl.NumberFormat`	Return a cached number formatter for the active locale and options.
`dateTime`	`(options?: Intl.DateTimeFormatOptions) => Intl.DateTimeFormat`	Return a cached date and time formatter for the active locale and options.
`list`	`(options?: Intl.ListFormatOptions) => Intl.ListFormat`	Return a cached list formatter for the active locale and options.
`relativeTime`	`(options?: Intl.RelativeTimeFormatOptions) => Intl.RelativeTimeFormat`	Return a cached relative-time formatter for the active locale and options.