Message Formatting

/**
 * Component for rendering ICU MessageFormat messages with React integration
 * @param props - Message descriptor and formatting options
 */
function FormattedMessage<V extends Record<string, any> = Record<string, React.ReactNode | PrimitiveType>>(
  props: MessageDescriptor & {
    /** Values for message interpolation */
    values?: V;
    /** HTML tag or React component to wrap the message */
    tagName?: React.ElementType<any>;
    /** Render prop receiving formatted message nodes */
    children?(nodes: React.ReactNode[]): React.ReactNode | null;
    /** Whether to ignore tag formatting in rich text */
    ignoreTag?: boolean;
  }
): React.ReactElement;

interface MessageDescriptor {
  /** Unique message identifier */
  id?: string;
  /** Human-readable description for translators */
  description?: string;
  /** Default message text in source language */
  defaultMessage?: string;
}

import { FormattedMessage } from "react-intl";

// Basic message
<FormattedMessage 
  id="greeting"
  defaultMessage="Hello!" 
/>

// Message with interpolation
<FormattedMessage
  id="welcome"
  defaultMessage="Welcome back, {name}!"
  values={{ name: "Alice" }}
/>

// Message with pluralization
<FormattedMessage
  id="itemCount"
  defaultMessage="You have {count, plural, =0 {no items} one {# item} other {# items}}"
  values={{ count: 5 }}
/>

// Rich text with React components
<FormattedMessage
  id="terms"
  defaultMessage="I agree to the <link>terms and conditions</link>"
  values={{
    link: (chunks) => <a href="/terms">{chunks}</a>
  }}
/>

// Custom wrapper component
<FormattedMessage
  id="alert"
  defaultMessage="Warning: Please save your work"
  tagName="strong"
/>

// Render prop pattern
<FormattedMessage
  id="complex"
  defaultMessage="Processing {progress}%"
  values={{ progress: 75 }}
>
  {(formattedMessage) => (
    <div className="progress-text">{formattedMessage}</div>
  )}
</FormattedMessage>

/**
 * Define multiple messages with preserved key typing
 * @param msgs - Record of message descriptors
 * @returns Same record with preserved TypeScript types
 */
function defineMessages<K extends keyof any, T = MessageDescriptor, U extends Record<K, T> = Record<K, T>>(
  msgs: U
): U;

/**
 * Define a single message descriptor
 * @param msg - Message descriptor
 * @returns Same message descriptor with preserved type
 */
function defineMessage<T extends MessageDescriptor>(msg: T): T;

import { defineMessages, defineMessage } from "react-intl";

// Define multiple messages
const messages = defineMessages({
  title: {
    id: "app.title",
    defaultMessage: "My Application",
    description: "Main application title"
  },
  subtitle: {
    id: "app.subtitle", 
    defaultMessage: "Welcome to our platform",
    description: "Application subtitle"
  },
  loginButton: {
    id: "login.button",
    defaultMessage: "Sign In"
  }
});

// Define single message
const errorMessage = defineMessage({
  id: "error.general",
  defaultMessage: "An unexpected error occurred",
  description: "Generic error message for unexpected failures"
});

// Use with FormattedMessage
<FormattedMessage {...messages.title} />
<FormattedMessage {...errorMessage} />

/**
 * Component for handling pluralization based on numeric values
 * @param props - Plural options and values for each form
 */
function FormattedPlural(props: FormatPluralOptions & {
  /** Numeric value to determine plural form */
  value: number;
  /** Required fallback for other plural forms */
  other: React.ReactNode;
  /** Content for zero form (exact match) */
  zero?: React.ReactNode;
  /** Content for one form (singular) */
  one?: React.ReactNode;
  /** Content for two form (dual) */
  two?: React.ReactNode;
  /** Content for few form */
  few?: React.ReactNode;
  /** Content for many form */
  many?: React.ReactNode;
  /** Render prop receiving selected plural content */
  children?(value: React.ReactNode): React.ReactElement | null;
}): React.ReactElement;

import { FormattedPlural } from "react-intl";

// Basic pluralization
<FormattedPlural
  value={itemCount}
  one="You have one item"
  other="You have # items"
/>

// Complex pluralization with zero form
<FormattedPlural
  value={messageCount}
  zero="No new messages"
  one="You have one new message"
  other="You have # new messages"
/>

// Pluralization with render prop
<FormattedPlural
  value={userCount}
  one="user"
  other="users"
>
  {(pluralizedText) => (
    <span className="user-count">
      {userCount} {pluralizedText} online
    </span>
  )}
</FormattedPlural>

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

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

// Values can be primitives, React nodes, or rich text functions
type MessageValues = Record<string, 
  | PrimitiveType 
  | React.ReactNode 
  | FormatXMLElementFn<React.ReactNode>
>;

// Link interpolation
<FormattedMessage
  id="privacy"
  defaultMessage="Read our <privacy>privacy policy</privacy> and <terms>terms of service</terms>"
  values={{
    privacy: (chunks) => <a href="/privacy">{chunks}</a>,
    terms: (chunks) => <a href="/terms">{chunks}</a>
  }}
/>

// Styled text interpolation
<FormattedMessage
  id="emphasis"
  defaultMessage="This is <bold>very important</bold> information"
  values={{
    bold: (chunks) => <strong className="highlight">{chunks}</strong>
  }}
/>

// Complex nested interpolation
<FormattedMessage
  id="welcome"
  defaultMessage="Welcome <user>{username}</user>, you have <count>{messageCount, plural, one {# message} other {# messages}}</count>"
  values={{
    username: currentUser.name,
    messageCount: unreadCount,
    user: (chunks) => <span className="username">{chunks}</span>,
    count: (chunks) => <span className="badge">{chunks}</span>
  }}
/>

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

// Error handling for message formatting
class MessageFormatError extends ReactIntlError {
  constructor(message: string, locale?: string, descriptor?: MessageDescriptor);
}