tessl/npm-lingui--core

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@lingui/core

Name: tessl/npm-lingui--core
Author: tessl

@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;