lingui-best-practices

Implement internationalization in React and JavaScript applications using Lingui macros and catalogs.

3|Updated Apr 20, 2026
One-click install
npx skills add https://github.com/langgenius/due-date-hq-jwl --skill lingui-best-practices-langgenius
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: lingui-best-practices
Source: https://github.com/langgenius/due-date-hq-jwl/tree/main/.agents/skills/lingui-best-practices
Command: npx skills add https://github.com/langgenius/due-date-hq-jwl --skill lingui-best-practices-langgenius

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Adding internationalization to a React or JavaScript app involves many subtle pitfalls: macros that fail at module level, plural forms that behave unexpectedly, memoization that breaks on locale change, and catalogs that drift out of sync with source code. This Skill provides correct patterns for the full Lingui workflow so translations extract, compile, and render reliably. ## Core Features & Use Cases - Macro usage guidance: Correct patterns for Trans, t, msg, Plural, Select, and useLingui, including when to use each and common mistakes to avoid. - Workflow coverage: Setup with I18nProvider, message extraction, catalog compilation, dynamic locale switching, and lingui.config.js catalog patterns. - Repository-specific rules: Enforces project constraints such as running i18n checks after changes, never leaving empty msgstr values, and translating interpolated branches. - Use Case: When adding a new UI label with a pluralized count, use this Skill to write the Plural macro correctly, extract messages, translate the zh-CN catalog, and verify extraction reports zero missing translations. ## Quick Start Ask the assistant to add a translated welcome message with a pluralized notification count to a React component using Lingui macros.

Frequently Asked Questions about lingui-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I translate JSX text in React with Lingui?

Use the Trans macro imported from @lingui/react/macro to wrap JSX content. For strings outside JSX such as attributes or alerts, use the t macro from useLingui. Macros compile at build time, reducing bundle size compared to runtime components.

How do I handle pluralization in Lingui?

Use the Plural macro with one and other forms, where # is replaced by the value. English has no zero form, so use the _0 exact-match syntax for messages like "No messages". Exact matches always take precedence over plural forms.

Why does my translation not update when the locale changes?

The i18n object reference is stable across renders, so memoizing with it as a dependency breaks re-translation. Use the t function from the macro version of useLingui, or the _ function from the runtime version, since both change reference with locale.

Can I use the t macro at module level in Lingui?

No, the t macro requires component context and will not react to locale changes at module level. Use the msg macro to create lazy message descriptors, then translate them at render time with _() from useLingui.

What import paths should I use for Lingui v5?

In v5, import core macros like t and msg from @lingui/core/macro and React macros like Trans and Plural from @lingui/react/macro. Runtime pieces like I18nProvider come from @lingui/react and the i18n object from @lingui/core.

Why are my Lingui messages not being extracted?

Extraction fails when the include patterns in lingui.config.js do not match your source files. Verify the catalogs configuration covers your source directory, exclude test files, and run lingui extract followed by lingui compile.