I18n Interface

/**
 * Creates a new I18n instance with optional configuration
 * @param params - Configuration options for the I18n instance
 * @returns New I18n instance
 */
function setupI18n(params?: I18nProps): I18n;

interface I18nProps {
  /** Initial locale to activate */
  locale?: Locale;
  /** List of fallback locales for formatting */
  locales?: Locales;
  /** Message catalogs for all locales */
  messages?: AllMessages;
  /** @deprecated Locale data (plurals are now automatic) */
  localeData?: AllLocaleData;
  /** Missing message handler - string or function */
  missing?: string | ((locale: string, id: string) => string);
}

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

// Basic setup
const i18n = setupI18n({
  locale: "en",
  messages: {
    en: { "Hello": "Hello" },
    es: { "Hello": "Hola" }
  }
});

// Setup with missing message handler
const i18n = setupI18n({
  locale: "en",
  missing: (locale, id) => `Missing translation: ${id} (${locale})`
});

class I18n extends EventEmitter<Events> {
  constructor(params: I18nProps);
  
  /** Current active locale */
  readonly locale: Locale;
  /** Active locales list for formatting fallbacks */
  readonly locales?: Locales;
  /** Messages for the current locale */
  readonly messages: Messages;
  /** @deprecated Locale data (automatic plurals) */
  readonly localeData: LocaleData;
}

type Events = {
  change: () => void;
  missing: (event: MissingMessageEvent) => void;
};

/**
 * Translate a message descriptor
 * @param descriptor - Message descriptor with id, values, etc.
 * @returns Translated and formatted message
 */
_(descriptor: MessageDescriptor): string;

/**
 * Translate a message by ID with optional values and options
 * @param id - Message ID to translate
 * @param values - Placeholder values for interpolation
 * @param options - Translation options including format overrides
 * @returns Translated and formatted message
 */
_(id: string, values?: Values, options?: MessageOptions): string;

/**
 * Alias for the _ method
 */
t: I18n["_"];

// Using message descriptors
const msg = i18n._({
  id: "welcome",
  values: { name: "Alice" },
  message: "Welcome {name}!"
});

// Using string ID
const greeting = i18n._("hello", { name: "Bob" });

// Using t alias
const farewell = i18n.t("goodbye");

// With formatting options
const price = i18n._("price", { amount: 99.99 }, {
  formats: { amount: { style: "currency", currency: "USD" } }
});

/**
 * Load messages for all locales
 * @param allMessages - Object mapping locales to message catalogs
 */
load(allMessages: AllMessages): void;

/**
 * Load messages for a specific locale
 * @param locale - Target locale
 * @param messages - Message catalog for the locale
 */
load(locale: Locale, messages: Messages): void;

/**
 * Load messages and activate locale in one operation
 * @param options - Locale, locales, and messages to load and activate
 */
loadAndActivate(options: LoadAndActivateOptions): void;

interface LoadAndActivateOptions {
  /** Locale to activate */
  locale: Locale;
  /** Optional fallback locales */
  locales?: Locales;
  /** Compiled message catalog */
  messages: Messages;
}

// Load all messages at once
i18n.load({
  en: { "hello": "Hello", "goodbye": "Goodbye" },
  es: { "hello": "Hola", "goodbye": "Adiós" },
  fr: { "hello": "Bonjour", "goodbye": "Au revoir" }
});

// Load messages for specific locale
i18n.load("de", { "hello": "Hallo", "goodbye": "Auf Wiedersehen" });

// Load and activate in one call
i18n.loadAndActivate({
  locale: "it",
  messages: { "hello": "Ciao", "goodbye": "Arrivederci" }
});

/**
 * Activate a locale for translations
 * @param locale - Locale to activate
 * @param locales - Optional fallback locales for formatting
 */
activate(locale: Locale, locales?: Locales): void;

// Activate single locale
i18n.activate("fr");

// Activate with fallbacks
i18n.activate("fr-CA", ["fr-CA", "fr", "en"]);

/**
 * Set a message compiler for runtime compilation
 * @param compiler - Function to compile ICU messages
 * @returns I18n instance for chaining
 */
setMessagesCompiler(compiler: MessageCompiler): I18n;

type MessageCompiler = (message: string) => CompiledMessage;

import { compileMessage } from "@lingui/message-utils/compileMessage";

// Enable runtime compilation (typically for development)
i18n.setMessagesCompiler(compileMessage);

/**
 * @deprecated Load locale data for pluralization (no longer needed)
 * @param allLocaleData - All locale data object
 */
loadLocaleData(allLocaleData: AllLocaleData): void;

/**
 * @deprecated Load locale data for a specific locale (no longer needed)  
 * @param locale - Target locale
 * @param localeData - Locale-specific data
 */
loadLocaleData(locale: Locale, localeData: LocaleData): void;

/**
 * Format a date using current locale(s)
 * @param value - Date to format (string or Date object)
 * @param format - Intl.DateTimeFormat options
 * @returns Formatted date string
 */
date(value: string | Date, format?: Intl.DateTimeFormatOptions): string;

/**
 * Format a number using current locale(s)
 * @param value - Number to format
 * @param format - Intl.NumberFormat options
 * @returns Formatted number string
 */
number(value: number, format?: Intl.NumberFormatOptions): string;

// Format dates
const shortDate = i18n.date(new Date(), { dateStyle: "short" });
const longDate = i18n.date("2023-12-25", { 
  weekday: "long", 
  year: "numeric", 
  month: "long", 
  day: "numeric" 
});

// Format numbers
const currency = i18n.number(1234.56, { 
  style: "currency", 
  currency: "EUR" 
});
const percentage = i18n.number(0.85, { 
  style: "percent" 
});

// Inherited from EventEmitter
on(event: "change", listener: () => void): () => void;
on(event: "missing", listener: (event: MissingMessageEvent) => void): () => void;
removeListener(event: "change" | "missing", listener: Function): void;
emit(event: "change" | "missing", ...args: any[]): void;

// Listen for locale changes
const unsubscribe = i18n.on("change", () => {
  console.log("Locale changed to:", i18n.locale);
  // Update UI, rerender components, etc.
});

// Listen for missing translations
i18n.on("missing", ({ locale, id }) => {
  console.warn(`Missing translation for "${id}" in locale "${locale}"`);
  // Log to analytics, show developer warnings, etc.
});

// Cleanup listener
unsubscribe();

/**
 * Default I18n instance created with setupI18n()
 * Ready to use but requires locale activation and message loading
 */
const i18n: I18n;

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

// Use the default instance
i18n.load("en", { "hello": "Hello world!" });
i18n.activate("en");
const message = i18n._("hello");