Announcing Lingui 5.0

Today we are pleased to announce the release of Lingui 5.0! 🚀

This release is a major milestone for the project and includes a number of new features, improvements and bug fixes. In this post, we'll highlight some of the major changes in this release.

In line with the principles of Semantic Versioning, this release contains breaking changes that we have thoroughly documented in the v5 upgrade guide.

What is Lingui?

Lingui is a powerful and flexible internationalization (i18n) and localization (l10n) library for JavaScript projects. It supports React (including RSC and React Native), Vanilla JS, Node.js, Vue.js and frameworks such as Next.js, Remix, and Svelte.

It provides a set of tools and APIs that make it easy for developers to create multilingual applications.

Table of Contents

• Progress Highlights
  • React Server Components (RSC) Support
  • ESLint Plugin
  • Metro Transformer
• What's New in 5.0?
  • React and JS Macros Were Split to Separate Packages
  • Whitespace Handling Changes
  • New useLingui Macro
  • Standalone babel-plugin-lingui-macro
  • Print Placeholder Values for Better Translation Context
  • Other Features
  • Documentation Updates
• Conclusion

Progress Highlights

Lingui has gone through a significant number of changes and milestones since the last major release.

Before we dive into the new features and improvements in 5.0, let's take a look at the growth of the project since the 4.0 release in April 2023.

The project has seen a significant increase in popularity since the last major release. The number of GitHub stars has increased by 28%, and the number of downloads per month has more than doubled for the @lingui/core and @lingui/react packages. The SWC and Vite plugins are also gaining a lot of traction.

(The download numbers are based on the npm-stat.com data)

The journey from Lingui 4.0 includes 25 version updates (minor and patch), more than 100 closed issues, and more than 150 merged pull requests.

Let's now take a quick look at some of the major features and improvements that have been released between 4.0 and 5.0.

React Server Components (RSC) Support

Lingui comes with out-of-the-box support for React Server Components (RSC). This allows you to render translations on the server and client using the same components.

With Lingui, the experience of localizing React is the same in client and server components: Trans and useLingui can be used identically in both worlds, even though internally there are two implementations.

tip

Lingui is fully compatible with the recently released Next.js 15 with the Turbopack Dev bundler.

📖 Read more in the Lingui with React Server Components tutorial.

ESLint Plugin

The new ESLint Plugin is gaining popularity among developers. It helps catch common usage errors and enforce best practices when working with Lingui.

It's fully compatible with the latest ESLint versions and supports both the new ESLint Flat configuration (eslint.config.js) and the legacy configuration .eslintrc format. There is also a set of recommended rules that you can use to get started quickly.

📖 See the Official repository for more details.

Released in September 2023, the plugin now has over 100k downloads per month.

Metro Transformer

Just recently, we released a new Metro Transformer for React Native projects. It allows you to import .po files directly, instead of running lingui compile and importing the resulting JavaScript (or TypeScript) files.

This is a great addition to the Lingui ecosystem and simplifies the workflow for React Native developers.

📖 See the @lingui/metro-transformer reference for more details.

What's New in 5.0?

Lingui 5.0 includes over 50 merged pull requests, bringing new features, improvements, bug fixes, and documentation updates. Here are some of the key highlights of this release.

React and JS Macros Were Split to Separate Packages

In Lingui 5.0, we split the React and JS macros into separate packages to make it easier to use Lingui in any JavaScript project.

The main motivation behind this change was to reduce the package size for projects that don't use React and to prepare for future improvements, especially the Vue.js integration.

The @lingui/macro package has been split into two separate entry points from the existing packages:

• @lingui/react/macro - for React (JSX) macros.
• @lingui/core/macro - for Core (JS) macros.

This allows developers to use Lingui macros in any JavaScript project without having to download the entire React package.

Whitespace Handling Changes

Whitespace handling has been improved to provide greater consistency and meet developer expectations. Previously, Lingui's regex-based whitespace normalization in JSX macros sometimes produced unexpected results. With Lingui 5.0, Lingui now uses JSX-specific whitespace rules, producing predictable, clean output for React (JSX) macros.

For JS macros, whitespace normalization has been completely removed based on developer feedback, leaving whitespace intact in expressions - ideal for text that requires special formatting, such as markdown.

This change is breaking, meaning that some auto-generated message IDs may change. This could cause translations to lose their connection to the original message ID. To address this, you can use the translation memory capabilities of your translation management system (TMS) to restore translations for the updated message IDs.

New useLingui Macro

In Lingui 5, we introduced a new useLingui macro that makes it easier to work with non-JSX messages within React components.

Take the following code snippet as an example:

import { t, msg } from "@lingui/macro";
import { useLingui } from "@lingui/react";

function MyComponent() {
  const { i18n, _ } = useLingui();

  const a = t(i18n)`Text`;
  // or
  const b = _(msg`Second Text`);
}

With the new useLingui macro, you can simplify this code to:

import { useLingui } from "@lingui/react/macro";

function MyComponent() {
  const { t } = useLingui();

  const a = t`Text`;
  const b = t`Second Text`;
}

Under the hood, the useLingui macro is transpiled to the runtime useLingui hook.

Standalone babel-plugin-lingui-macro

There are now two ways to use Lingui macros with Babel in your project. You can choose between the babel-macro-plugin and the standalone @lingui/babel-plugin-lingui-macro.

The new plugin offers faster transpiling and additional configuration options.

We recommend replacing babel-macro-plugin with @lingui/babel-plugin-lingui-macro if you have direct access to your Babel configuration and don't use any other macros in your project.

.babelrc

{
  "plugins": [
-    "macros"
+    "@lingui/babel-plugin-lingui-macro"
  ]
}

Print Placeholder Values for Better Translation Context

Context is critical for translators (and AI) to provide accurate translations. This release introduces a new feature that prints placeholder values in PO comments.

If the message contains unnamed placeholders such as {0}, Lingui will print the name of the placeholder variable in the PO comments, giving translators and AI more context about what the placeholder is about.

Consider the following example:

t`Hello ${user.name} ${value}`;

With the new feature enabled, the message in the PO file will include the placeholder values in the comments:

en.po

+ #. placeholder {0}: user.name
msgid "Hello {0} {value}"

This gives the translators more context about the placeholders, which definitely helps in providing accurate translations.

Other Features

Configurable Message Stripping via Babel Options

By default, Lingui strips messages and comments from the production bundle to reduce the bundle size.

It's now possible to configure this feature by setting the stripMessageField option in the Babel configuration:

babel.config.js

module.exports = {
  plugins: [
    "macros",
    {
      lingui: {
        stripMessageField: true,
      },
    },
  ],
};

Setting stripMessageField to true will strip messages and comments from both development and production bundles. Alternatively, set it to false to keep the original messages in both environments.

This helps to align the development and production environments and catch potential issues early in the development process.

Support decoratorAutoAccessors Decorator

Decorators are a proposal for extending JavaScript classes that has been widely adopted by developers in transpiler environments, with widespread interest in standardization.

By default, Lingui supports Typescript, Flow, and JavaScript (Stage 3) syntax. The Decorators proposal is already at Stage 3, and Lingui now supports the decoratorAutoAccessors decorator in the Babel plugin.

📖 Read more about the supported syntax in the Custom Extractor reference.

Dependency Tree Extractor Improvements

The Dependency Tree Extractor has been improved to provide better performance and more accurate results.

• Use the newer esbuild version and refactor the codebase to apply the Lingui macro to each file as an esbuild plugin.
• Change the way how the external dependencies are excluded from the extraction process.
• Use the TSX loader instead of JSX.
• Improved Tree Shaking support.

This feature is still in the experimental stage, but we are working to make it more stable and reliable.

Multiple Locales Support in lingui extract

Now you can extract messages for multiple locales in a single command.

lingui extract --locale de --locale fr

Quality of Life Update for Windows Users

All Lingui CLI commands now work without problems on Windows, as well as the Webpack Loader and the Vite plugin. We've fixed all known bugs and improved the overall experience for Windows users.

New defineConfig Method

We've introduced a new defineConfig method that allows you to define configuration options for the Lingui CLI in a more flexible and convenient way:

lingui.config.{js,ts}

import { defineConfig } from "@lingui/cli";

export default defineConfig({
  sourceLocale: "en",
  locales: ["cs", "en"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
});

This method provides a more structured and type-safe way to define configuration options for the Lingui CLI, and it's quite common in modern JavaScript tools.

Documentation Updates

In addition to the new features and improvements, we've also made significant updates to the documentation to make it more comprehensive and user-friendly:

• All the documentation pages have been reviewed, improved and updated to reflect the latest changes in Lingui 5.0.
• The structure of the documentation has been reorganized to make it easier to navigate and find the information you need.
• The installation instructions have been dramatically improved to provide a simpler and clearer process for getting started with Lingui.
• The Tutorials section is now more detailed and clearer to help you quickly get up and running with Lingui for a specific use case.
• Outdated and duplicate content has been removed to reduce confusion.
• And many other small improvements and updates to make the documentation more helpful and informative.

Conclusion

Lingui 5.0 is a significant milestone for the project, bringing a number of new features, improvements, and bug fixes. We hope you enjoy using Lingui 5.0 and look forward to hearing your feedback!

This release wouldn't have been possible without the help of our amazing community. Thank you to everyone who contributed to this release!

Links

• Migration Guide
• Full Changelog