CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-react-intl

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

hooks.mddocs/

Hooks and Imperative API

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

Capabilities

useIntl Hook

Primary hook for accessing the complete internationalization API programmatically.

/**
 * Hook for accessing the IntlShape object with all formatting methods
 * Must be used within an IntlProvider context
 * @returns IntlShape object with formatting methods and configuration
 */
function useIntl(): IntlShape;

interface IntlShape extends ResolvedIntlConfig, IntlFormatters<React.ReactNode> {
  /** Format ICU MessageFormat messages with interpolation */
  formatMessage(
    descriptor: MessageDescriptor,
    values?: Record<string, PrimitiveType | FormatXMLElementFn<string, string>>
  ): string;
  formatMessage(
    descriptor: MessageDescriptor,
    values?: Record<string, React.ReactNode | PrimitiveType | FormatXMLElementFn<string, React.ReactNode>>
  ): Array<React.ReactNode>;
  
  /** Current locale identifier */
  locale: string;
  /** Available translation messages */
  messages: Record<string, string>;
  /** Configured timezone */
  timeZone?: string;
  /** Custom format configurations */
  formats: CustomFormats;
  /** Default locale fallback */
  defaultLocale: string;
  /** Text component for rendering */
  textComponent?: React.ComponentType | keyof React.JSX.IntrinsicElements;
  /** Low-level formatters object */
  formatters: Formatters;
}

Usage Examples:

import { useIntl } from "react-intl";

function MyComponent() {
  const intl = useIntl();
  
  // Format messages programmatically
  const welcomeMessage = intl.formatMessage(
    { 
      id: 'welcome',
      defaultMessage: 'Welcome {name}!' 
    },
    { name: 'Alice' }
  );
  
  // Format dates
  const formattedDate = intl.formatDate(new Date(), {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  });
  
  // Format numbers
  const formattedPrice = intl.formatNumber(29.99, {
    style: 'currency',
    currency: 'USD'
  });
  
  // Complex conditional formatting
  const getStatusMessage = (count: number) => {
    if (count === 0) {
      return intl.formatMessage({ 
        id: 'noItems',
        defaultMessage: 'No items found' 
      });
    }
    
    return intl.formatMessage(
      {
        id: 'itemCount',
        defaultMessage: '{count, plural, one {# item} other {# items}} found'
      },
      { count }
    );
  };
  
  return (
    <div>
      <h1>{welcomeMessage}</h1>
      <p>Today is {formattedDate}</p>
      <p>Price: {formattedPrice}</p>
      <p>{getStatusMessage(itemCount)}</p>
    </div>
  );
}

Message Formatting Methods

Programmatic message formatting with support for interpolation and rich text.

/**
 * Format ICU MessageFormat messages with values
 * Returns string for simple interpolation, React nodes for rich text
 */
formatMessage(
  descriptor: MessageDescriptor,
  values?: Record<string, any>
): string | Array<React.ReactNode>;

/**
 * $t is an alias for formatMessage for shorter syntax
 */
$t(descriptor: MessageDescriptor, values?: Record<string, any>): string | Array<React.ReactNode>;

Usage Examples:

const intl = useIntl();

// Simple message
const simple = intl.formatMessage({
  id: 'greeting',
  defaultMessage: 'Hello!'
});

// Message with interpolation
const withValues = intl.formatMessage(
  {
    id: 'welcome',
    defaultMessage: 'Welcome {name}!'
  },
  { name: 'Bob' }
);

// Rich text with React components
const richText = intl.formatMessage(
  {
    id: 'terms',
    defaultMessage: 'I agree to the <link>terms</link>'
  },
  {
    link: (chunks) => <a href="/terms">{chunks}</a>
  }
);

// Using $t alias for shorter syntax
const shortSyntax = intl.$t(
  { id: 'save', defaultMessage: 'Save' }
);

// $t alias works identically to formatMessage
const aliasWithValues = intl.$t(
  {
    id: 'welcome',
    defaultMessage: 'Welcome {name}!'
  },
  { name: 'Alice' }
);

// Pluralization
const plural = intl.formatMessage(
  {
    id: 'items',
    defaultMessage: '{count, plural, =0 {no items} one {# item} other {# items}}'
  },
  { count: 5 }
);

Date and Time Formatting Methods

Programmatic date and time formatting methods.

/**
 * Format dates using Intl.DateTimeFormat
 */
formatDate(value: Date | number, options?: FormatDateOptions): string;

/**
 * Format times using Intl.DateTimeFormat  
 */
formatTime(value: Date | number, options?: FormatDateOptions): string;

/**
 * Format relative time periods
 */
formatRelativeTime(
  value: number, 
  unit?: Intl.RelativeTimeFormatUnit, 
  options?: FormatRelativeTimeOptions
): string;

/**
 * Format date/time ranges
 */
formatDateTimeRange(
  from: Date | number,
  to: Date | number, 
  options?: FormatDateTimeRangeOptions
): string;

/**
 * Get formatted date parts for custom rendering
 */
formatDateToParts(value: Date | number, options?: FormatDateOptions): Intl.DateTimeFormatPart[];

/**
 * Get formatted time parts for custom rendering
 */
formatTimeToParts(value: Date | number, options?: FormatDateOptions): Intl.DateTimeFormatPart[];

Usage Examples:

const intl = useIntl();
const now = new Date();

// Date formatting
const shortDate = intl.formatDate(now, { 
  year: 'numeric', 
  month: 'short', 
  day: 'numeric' 
});

const longDate = intl.formatDate(now, {
  weekday: 'long',
  year: 'numeric',
  month: 'long', 
  day: 'numeric'
});

// Time formatting
const time24 = intl.formatTime(now, { 
  hour: '2-digit', 
  minute: '2-digit',
  hour12: false 
});

const time12 = intl.formatTime(now, {
  hour: 'numeric',
  minute: '2-digit',
  hour12: true
});

// Relative time
const relativeTime = intl.formatRelativeTime(-1, 'day');
// Output: "1 day ago"

const autoRelative = intl.formatRelativeTime(-1, 'day', { 
  numeric: 'auto' 
});
// Output: "yesterday"

// Date range
const range = intl.formatDateTimeRange(
  new Date('2023-12-01'),
  new Date('2023-12-03')
);
// Output: "Dec 1 – 3, 2023"

// Date parts for custom rendering
const dateParts = intl.formatDateToParts(now, {
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});
// Returns: [
//   { type: 'month', value: 'December' },
//   { type: 'literal', value: ' ' },
//   { type: 'day', value: '10' },
//   { type: 'literal', value: ', ' },
//   { type: 'year', value: '2023' }
// ]

Number and List Formatting Methods

Programmatic number, currency, and list formatting methods.

/**
 * Format numbers using Intl.NumberFormat
 */
formatNumber(value: number, options?: FormatNumberOptions): string;

/**
 * Format lists using Intl.ListFormat
 */
formatList(value: React.ReactNode[], options?: FormatListOptions): string;

/**
 * Format display names using Intl.DisplayNames
 */
formatDisplayName(value: string, options: FormatDisplayNameOptions): string;

/**
 * Format plurals based on count
 */
formatPlural(value: number, options?: FormatPluralOptions): Intl.LDMLPluralRule;

/**
 * Get formatted number parts for custom rendering
 */
formatNumberToParts(value: number, options?: FormatNumberOptions): Intl.NumberFormatPart[];

/**
 * Get formatted list parts for custom rendering
 */
formatListToParts(value: React.ReactNode[], options?: FormatListOptions): Intl.ListFormatPart[];

Usage Examples:

const intl = useIntl();

// Number formatting
const basicNumber = intl.formatNumber(1234.56);
// Output: "1,234.56" (en-US), "1.234,56" (de-DE)

const currency = intl.formatNumber(29.99, {
  style: 'currency',
  currency: 'USD'
});
// Output: "$29.99"

const percent = intl.formatNumber(0.75, {
  style: 'percent'
});
// Output: "75%"

// List formatting
const list = intl.formatList(['Apple', 'Banana', 'Orange']);
// Output: "Apple, Banana, and Orange"

const orList = intl.formatList(['Red', 'Blue'], {
  type: 'disjunction'
});
// Output: "Red or Blue"

// Display names
const languageName = intl.formatDisplayName('fr', {
  type: 'language'
});
// Output: "French"

const countryName = intl.formatDisplayName('JP', {
  type: 'region'
});
// Output: "Japan"

// Plural form detection
const pluralForm = intl.formatPlural(5);
// Returns: "other" (for English)

// Parts for custom rendering
const numberParts = intl.formatNumberToParts(1234.56, {
  style: 'currency',
  currency: 'USD'
});
// Returns parts array for custom styling

Dynamic Formatting Patterns

Advanced patterns for dynamic and conditional formatting.

Usage Examples:

function DynamicFormattingComponent() {
  const intl = useIntl();
  
  // Dynamic message selection
  const getGreeting = (timeOfDay: 'morning' | 'afternoon' | 'evening') => {
    const messages = {
      morning: { id: 'greeting.morning', defaultMessage: 'Good morning!' },
      afternoon: { id: 'greeting.afternoon', defaultMessage: 'Good afternoon!' },
      evening: { id: 'greeting.evening', defaultMessage: 'Good evening!' }
    };
    
    return intl.formatMessage(messages[timeOfDay]);
  };
  
  // Conditional formatting based on value
  const formatQuantity = (count: number, item: string) => {
    if (count === 0) {
      return intl.formatMessage(
        { id: 'quantity.none', defaultMessage: 'No {item}' },
        { item }
      );
    }
    
    return intl.formatMessage(
      {
        id: 'quantity.some',
        defaultMessage: '{count, plural, one {# {item}} other {# {item}s}}'
      },
      { count, item }
    );
  };
  
  // Complex data formatting
  const formatOrderSummary = (order: Order) => {
    const total = intl.formatNumber(order.total, {
      style: 'currency',
      currency: order.currency
    });
    
    const date = intl.formatDate(order.date, {
      month: 'short',
      day: 'numeric',
      year: 'numeric'
    });
    
    return intl.formatMessage(
      {
        id: 'order.summary',
        defaultMessage: 'Order #{id} for {total} placed on {date}'
      },
      { id: order.id, total, date }
    );
  };
  
  return (
    <div>
      <p>{getGreeting('morning')}</p>
      <p>{formatQuantity(5, 'item')}</p>
      <p>{formatOrderSummary(currentOrder)}</p>
    </div>
  );
}

Types

interface ResolvedIntlConfig {
  locale: string;
  timeZone?: string;
  fallbackOnEmptyString?: boolean;
  formats: CustomFormats;
  messages: Record<string, string>;
  defaultLocale: string;
  defaultFormats: CustomFormats;
  onError: (error: ReactIntlError) => void;
  textComponent?: React.ComponentType | keyof React.JSX.IntrinsicElements;
  wrapRichTextChunksInFragment?: boolean;
  defaultRichTextElements?: Record<string, FormatXMLElementFn<React.ReactNode>>;
}

interface IntlFormatters<T = string> {
  formatDate(value: Date | number, options?: FormatDateOptions): string;
  formatTime(value: Date | number, options?: FormatDateOptions): string;
  formatDateTimeRange(from: Date | number, to: Date | number, options?: FormatDateTimeRangeOptions): string;
  formatNumber(value: number, options?: FormatNumberOptions): string;
  formatList(value: T[], options?: FormatListOptions): string;
  formatDisplayName(value: string, options: FormatDisplayNameOptions): string;
  formatPlural(value: number, options?: FormatPluralOptions): Intl.LDMLPluralRule;
  formatRelativeTime(value: number, unit?: Intl.RelativeTimeFormatUnit, options?: FormatRelativeTimeOptions): string;
  formatDateToParts(value: Date | number, options?: FormatDateOptions): Intl.DateTimeFormatPart[];
  formatTimeToParts(value: Date | number, options?: FormatDateOptions): Intl.DateTimeFormatPart[];
  formatNumberToParts(value: number, options?: FormatNumberOptions): Intl.NumberFormatPart[];
  formatListToParts(value: T[], options?: FormatListOptions): Intl.ListFormatPart[];
}

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

docs

date-time.md

hooks.md

index.md

inject-intl.md

messages.md

number-list.md

provider.md

tile.json