DOCSEARCHbyAlgolia
Submit Docs

LinguiJS Documentation

repository·main·Indexed 26 days ago

https://github.com/lingui/js-lingui

A lightweight, automated internationalization (i18n) framework for JavaScript using an extract-and-compile workflow. It supports ICU MessageFormat and provides integrations for React, SolidJS, React Native, Astro, and Svelte. The ecosystem includes @lingui/core for essential functionality, @lingui/cli for managing catalogs, and various plugins for Babel, Vite, and Webpack to optimize translation extraction and compilation.

Tokens
73.9K
Snippets
237
Records
442
Agent score
90%

What's inside LinguiJS

  1. Overview of Lingui

    main

    Lingui is an internationalization (i18n) and localization (l10n) library for JavaScript projects (React, Vue.js, Node.js, Next.js, etc.). It uses ICU MessageFormat under the hood and provides tools to manage translation files centrally.

    Key characteristics:

    • Universal: Works with Vanilla JS, React, Vue, etc.
    • Rich-text support: Allows using React components within localized messages.
    • Tooling: Includes a CLI for message extraction, validation, and verification.
    • Unopinionated: Supports both message keys and auto-generated messages, and various formats like PO, JSON, and CSV.
    • Lightweight: @lingui/core is ~1.5 kB gzipped; @lingui/react is ~1.3 kB gzipped.

  2. Overview of LinguiJS

    main
    LinguiJS is a lightweight (approx. 2 kb), automated, and optimized internationalization (i18n) framework for JavaScript. It uses the ICU MessageFormat under the hood and supports a variety of environments including React (including RSC), SolidJS, React Native, Astro, and Svelte. It follows an extract-and-compile workflow where messages are extracted from source code and compiled into optimized catalogs.

  3. Overview of Lingui features and capabilities

    main

    Lingui is a flexible internationalization (i18n) solution for JavaScript applications. Key features include:

    • Universal Support: Works with Vanilla JS, React, Vue.js, Next.js, Node.js, and more.
    • Rich-text Support: Allows using React components within localized messages using JSX-like syntax.
    • Powerful Tooling:
      • Lingui CLI: Manages the entire workflow, including message extraction and validation.
      • ESLint plugin: Detects common Lingui usage errors.
      • Vite plugin: Compiles Lingui catalogs on the fly and provides Vite-specific configuration.
    • Customization:
      • Supports both message keys and auto-generated messages.
      • Supports multiple catalog formats including PO, JSON, and CSV.
      • Extensible via Custom Extractors and Custom Formatters.

  5. Understand Lingui Core Macros

    main

    Core JS macros are used in any JavaScript context (including outside JSX). They transform tagged template literals or objects into a MessageDescriptor wrapped in an i18n._() call.

    At runtime, only the id and values properties of the descriptor are used; message, comment, and context are stripped from production code to optimize size, but are used by the extractor to build the message catalog.

    A MessageDescriptor follows this structure:

    type MessageDescriptor = {
  id: string;
  message?: string;
  values?: Record<string, any>;
  comment?: string;
};
    import { t } from "@lingui/core/macro";
t`Attachment ${name} saved`;

// Transforms into:
import { i18n } from "@lingui/core";
i18n._(
  /** i18n */ {
    id: "nwR43V",
    message: "Attachment {name} saved",
    values: { name },
  }
);

  7. Use @lingui/format-json to read and write message catalogs

    main

    @lingui/format-json is a utility package used to read and write LinguiJS message catalogs in JSON format. It is part of the LinguiJS ecosystem.

    For detailed implementation details and API references, consult the official LinguiJS documentation.

  8. Lingui package ecosystem overview

    main

    Lingui is composed of several specialized packages depending on your environment:

    • @lingui/core: The framework-agnostic layer. It handles loading compiled catalogs, tracking the active locale, and formatting messages using ICU MessageFormat. Works in browsers, Node.js, or scripts.
    • @lingui/react: Adds components and hooks for React applications, including support for React Server Components.
    • @lingui/solid: Provides native bindings for SolidJS with reactive Trans components and a useLingui hook.
    • @lingui/cli: Tooling for extracting, compiling, and validating messages.
    • @lingui/vite-plugin: Compiles catalogs on the fly during development/build.
    • @lingui/eslint-plugin: Helps catch common i18n usage errors during development.
    • lingui/skills: An optional package to help AI assistants understand Lingui patterns for better automated translations.

  10. Use @lingui/vite-plugin for on-the-fly catalog compilation

    main
    The @lingui/vite-plugin is a Vite plugin that compiles Lingui catalogs on the fly during development and build. When using this plugin, you do not need to manually run the lingui compile command, as the plugin handles the compilation process automatically within the Vite pipeline.