or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

date-time.mdhooks.mdindex.mdinject-intl.mdmessages.mdnumber-list.mdprovider.md
tile.json

tessl/npm-react-intl

Internationalize React apps with components and APIs for formatting dates, numbers, strings, pluralization and translations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-intl@7.1.x

To install, run

npx @tessl/cli install tessl/npm-react-intl@7.1.0

index.mddocs/

React Intl

React Intl is a comprehensive internationalization library for React applications that provides components and hooks for formatting dates, numbers, and messages with full support for pluralization, relative time formatting, and locale-aware translations. It offers a declarative API through React components and imperative hooks for programmatic access to formatting functions.

Package Information

  • Package Name: react-intl
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install react-intl

Core Imports

import { 
  IntlProvider, 
  FormattedMessage, 
  FormattedDate, 
  FormattedNumber,
  useIntl 
} from "react-intl";

For CommonJS:

const { 
  IntlProvider, 
  FormattedMessage, 
  FormattedDate, 
  FormattedNumber,
  useIntl 
} = require("react-intl");

Basic Usage

import React from "react";
import { 
  IntlProvider, 
  FormattedMessage, 
  FormattedDate, 
  FormattedNumber,
  defineMessages 
} from "react-intl";

// Define messages
const messages = defineMessages({
  welcome: {
    id: "app.welcome",
    defaultMessage: "Welcome {name}!",
  },
  itemCount: {
    id: "app.itemCount", 
    defaultMessage: "You have {count, plural, =0 {no items} one {# item} other {# items}}",
  },
});

// Application with i18n
function App() {
  return (
    <IntlProvider locale="en" messages={{
      "app.welcome": "Welcome {name}!",
      "app.itemCount": "You have {count, plural, =0 {no items} one {# item} other {# items}}"
    }}>
      <div>
        <FormattedMessage {...messages.welcome} values={{ name: "Alice" }} />
        <FormattedDate value={new Date()} />
        <FormattedNumber value={1234.56} style="currency" currency="USD" />
        <FormattedMessage {...messages.itemCount} values={{ count: 5 }} />
      </div>
    </IntlProvider>
  );
}

Architecture

React Intl is built around several key architectural components:

  • Provider System: IntlProvider establishes locale context for the entire component tree
  • Component API: Declarative React components for formatting (FormattedMessage, FormattedDate, etc.)
  • Hook API: useIntl hook provides imperative access to formatting functions
  • HOC Support: injectIntl higher-order component for legacy class components
  • Message System: ICU MessageFormat parsing with interpolation, pluralization, and rich text
  • Formatter Integration: Built on top of native Intl APIs and FormatJS ecosystem
  • Type Safety: Full TypeScript support with generic type preservation

Capabilities

Provider and Context

Core provider component that establishes internationalization context for React components, managing locale data, messages, and formatting configuration.

function IntlProvider(props: React.PropsWithChildren<IntlConfig>): React.JSX.Element;
function createIntl(config: IntlConfig, cache?: IntlCache): IntlShape;

interface IntlConfig {
  locale: string;
  messages?: Record<string, string>;
  formats?: CustomFormats;
  defaultLocale?: string;
  timeZone?: string;
  onError?: (error: ReactIntlError) => void;
  textComponent?: React.ComponentType | keyof React.JSX.IntrinsicElements;
}

Provider and Context

Message Formatting

Components and functions for formatting ICU messages with interpolation, pluralization, and rich text rendering support.

function FormattedMessage(props: {
  id?: string;
  description?: string;
  defaultMessage?: string;
  values?: Record<string, React.ReactNode | PrimitiveType>;
  tagName?: React.ElementType<any>;
  children?(nodes: React.ReactNode[]): React.ReactNode | null;
}): React.ReactElement;

function FormattedPlural(props: FormatPluralOptions & {
  value: number;
  other: React.ReactNode;
  zero?: React.ReactNode;
  one?: React.ReactNode;
  two?: React.ReactNode;
  few?: React.ReactNode;
  many?: React.ReactNode;
}): React.ReactElement;

function defineMessages<T extends Record<string, MessageDescriptor>>(msgs: T): T;
function defineMessage<T extends MessageDescriptor>(msg: T): T;

Message Formatting

Date and Time Formatting

Components for formatting dates, times, relative times, and date ranges with full locale support and customizable formats.

const FormattedDate: React.FC<
  Intl.DateTimeFormatOptions & 
  CustomFormatConfig & {
    value: string | number | Date | undefined;
    children?(formattedDate: string): React.ReactElement | null;
  }
>;

const FormattedTime: React.FC<
  Intl.DateTimeFormatOptions & 
  CustomFormatConfig & {
    value: string | number | Date | undefined;
    children?(formattedTime: string): React.ReactElement | null;
  }
>;

function FormattedRelativeTime(props: FormatRelativeTimeOptions & {
  value?: number;
  unit?: Intl.RelativeTimeFormatUnit;
  updateIntervalInSeconds?: number;
  children?(value: string): React.ReactElement | null;
}): React.ReactElement;

function FormattedDateTimeRange(props: FormatDateTimeRangeOptions & {
  from: Date | number;
  to: Date | number;
  children?(value: React.ReactNode): React.ReactElement | null;
}): React.ReactElement;

const FormattedDateParts: React.FC<
  FormatDateOptions & {
    value: Date | number | string;
    children(val: Intl.DateTimeFormatPart[]): React.ReactElement | null;
  }
>;

const FormattedTimeParts: React.FC<
  FormatDateOptions & {
    value: Date | number | string;
    children(val: Intl.DateTimeFormatPart[]): React.ReactElement | null;
  }
>;

Date and Time Formatting

Number and List Formatting

Components for formatting numbers, currencies, percentages, lists, and display names with locale-aware formatting rules.

const FormattedNumber: React.FC<
  Omit<NumberFormatOptions, 'localeMatcher'> &
  CustomFormatConfig<'number'> & {
    value: Parameters<IntlShape['formatNumber']>[0];
    children?(formattedNumber: string): React.ReactElement | null;
  }
>;

const FormattedList: React.FC<
  Intl.ListFormatOptions & {
    value: readonly React.ReactNode[];
  }
>;

const FormattedDisplayName: React.FC<
  Intl.DisplayNamesOptions & {
    value: string;
  }
>;

const FormattedNumberParts: React.FC<
  FormatNumberOptions & {
    value: Parameters<IntlShape['formatNumber']>[0];
    children(val: Intl.NumberFormatPart[]): React.ReactElement | null;
  }
>;

const FormattedListParts: React.FC<
  FormatListOptions & {
    value: readonly React.ReactNode[];
    children(val: Intl.ListFormatPart[]): React.ReactElement | null;
  }
>;

Number and List Formatting

Hooks and Imperative API

React hooks providing programmatic access to all formatting functions, ideal for complex formatting logic and dynamic content.

function useIntl(): IntlShape;

interface IntlShape {
  formatMessage(
    descriptor: MessageDescriptor,
    values?: Record<string, React.ReactNode | PrimitiveType>
  ): string | Array<React.ReactNode>;
  formatDate(value: Date | number, options?: FormatDateOptions): string;
  formatTime(value: Date | number, options?: FormatDateOptions): string;
  formatNumber(value: number, options?: FormatNumberOptions): string;
  formatRelativeTime(value: number, unit?: Intl.RelativeTimeFormatUnit, options?: FormatRelativeTimeOptions): string;
  formatList(value: React.ReactNode[], options?: FormatListOptions): string;
  locale: string;
  messages: Record<string, string>;
}

Hooks and Imperative API

Legacy HOC Support

Higher-order component for injecting intl functionality into class components, providing backward compatibility with legacy codebases.

function injectIntl<P extends WrappedComponentProps>(
  WrappedComponent: React.ComponentType<P>,
  options?: {
    intlPropName?: string;
    forwardRef?: boolean; 
    enforceContext?: boolean;
  }
): React.ComponentType<WithIntlProps<P>>;

type WrappedComponentProps<IntlPropName extends string = 'intl'> = {
  [k in IntlPropName]: IntlShape;
};

Legacy HOC Support

Types

interface MessageDescriptor {
  id?: string;
  description?: string;
  defaultMessage?: string;
}

interface CustomFormats {
  date?: Record<string, Intl.DateTimeFormatOptions>;
  time?: Record<string, Intl.DateTimeFormatOptions>;
  number?: Record<string, Intl.NumberFormatOptions>;
}

interface CustomFormatConfig<T extends keyof CustomFormats = keyof CustomFormats> {
  format?: string;
}

interface IntlShape {
  locale: string;
  messages: Record<string, string>;
  formatMessage(descriptor: MessageDescriptor, values?: Record<string, any>): string | React.ReactNode[];
  $t(descriptor: MessageDescriptor, values?: Record<string, any>): string | React.ReactNode[];
  formatDate(value: Date | number, options?: FormatDateOptions): string;
  formatTime(value: Date | number, options?: FormatDateOptions): string;
  formatDateToParts(value: Date | number, options?: FormatDateOptions): Intl.DateTimeFormatPart[];
  formatTimeToParts(value: Date | number, options?: FormatDateOptions): Intl.DateTimeFormatPart[];
  formatNumber(value: number, options?: FormatNumberOptions): string;
  formatNumberToParts(value: number, options?: FormatNumberOptions): Intl.NumberFormatPart[];
  formatRelativeTime(value: number, unit?: Intl.RelativeTimeFormatUnit, options?: FormatRelativeTimeOptions): string;
  formatList(value: React.ReactNode[], options?: Intl.ListFormatOptions): string;
  formatListToParts(value: React.ReactNode[], options?: FormatListOptions): Intl.ListFormatPart[];
  formatPlural(value: number, options?: FormatPluralOptions): Intl.LDMLPluralRule;
  formatDisplayName(value: string, options: FormatDisplayNameOptions): string;
  formatDateTimeRange(from: Date | number, to: Date | number, options?: FormatDateTimeRangeOptions): string;
  formatters: Formatters;
}

interface IntlCache {
  // Opaque cache structure for formatter instances
}

interface FormatDateOptions extends Intl.DateTimeFormatOptions {
  format?: string;
}

interface FormatNumberOptions extends Intl.NumberFormatOptions {
  format?: string;
}

interface FormatListOptions extends Intl.ListFormatOptions {
  format?: string;
}

interface FormatDisplayNameOptions extends Intl.DisplayNamesOptions {
  format?: string;
}

interface FormatRelativeTimeOptions {
  style?: 'long' | 'short' | 'narrow';
  numeric?: 'always' | 'auto';
}

interface FormatPluralOptions {
  type?: 'cardinal' | 'ordinal';
}

interface FormatDateTimeRangeOptions extends Intl.DateTimeFormatOptions {
  format?: string;
}

type PrimitiveType = string | number | boolean | null | undefined | Date;

// Error types
class ReactIntlError extends Error {}
class MessageFormatError extends ReactIntlError {}
class MissingTranslationError extends ReactIntlError {}
class MissingDataError extends ReactIntlError {}
class InvalidConfigError extends ReactIntlError {}
class UnsupportedFormatterError extends ReactIntlError {}

enum ReactIntlErrorCode {
  MISSING_TRANSLATION = 'MISSING_TRANSLATION',
  MISSING_DATA = 'MISSING_DATA', 
  INVALID_CONFIG = 'INVALID_CONFIG'
}

interface Formatters {
  // Internal formatters structure (opaque)
}

// Additional type exports
type MessageFormatElement = any; // From @formatjs/icu-messageformat-parser

type FormatXMLElementFn<T, U = T> = (parts: Array<string | T>) => U;