Internationalization Provider@astryxdesign/core v0.5.2 · InternationalizationProvider

Usage

Wraps your app to set the active locale and (optionally) merge additional translation catalogs + per-locale overrides. Astryx components inside the subtree resolve their strings against this context. If no provider is present, components fall back to the shipped English defaults.

ts
import {InternationalizationProvider} from '@astryxdesign/core/i18n'

Best practices

GuidancePractices
Do

Use shipped Astryx locale catalogs from @astryxdesign/core/locales/* when one exists for your target locale.

Do

Use a same-shape local catalog only when Astryx has not shipped that locale yet or you are testing in-progress translations.

Do

Use real BCP 47 tags such as fr, pt-BR, or ar; regional locales fall back to their base language before English.

Do

Set the dir attribute on <html> (or a wrapping element) yourself; the provider does not set it. Astryx components mirror layout and directional icons from the DOM dir, so an RTL locale won't visually mirror without it. Use getLocaleDirection(locale) to derive the value for both the provider and the DOM.

Don't

Cast custom catalog maps to any; the i18n package exports MessagesByLocale and Catalog for local catalog typing.

Props

PropTypeDescription
localerequired
string

BCP 47 language tag for the active locale (e.g. "en", "pt", "pt-BR", "zh-Hans"). Regional tags fall back to their base language, then to the shipped "en" catalog.

childrenrequired
ReactNode

Content to render with the internationalization provider.

messages
MessagesByLocale

Optional map of BCP 47 tag to translation catalog. Import shipped catalogs from @astryxdesign/core/locales/*; the shipped "en" catalog is always available and does not need to be listed here.

overrides
Overrides

Sparse per-locale key overrides applied on top of shipped defaults. Overrides are locale-keyed so a runtime locale swap picks up the correct set.

dir
'ltr' | 'rtl'

Explicit text-direction override for the context. When omitted, direction is derived from locale via Intl.Locale.getTextInfo(). This sets the direction Astryx reads, but it does NOT set the DOM dir attribute; you must set dir on <html> (or a wrapping element) yourself, since Astryx components mirror layout and directional icons from the DOM dir, not from this prop. Set both to the same value and keep them in sync.

Examples

Common configurations, variations, and states.
InternationalizationProvider — Shipped Locale
Open in Playground

Load a locale catalog shipped by Astryx and re-render InternationalizationProvider with a new locale to update Astryx strings live.

InternationalizationProvider — Overrides
Open in Playground

Override a small number of Astryx strings without providing a full locale catalog.

InternationalizationProvider — RTL Direction
Open in Playground

Toggle text direction with the dir prop and watch Astryx components mirror. Pagination flips its prev/next chevrons under RTL. The dir prop is passed to both InternationalizationProvider (so Astryx components pick it up) and the VStack (so the DOM subtree mirrors); both channels stay in sync with no extra wrapper.