or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

formatting.mdi18n.mdindex.mdmacros.md
tile.json

tessl/npm-lingui--core

Essential internationalization library providing core functionality for JavaScript applications requiring multilingual support with ICU MessageFormat.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@lingui/core@5.4.x

To install, run

npx @tessl/cli install tessl/npm-lingui--core@5.4.0

index.mddocs/

@lingui/core

@lingui/core is the essential internationalization (i18n) library that provides core functionality for JavaScript applications requiring multilingual support. It offers comprehensive API for message formatting using the ICU MessageFormat standard, enabling developers to handle complex pluralization, number formatting, date formatting, and context-sensitive translations with a lightweight runtime and zero dependencies.

Package Information

  • Package Name: @lingui/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @lingui/core

Core Imports

import { setupI18n, I18n, i18n } from "@lingui/core";
import { formats } from "@lingui/core";

For CommonJS:

const { setupI18n, I18n, i18n, formats } = require("@lingui/core");

Macro imports (compile-time):

import { t, plural, select, defineMessage, msg } from "@lingui/core/macro";

Basic Usage

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

// Create and configure I18n instance
const i18n = setupI18n({
  locale: "en",
  messages: {
    en: {
      "Hello {name}": "Hello {name}",
      "greeting": "Welcome!"
    },
    es: {
      "Hello {name}": "Hola {name}",
      "greeting": "¡Bienvenido!"
    }
  }
});

// Activate a locale
i18n.activate("es");

// Translate messages
const greeting = i18n._("greeting"); // "¡Bienvenido!"
const welcome = i18n._("Hello {name}", { name: "María" }); // "Hola María"

// Format numbers and dates
const price = i18n.number(1234.56, { style: "currency", currency: "EUR" });
const today = i18n.date(new Date(), { dateStyle: "medium" });

Architecture

@lingui/core is built around several key components:

  • I18n Class: Central internationalization manager providing translation, formatting, and locale management
  • Macro System: Compile-time translation helpers for optimal performance and developer experience
  • Message Compilation: ICU MessageFormat parsing and compilation for efficient runtime execution
  • Event System: Reactive locale changes and missing message handling
  • Formatting Engine: Intl API-based number, date, and plural formatting with memoization
  • Type Safety: Full TypeScript integration with comprehensive type definitions

Capabilities

Core I18n Interface

Central internationalization class providing translation methods, locale management, and message loading. The primary interface for all i18n operations.

function setupI18n(params?: I18nProps): I18n;

class I18n extends EventEmitter<Events> {
  constructor(params: I18nProps);
  readonly locale: Locale;
  readonly locales?: Locales;
  readonly messages: Messages;
  
  _(descriptor: MessageDescriptor): string;
  _(id: string, values?: Values, options?: MessageOptions): string;
  t: I18n["_"];
  
  load(allMessages: AllMessages): void;
  load(locale: Locale, messages: Messages): void;
  loadAndActivate(options: LoadAndActivateOptions): void;
  activate(locale: Locale, locales?: Locales): void;
  
  date(value: string | Date, format?: Intl.DateTimeFormatOptions): string;
  number(value: number, format?: Intl.NumberFormatOptions): string;
}

const i18n: I18n;

I18n Interface

Macro Functions

Compile-time translation macros that optimize messages during build time for maximum runtime performance. These functions are transformed by Babel during compilation.

function t(descriptor: MacroMessageDescriptor): string;
function t(literals: TemplateStringsArray, ...placeholders: MessagePlaceholder[]): string;
function t(i18n: I18n): {
  (literals: TemplateStringsArray, ...placeholders: any[]): string;
  (descriptor: MacroMessageDescriptor): string;
};

function plural(
  value: number | string | LabeledExpression<number | string>,
  options: ChoiceOptions
): string;

function selectOrdinal(
  value: number | string | LabeledExpression<number | string>,
  options: ChoiceOptions
): string;

function select(
  value: string | LabeledExpression<string>,
  choices: SelectOptions
): string;

function defineMessage(descriptor: MacroMessageDescriptor): MessageDescriptor;
function defineMessage(literals: TemplateStringsArray, ...placeholders: MessagePlaceholder[]): MessageDescriptor;

const msg: typeof defineMessage;

function ph(def: LabeledExpression<string | number>): string;

Macro Functions

Formatting Utilities

Standalone formatting functions for dates, times, numbers, and plurals. These utilities provide direct access to Intl API-based formatting with locale support and memoization.

declare const formats: {
  date(locales: Locales, value: string | Date, format?: Intl.DateTimeFormatOptions | DateTimeFormatSize): string;
  time(locales: Locales, value: string | Date, format?: Intl.DateTimeFormatOptions | DateTimeFormatSize): string;
  number(locales: Locales, value: number, format?: Intl.NumberFormatOptions): string;
  plural(locales: Locales, ordinal: boolean, value: number, options: PluralOptions): string;
  defaultLocale: string;
};

type DateTimeFormatSize = "short" | "default" | "long" | "full";

Formatting Utilities

Types

Core types exported from the main @lingui/core package:

type Locale = string;
type Locales = Locale | Locale[];

interface MessageDescriptor {
  id: string;
  comment?: string;
  message?: string;
  values?: Record<string, unknown>;
}

interface MessageOptions {
  message?: string;
  formats?: Formats;
  comment?: string;
}

type Messages = Record<string, UncompiledMessage | CompiledMessage>;
type AllMessages = Record<Locale, Messages>;

/** @deprecated Plurals automatically used from Intl.PluralRules */
interface LocaleData {
  plurals?: (n: number, ordinal?: boolean) => ReturnType<Intl.PluralRules["select"]>;
}

/** @deprecated Plurals automatically used from Intl.PluralRules */
type AllLocaleData = Record<Locale, LocaleData>;

type Values = Record<string, unknown>;
type Formats = Record<string, Intl.DateTimeFormatOptions | Intl.NumberFormatOptions>;

type UncompiledMessage = string;
type CompiledMessage = any; // From @lingui/message-utils

interface MissingMessageEvent {
  locale: Locale;
  id: string;
}

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