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.

📖 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.

{
  "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:

+ #. 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:

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:

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

The new @lingui/metro-transformer package brings a more streamlined way to consume translations from .po files in Expo and React Native.

It can be used in apps across all platforms supported by React Native (Android, iOS, web and more!) - the only pre-requisite is that you use Metro bundler to bundle your app.

Previously, React Native developers would need to follow the two-step process of extracting translations into a .po file (with lingui extract), and then compiling translated po files into JS/TS files (with lingui compile) for production.

Good news! By setting up the metro-transformer, you now don't need to perform the second step - it's performed for you during bundling!

The @lingui/metro-transformer package is available as of version 4.12.0. Please let us know if you encounter any issues!

Getting Started​

The TL;DR is: install @lingui/metro-transformer, update metro.config.js and you're ready to go!

For more details - see the official docs.

Exciting Future for Lingui​

In case you missed it, Lingui now offers a truly universal support for React — you can use the same syntax for React on the web, React Native, and even in React Server Components (RSC), making it a consistent solution across platforms and environments.

Additionally, keep an eye on Lingui v5 which is packed with new features and bug fixes, and a stable release is just behind the corner. In fact, you can already try v5 with a pre-release version - see the latest releases on GitHub!

As always, thank you to the community for trusting Lingui!

We're thrilled to announce that the Lingui repository has reached an important milestone - 4,000 stars! This achievement is a testament to the growing popularity of Lingui as a powerful and flexible internationalization solution for global products.

Lingui has been gaining traction in the JS community due to its several key advantages​

• Universal - use it everywhere: Vanilla JS, React, Vue.js, Next.js, Node.js, etc.

• Full rich-text support - use React components within localized messages without restriction. Writing rich-text messages is as easy as writing JSX.

• Powerful tooling - manage the entire intl workflow with the Lingui CLI. It extracts messages from source code, validates messages coming from translators, and many more. Use the ESLint plugin to find common Lingui usage errors in your code. In addition, for Vite users, we have the Vite plugin which compiles Lingui catalogs on the fly and provides additional configuration needed for Vite.

• Customization - integrate Lingui with your existing workflow. It supports both message keys and auto-generated messages. Translations can be stored in a variety of file formats including PO, JSON, and CSV. For more advanced usage, there is a possibility to create a Custom Extractor or Custom Formatter for your project.

Here are some of the ways that Lingui is being used by companies around the world​

• Ansible - an open source community project sponsored by Red Hat, it's the simplest way to automate IT.
• Metamask - a crypto wallet & gateway to blockchain apps.
• Uniswap - an open source interfaces for the Uniswap protocol.

These are just a few examples of the many companies that use Lingui to power their internationalization efforts. We're confident that Lingui will continue to grow in popularity as more and more companies recognize its value.

Thanks to the community​

This milestone wouldn't have happened without all of you, so we want to thank the awesome community for being with Lingui all the way along. Join the Lingui community and help us make Lingui even better!

What is Lingui exactly?​

Lingui is a powerful and flexible internationalization (i18n) and localization (l10n) library for JavaScript projects, including React, Vue.js, Node.js, Next.js, Angular, and more. It provides a set of tools and APIs that make it easy for developers to create multilingual applications.

One of the key benefits of Lingui is that it simplifies the process of managing translations by providing a centralized way to store and manage translation files.

Key features​

• Clean and readable - keep your code clean and readable, while the library uses the battle-tested and powerful ICU MessageFormat under the hood.
• Universal - use it everywhere: Vanilla JS, React, Vue.js, Next.js, Node.js, etc.
• Full rich-text support - use React components within localized messages without restriction. Writing rich-text messages is as easy as writing JSX.
• Powerful tooling - manage the entire intl workflow with Lingui CLI. It extracts messages from source code, validates messages coming from translators, and verifies that all messages are translated before shipping to production.
• Unopinionated - integrate Lingui with your existing workflow. It supports both message keys and auto-generated messages. Translations can be stored in a variety of file formats including PO, JSON, and CSV.
• Lightweight and optimized - core library is only 1.5 kB gzipped, React components are additional 1.3 kB gzipped.
• Active community.

What's new in 4.0?​

This version is packed with tons of new features, improvements and fixes that will make internationalizing your JavaScript projects much easier!

The codebase has also been significantly refactored and updated. As a result, Lingui has become much more stable, lightweight, reliable, and less fragile.

Extractors​

The big change in v4.0 is in the extractor internals. It is now less fragile and doesn't depend on host project settings. Also, the extractor now supports TypeScript out of the box.

Hash-based message IDs + Context​

The previous implementation had a flaw: there is an original message in the bundle at least 2 times + 1 translation.

For the line "Hello world", it will exist in the source as an ID in the i18n call, then as a key in the message catalog, and then as the translation itself. Strings can be very long, not just a few words, so this may add more kB to the bundle.

A much better option is to generate a "stable" ID based on the msg + context as a fixed length hash.

We've also added the ability to specify a context for the message. For more details, see the Providing a context for a message.

The context feature affects the message ID generation and adds the msgctxt parameter in case of the PO catalog format extraction.

Custom Extractors​

The extractor refactoring has allowed the creation of Custom Extractors. If your project does not work well with Lingui's extractor, you can easily write your own extractor implementation. This might be the case if you are using some experimental features (stage0 - stage2) or frameworks with custom syntax like Vue.js or Svelte. See the Custom Extractor guide for more details.

Flow Syntax support​

Lingui supports Flow by default. If your project uses Flow, you need to explicitly enable support in the extractor.

Custom Formatters​

If your project requires a special format or handling logic, you can write your own format implementation.

Formatter is a simple object with 2 main functions parse and serialize, which should take Lingui catalog and serialize it to string and vice versa.

You don't need to create a separate package for formatter, you can write it directly in lingui.config.{ts,js}.

The built-in Lingui formatters have been extracted into a separate packages:

• @lingui/format-po (enabled by default)
• @lingui/format-po-gettext
• @lingui/format-json
• @lingui/format-csv

See the Custom Formatter guide for more details.

Experimental dependency tree crawling​

While the standard glob-based extraction process is effective for most projects, multipage (MPA) frameworks such as NextJS pose a problem because the glob-based approach creates a catalog consisting of all messages from all pages.

This means that the entire catalog must be loaded for each page/navigation, which results in loading messages that are not used on that page.

To address this issue, a new experimental extractor was introduced in version 4. This extractor uses the dependency tree of files, rather than just a glob pattern, to crawl imports and discover files more accurately.

By doing so, it creates a more optimized catalog that only contains the messages needed for each page.

The catalogs would still contain duplicate messages for common components, but it would be much better than the current approach.

Improved React support​

Lingui v4.0 includes a bunch of improvements to its React support, making it even easier for developers to implement internationalization and localization in their React applications. Visit the Internationalization of React apps and Common i18n patterns in React tutorials to learn the most common patterns for internationalizing React applications.

Plugins​

During the development of Lingui v4.0, we have created two new plugins to improve the integration of Lingui with other tools and frameworks. These plugins are the SWC Plugin and the Vite Plugin.

Both of these plugins are designed to make it easier for developers to use Lingui with other modern tools and frameworks. We are excited to see how developers will use these plugins to improve their localization workflows and make their applications more accessible to a global audience.

More examples​

As part of Lingui v4.0, we've also created new example projects that show how Lingui can be integrated into different types of applications. These projects demonstrate best practices for integrating Lingui with popular frameworks and libraries, including nextjs-babel, nextjs-swc, vite-project-react-babel, nextjs-13 as well as the existing ones create-react-app and js were updated.

These example projects are a great resource for developers who are new to Lingui and want to see how it can be used in practice. They provide a clear starting point for building a multilingual application, and can help developers avoid common pitfalls and obstacles. We hope that these examples will inspire developers to try Lingui in their own projects and make their applications accessible to a wider audience.

Other features​

Lingui v4 comes with a long list of useful features:

• extractor: support TS experimental decorators
• macro: support tagged templates in defineMessage + short alias
• macro: allow passing any expression as custom i18n instance
• macro: support JSX macro inside conditional expressions
• macro: support renamed identifiers in macro
• core (Experimental): new core API for Node/JS usage without macros
• core: support extracting from all forms of i18n._ / i18n.t calls
• extractor: respect sourcemaps

Visit the Release notes to see all the updates.

Credits​

We would like to say thanks to all the contributors who made this release possible. It represents the hard work and dedication of a global community of developers who have contributed their time, expertise, and support.

We are also grateful to the entire community who provided valuable feedback, bug reports, and feature requests. Your contributions have helped shape and make Lingui better.

See more​

• Migration guide from 3.x to 4.x
• Lingui 4.0 full changelog