@enact-ui/i18n

Optional internationalization utilities for ENACT UI.

Package Intent

This package exists to:

• Provide optional internationalization capabilities beyond React Aria's built-in support
• Extend React Aria's i18n with additional utilities and convenience APIs
• Support RTL/LTR text directionality management
• Provide consistent date/number/currency formatting utilities
• Optionally integrate with translation libraries (react-i18next, formatjs, etc.)
• Keep i18n features truly optional (not forced on all consumers)

If you don't need i18n features beyond React Aria's built-in support, do not install this package.

Installation

bun add @enact-ui/i18n @enact-ui/react

Features

• LocaleProvider - Centralized locale context that extends React Aria's I18nProvider
• useLocale - Enhanced locale hook with RTL detection and language/region parsing
• useTextDirection - RTL/LTR direction management with manual override
• Formatting utilities - Consistent date, number, currency, and relative time formatting

Usage

Locale Provider

Wrap your app with LocaleProvider to provide locale context to all components:

import { LocaleProvider } from '@enact-ui/i18n';

function App() {
  return (
    <LocaleProvider locale="en-US" currency="USD">
      <YourApp />
    </LocaleProvider>
  );
}

Using Locale Information

import { useLocale, useLocaleContext } from '@enact-ui/i18n';

function MyComponent() {
  // Enhanced locale hook
  const { locale, direction, isRTL, language, region } = useLocale();

  // Or use context for setLocale
  const { setLocale } = useLocaleContext();

  return (
    <div dir={direction}>
      <p>Current locale: {locale}</p>
      <button onClick={() => setLocale('fr-FR')}>Switch to French</button>
    </div>
  );
}

Text Direction

import { useTextDirection, TextDirectionProvider } from '@enact-ui/i18n';

// Using the hook
function MyComponent() {
  const { direction, isRTL, setDirection, resetDirection } = useTextDirection();

  return (
    <div dir={direction}>
      <button onClick={() => setDirection('rtl')}>Force RTL</button>
      <button onClick={resetDirection}>Auto</button>
    </div>
  );
}

// Or using the provider
function App() {
  return (
    <TextDirectionProvider onDirectionChange={(dir) => console.log(dir)}>
      <YourApp />
    </TextDirectionProvider>
  );
}

Formatting Utilities

import {
  formatDate,
  formatNumber,
  formatCurrency,
  formatRelativeTime
} from '@enact-ui/i18n';

// Date formatting
formatDate(new Date(), { format: 'short' }); // "1/27/2025"
formatDate(new Date(), { format: 'long', locale: 'fr-FR' }); // "27 janvier 2025"

// Number formatting
formatNumber(1234.56); // "1,234.56"
formatNumber(1234.56, { locale: 'de-DE' }); // "1.234,56"

// Currency formatting
formatCurrency(1234.56, { currency: 'USD' }); // "$1,234.56"
formatCurrency(1234.56, { currency: 'EUR', locale: 'de-DE' }); // "1.234,56 €"

// Relative time
formatRelativeTime(Date.now() - 5 * 60 * 1000); // "5 minutes ago"
formatRelativeTime(Date.now() + 2 * 60 * 60 * 1000); // "in 2 hours"

RTL Language Detection

import { isRTLLanguage, RTL_LANGUAGES } from '@enact-ui/i18n';

isRTLLanguage('ar-SA'); // true (Arabic)
isRTLLanguage('he-IL'); // true (Hebrew)
isRTLLanguage('en-US'); // false (English)

// List of supported RTL languages
console.log(RTL_LANGUAGES); // ["ar", "he", "fa", ...]

API Reference

Components

LocaleProvider

| Prop | Type | Default | Description | |------|------|---------|-------------| | locale | string | Browser locale | Current locale | | defaultLocale | string | "en-US" | Fallback locale | | currency | string | - | Default currency code | | onLocaleChange | (locale: string) => void | - | Locale change callback | | children | ReactNode | - | Child components |

TextDirectionProvider

| Prop | Type | Default | Description | |------|------|---------|-------------| | direction | "ltr" \| "rtl" | Auto | Force text direction | | updateDocument | boolean | true | Update document.dir | | onDirectionChange | (direction: "ltr" \| "rtl") => void | - | Direction change callback | | children | ReactNode | - | Child components |

Hooks

useLocale

Returns LocaleInfo:

| Property | Type | Description | |----------|------|-------------| | locale | string | Current locale string | | direction | "ltr" \| "rtl" | Text direction | | isRTL | boolean | RTL mode active | | isLTR | boolean | LTR mode active | | language | string | Language code (e.g., "en") | | region | string \| undefined | Region code (e.g., "US") |

useTextDirection

Returns TextDirectionInfo:

| Property | Type | Description | |----------|------|-------------| | direction | "ltr" \| "rtl" | Current direction | | isRTL | boolean | RTL mode active | | isLTR | boolean | LTR mode active | | setDirection | (dir: "ltr" \| "rtl") => void | Set direction manually | | resetDirection | () => void | Reset to auto detection | | isOverridden | boolean | Manual override active |

Peer Dependencies

• @enact-ui/react ^0.1.0
• react ^18.0.0 || ^19.0.0
• react-dom ^18.0.0 || ^19.0.0

Optional Peer Dependencies

For translation support:

• react-i18next ^13.0.0
• @formatjs/intl ^2.0.0

License

MIT