Formatting Utilities

/**
 * Format a date using specified locales and options
 * @param locales - Locale(s) to use for formatting
 * @param value - Date to format (string or Date object)
 * @param format - Format options or predefined size
 * @returns Formatted date string
 */
function date(
  locales: Locales,
  value: string | Date,
  format?: Intl.DateTimeFormatOptions | DateTimeFormatSize
): string;

/**
 * Format a time using specified locales and options
 * @param locales - Locale(s) to use for formatting
 * @param value - Date/time to format (string or Date object)
 * @param format - Format options or predefined size
 * @returns Formatted time string
 */
function time(
  locales: Locales,
  value: string | Date,
  format?: Intl.DateTimeFormatOptions | DateTimeFormatSize
): string;

type DateTimeFormatSize = "short" | "default" | "long" | "full";
type Locales = string | string[];

import { formats } from "@lingui/core";

const now = new Date();
const dateString = "2023-12-25T10:30:00Z";

// Basic date formatting
const shortDate = formats.date("en-US", now, "short");
// "12/25/23"

const longDate = formats.date("fr-FR", now, "long"); 
// "25 décembre 2023"

// Custom date formatting
const customDate = formats.date("de-DE", now, {
  weekday: "long",
  year: "numeric", 
  month: "long",
  day: "numeric"
});
// "Montag, 25. Dezember 2023"

// Time formatting
const shortTime = formats.time("en-US", now, "short");
// "10:30 AM"

const fullTime = formats.time("ja-JP", now, "full");
// "10時30分00秒 GMT"

// Multiple locale fallback
const multiLocale = formats.date(["pt-BR", "pt", "en"], now, "default");

/**
 * Format a number using specified locales and options
 * @param locales - Locale(s) to use for formatting
 * @param value - Number to format
 * @param format - Intl.NumberFormat options
 * @returns Formatted number string
 */
function number(
  locales: Locales,
  value: number,
  format?: Intl.NumberFormatOptions
): string;

import { formats } from "@lingui/core";

const price = 1234.56;
const percentage = 0.75;

// Basic number formatting
const basic = formats.number("en-US", price);
// "1,234.56"

const german = formats.number("de-DE", price);
// "1.234,56"

// Currency formatting
const usd = formats.number("en-US", price, {
  style: "currency",
  currency: "USD"
});
// "$1,234.56"

const euro = formats.number("fr-FR", price, {
  style: "currency", 
  currency: "EUR"
});
// "1 234,56 €"

// Percentage formatting
const percent = formats.number("en-US", percentage, {
  style: "percent"
});
// "75%"

// Scientific notation
const scientific = formats.number("en-US", 123456789, {
  notation: "scientific"
});
// "1.235E8"

// Custom precision
const precise = formats.number("en-US", price, {
  minimumFractionDigits: 3,
  maximumFractionDigits: 3
});
// "1,234.560"

/**
 * Format plurals using locale-specific plural rules
 * @param locales - Locale(s) to determine plural rules
 * @param ordinal - Whether to use ordinal (1st, 2nd) or cardinal (1, 2) rules
 * @param value - Numeric value to determine plural form
 * @param options - Plural form options with offset and rules
 * @returns Selected plural form string
 */
function plural(
  locales: Locales,
  ordinal: boolean,
  value: number,
  options: PluralOptions
): string;

interface PluralOptions {
  /** Offset for plural calculation (default: 0) */
  offset: number;
  /** Default/fallback form (required) */
  other: string;
  /** Specific LDML plural rules */
  [key: string]: Intl.LDMLPluralRule;
}

import { formats } from "@lingui/core";

// Cardinal plurals (1, 2, 3...)
const cardinalEn = formats.plural("en", false, 1, {
  one: "1 item",
  other: "# items"
});
// "1 item"

const cardinalPl = formats.plural("pl", false, 2, {
  one: "1 przedmiot",
  few: "# przedmioty", 
  many: "# przedmiotów",
  other: "# przedmiotów"
});
// "2 przedmioty"

// Ordinal plurals (1st, 2nd, 3rd...)  
const ordinalEn = formats.plural("en", true, 21, {
  one: "#st",
  two: "#nd", 
  few: "#rd",
  other: "#th"
});
// "21st"

// With offset (useful for "Alice and 3 others")
const withOffset = formats.plural("en", false, 4, {
  offset: 1,
  "0": "Nobody else",
  "1": "Alice only",
  one: "Alice and 1 other",
  other: "Alice and # others"
});
// "Alice and 3 others"

// Exact matches override plural rules
const exactMatch = formats.plural("en", false, 0, {
  "0": "No items",
  one: "1 item",
  other: "# items"
});
// "No items"

/**
 * Default locale constant used as fallback
 */
const defaultLocale: "en";

import { formats } from "@lingui/core";

console.log(formats.defaultLocale); // "en"

// Default locale is automatically added to locale arrays
const result = formats.date(["fr-CA", "fr"], new Date());
// Equivalent to: formats.date(["fr-CA", "fr", "en"], new Date())

// Internal caching mechanism (not exposed)
// Multiple calls with same parameters reuse cached formatters
const formatter1 = formats.number("en-US", 123, { style: "currency", currency: "USD" });
const formatter2 = formats.number("en-US", 456, { style: "currency", currency: "USD" });
// Second call reuses the cached Intl.NumberFormat instance

import { setupI18n } from "@lingui/core";

const i18n = setupI18n({ locale: "en-US" });

// I18n method (uses current locale automatically)
const price1 = i18n.number(1234.56, { style: "currency", currency: "USD" });

// Direct formatting utility (explicit locale)
const price2 = formats.number("en-US", 1234.56, { style: "currency", currency: "USD" });

// Both produce the same result: "$1,234.56"