InternationalizationProvider

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.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Internationalization Provider

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.

Usage guidance

• Use shipped Astryx locale catalogs from @astryxdesign/core/locales/* when one exists for your target locale.
• Use a same-shape local catalog only when Astryx has not shipped that locale yet or you are testing in-progress translations.
• Use real BCP 47 tags such as fr-FR, pt-BR, or ar-SA; regional locales fall back to their base language before English.
• 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.
• Avoid: Cast custom catalog maps to any; the i18n package exports ProviderMessagesByLocale, MessagesByLocale, Catalog, and RuntimeCatalog for local catalog typing.

Load a shipped Astryx locale catalog

import type {ReactNode} from 'react';
import {InternationalizationProvider} from '@astryxdesign/core/i18n';
import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';

export function AppI18n({children}: {children: ReactNode}) {
  return (
    <InternationalizationProvider locale="fr-FR" messages={{'fr-FR': frFR}}>
      {children}
    </InternationalizationProvider>
  );
}

Override one Astryx string

import type {ReactNode} from 'react';
import {InternationalizationProvider} from '@astryxdesign/core/i18n';

export function AppI18n({children}: {children: ReactNode}) {
  return (
    <InternationalizationProvider
      locale="en"
      overrides={{
        en: {'@astryx.selector.placeholder': 'Choose...'},
      }}
    >
      {children}
    </InternationalizationProvider>
  );
}

Provide a local fallback catalog

import type {ReactNode} from 'react';
import {
  InternationalizationProvider,
  type MessagesByLocale,
} from '@astryxdesign/core/i18n';
import ptBR from './locales/pt-BR.json';

const messages: MessagesByLocale = {'pt-BR': ptBR};

export function AppI18n({children}: {children: ReactNode}) {
  return (
    <InternationalizationProvider locale="pt-BR" messages={messages}>
      {children}
    </InternationalizationProvider>
  );
}

useCollator

Returns the sanctioned locale-aware comparator for custom sorting. The collator is recreated when the provider locale or an option changes.

Parameters

Returns

[
  {
    "name": "collator",
    "type": "Intl.Collator",
    "description": "A memoized collator bound to the active InternationalizationProvider locale."
  }
]

Usage guidance

• Reuse collator.compare in custom Table comparators and other user-visible string ordering.
• Avoid: Construct Intl.Collator directly or call localeCompare; those bypass the provider-backed locale contract.

useLocale

Reads the authoritative Astryx locale. Use it to thread the provider locale into pure formatting helpers and sibling-package APIs; do not derive a second locale from navigator.language or a hardcoded literal.

Returns

[
  {
    "name": "locale",
    "type": "Locale",
    "description": "The active InternationalizationProvider BCP 47 locale. Falls back to 'en' when no provider is present."
  }
]

Usage guidance

• Pass the returned locale to pure Astryx helpers or package APIs that require an explicit locale.
• Avoid: Use navigator.language or a hardcoded display locale as a fallback; InternationalizationProvider is the locale source.

useTranslator

Returns a translator function that resolves keys against the current locale, provider overrides, and the shipped English fallback catalog. Call inside a component; the returned function can be used anywhere within that component's scope.

Returns

[
  {
    "name": "value",
    "type": "(key: string, values?: Record<string, string | number | Date>) => string",
    "description": "A stable translator function bound to the current InternationalizationProvider context. Call it with a message key and optional ICU MessageFormat values to get the formatted string in the active locale. Safe to use in render, event handlers, effects, or any code that runs during the parent component's lifecycle."
  }
]

Examples

• Internationalization Provider — Shipped Locale: Load a locale catalog shipped by Astryx and re-render InternationalizationProvider with a new locale to update Astryx strings live.
• Internationalization Provider — Overrides: Override a small number of Astryx strings without providing a full locale catalog.
• Internationalization Provider — RTL Direction: 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.