lingui-best-practices
Skill5 starsChanged 9 days agoMITView on GitHub
Implement or review Lingui message macros, catalog configuration, locale loading, and React or JavaScript integration. Use for Lingui-specific code and runtime issues, not plain text translation or another i18n library. For command-only catalog maintenance, use the project workflow.
- Installs packages
3 other projects use a version of this, 3 of them edited.
Adopted by
Most recently taken up by
- nhattran998/better-proxyedited, first seen Oct 11, 2026
- lingui/skillsedited, first seen Sep 2, 2026
- platformplatform/PlatformPlatformedited, first seen May 15, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 3
- platformplatform/PlatformPlatform★ 43994% same
- lingui/skills★ 1033% same
- nhattran998/better-proxy★ 094% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository44 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- agent-symlink-initSkill
- code-inspector-initSkill
- commitSkill
- copywritingSkill
- css-tailwind-stylingSkill
- lingui-workflowSkill
- repo-skill-creatorSkill
- weekly-reportSkill
- agent-dispatchSkill
- agentic-review-handoffSkill
- agent-practice-auditSkill
- agent-skill-evaluationSkill
- agent-symlink-initSkill
- architecture-hardening-loopSkill
- ardot-mcpSkill
- branch-creatorSkill
- chrome-dev-mcpSkill
- code-inspector-initSkill
- code-plugin-architectureSkill
- commit-pushSkill
- commitSkill
- decision-first-technical-writingSkill
- design-systemSkill
- desktop-agent-activitySkill
- dev-environment-roi-auditSkill
- disk-tidySkill
- figma-mcpSkill
- file-tidySkill
- goal-gateSkill
- grill-autopilotSkill
- kimi-computer-useSkill
- lingui-workflowSkill
- local-web-surfaceSkill
- open-code-review-loopSkill
- prompt-studioSkill
- review-prompt-composerSkill
- task-completion-loopSkill
- uxc-facadeSkill
- web-performance-auditSkill
- weekly-reportSkill
- workflow-gateSkill
- worktree-tidySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. 6 are common, 0 are distinctive, and 12 are very specific to this project.
6
Common
Most of the 3 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 31
Import from these packages:
- Very specific: line 114
When using Lingui in Next.js App Router with server components:
- Very specific: line 117
Ensure server initLingui(locale) activates locale before binding context:
- Very specific: line 121
If you hit Attempted to call a translation function without setting a locale, first verify initialization order before changing catalogs.
- Common: line 138
When you need to define messages at module level or in arrays/objects:
- Very specific: line 164
Use the Plural macro for quantity-dependent messages:
- Very specific: line 180
Use _N syntax for exact number matches (takes precedence over plural forms):
- Very specific: line 204
Use i18n.date() and i18n.number() for locale-aware formatting:
- Very specific: line 231
When the same text has different meanings, use context:
- Common: line 242
Add context for translators:
- Common: line 274
Prefer macros over runtime components.
- Common: line 286
Avoid complex expressions in messages - they'll be replaced with placeholders:
- Very specific: line 381
When using memoization, use the t function from the macro version:
- Common: line 402
If you encounter issues:
- Very specific: line 404
Messages not extracted: Check include patterns in lingui.config.js
- Very specific: line 405
Translations not applied: Ensure catalogs are compiled with lingui compile
- Very specific: line 406
Runtime errors: Verify I18nProvider wraps your app
- Very specific: line 407
Type errors: Run lingui compile --typescript for TypeScript projects
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Lingui Best Practices
Lingui is a powerful internationalization (i18n) framework for JavaScript. This skill covers best practices for implementing i18n in React and vanilla JavaScript applications.
Scope Before Setup
Reuse the project's existing Lingui version, framework, catalog layout, and initialization. A message edit does not require reinstalling packages or rebuilding the provider. Inspect the relevant imports and lockfile before applying version-sensitive examples; read only the reference needed for the current problem. The provider example below is a client-side starting point, not a replacement for an established RSC setup.
Quick Start Workflow
For a new integration, the main pieces are below. For an existing integration, work only on the pieces affected by the request:
- Wrap your app in
I18nProvider - Mark messages for translation using macros (
Trans,t, etc.) - Extract messages:
lingui extract - Translate the catalogs
- Compile catalogs:
lingui compile - Load and activate locale in your app
Core Packages
Import from these packages:
// React macros (recommended)
import { Trans, Plural, Select, useLingui } from "@lingui/react/macro";
// Core macros for vanilla JS
import { t, msg, plural, select } from "@lingui/core/macro";
// Runtime (rarely used directly)
import { I18nProvider } from "@lingui/react";
import { i18n } from "@lingui/core";Setup I18nProvider
Wrap your application with I18nProvider:
import { I18nProvider } from "@lingui/react";
import { i18n } from "@lingui/core";
import { messages } from "./locales/en/messages";
i18n.load("en", messages);
i18n.activate("en");
function App() {
return <I18nProvider i18n={i18n}>{/* Your app */}</I18nProvider>;
}Translating UI Text
Use Trans for JSX Content
The Trans macro is the primary way to translate JSX:
import { Trans } from "@lingui/react/macro";
// Simple text
<Trans>Hello World</Trans>
// With variables
<Trans>Hello {userName}</Trans>
// With components (rich text)
<Trans>
Read the <a href="/docs">documentation</a> for more info.
</Trans>
// Extracted as: "Read the <0>documentation</0> for more info."When to use: For any translatable text in JSX elements.
Use useLingui for Non-JSX
For strings outside JSX (attributes, alerts, function calls):
import { useLingui } from "@lingui/react/macro";
function MyComponent() {
const { t } = useLingui();
const handleClick = () => {
alert(t`Action completed!`);
};
return (
<div>
<img src="..." alt={t`Image description`} />
<button onClick={handleClick}>{t`Click me`}</button>
</div>
);
}When to use: Element attributes, alerts, function parameters, any non-JSX string.
Next.js App Router / RSC Rules
When using Lingui in Next.js App Router with server components:
- Initialize locale on both server layouts and server pages. Do not rely on layout-only initialization.
- Ensure server
initLingui(locale)activates locale before binding context:i18n.activate(locale)setI18n(i18n)
- In shared server components, prefer
useLingui/Transfrom@lingui/react/macrofor translated strings. - If you hit
Attempted to call a translation function without setting a locale, first verify initialization order before changing catalogs.
Example:
import { setI18n } from "@lingui/react/server";
export function initLingui(locale: AppLocale) {
const i18n = getI18nInstance(locale);
i18n.activate(locale);
setI18n(i18n);
return i18n;
}Use msg for Lazy Translations
When you need to define messages at module level or in arrays/objects:
import { msg } from "@lingui/core/macro";
import { useLingui } from "@lingui/react";
// Module-level constants
const STATUSES = {
active: msg`Active`,
inactive: msg`Inactive`,
pending: msg`Pending`,
};
function StatusList() {
const { _ } = useLingui();
return Object.entries(STATUSES).map(([key, message]) => (
<div key={key}>{_(message)}</div>
));
}When to use: Module-level constants, arrays of messages, conditional message selection.
Pluralization
Use the Plural macro for quantity-dependent messages:
import { Plural } from "@lingui/react/macro";
<Plural
value={messageCount}
one="You have # message"
other="You have # messages"
/>;The # placeholder is replaced with the actual value.
Exact Matches
Use _N syntax for exact number matches (takes precedence over plural forms):
<Plural value={count} _0="No messages" one="One message" other="# messages" />With Variables and Components
Combine with Trans for complex messages:
<Plural
value={count}
one={`You have # message, ${userName}`}
other={
<Trans>
You have <strong>#</strong> messages, {userName}
</Trans>
}
/>Formatting Dates and Numbers
Use i18n.date() and i18n.number() for locale-aware formatting:
import { useLingui } from "@lingui/react/macro";
function MyComponent() {
const { i18n } = useLingui();
const lastLogin = new Date();
return <Trans>Last login: {i18n.date(lastLogin)}</Trans>;
}These use the browser's Intl API for proper locale formatting.
Message IDs and Context
Explicit IDs
Provide a custom ID for stable message keys:
<Trans id="header.welcome">Welcome to our app</Trans>Context for Disambiguation
When the same text has different meanings, use context:
<Trans context="direction">right</Trans>
<Trans context="correctness">right</Trans>These create separate catalog entries.
Comments for Translators
Add context for translators:
<Trans comment="Greeting shown on homepage">Hello World</Trans>Configuration
Basic lingui.config.js:
import { defineConfig } from "@lingui/cli";
export default defineConfig({
sourceLocale: "en",
locales: ["en", "es", "fr", "de"],
catalogs: [
{
path: "<rootDir>/src/locales/{locale}/messages",
include: ["src"],
exclude: ["**/node_modules/**"],
},
],
});For detailed configuration patterns, see configuration.md.
Best Practices
Always Use Macros
Prefer macros over runtime components. Macros are compiled at build time, reducing bundle size:
// ✅ Good - uses macro
import { Trans } from "@lingui/react/macro";
// ❌ Avoid - runtime only
import { Trans } from "@lingui/react";Keep Messages Simple
Avoid complex expressions in messages - they'll be replaced with placeholders:
// ❌ Bad - loses context
<Trans>Hello {user.name.toUpperCase()}</Trans>;
// Extracted as: "Hello {0}"
// ✅ Good - clear variable name
const userName = user.name.toUpperCase();
<Trans>Hello {userName}</Trans>;
// Extracted as: "Hello {userName}"Use Trans for JSX, t for Strings
Choose the right tool:
// ✅ For JSX content
<h1>
<Trans>Welcome</Trans>
</h1>;
// ✅ For string values
const { t } = useLingui();
<img alt={t`Profile picture`} />;Don't Use Macros at Module Level
Macros need component context - use msg instead:
// ❌ Bad - won't work
import { t } from "@lingui/core/macro";
const LABELS = [t`Red`, t`Green`, t`Blue`];
// ✅ Good - use msg for lazy translation
import { msg } from "@lingui/core/macro";
const LABELS = [msg`Red`, msg`Green`, msg`Blue`];Use the ESLint Plugin
Install and configure eslint-plugin-lingui to catch common mistakes automatically:
npm install --save-dev eslint-plugin-lingui// eslint.config.js
import pluginLingui from "eslint-plugin-lingui";
export default [pluginLingui.configs["flat/recommended"]];Common Patterns
Dynamic Locale Switching
import { i18n } from "@lingui/core";
async function changeLocale(locale) {
const { messages } = await import(`./locales/${locale}/messages`);
i18n.load(locale, messages);
i18n.activate(locale);
}Loading Catalogs Dynamically
import { useEffect } from "react";
import { i18n } from "@lingui/core";
function loadCatalog(locale) {
return import(`./locales/${locale}/messages`);
}
function App() {
useEffect(() => {
loadCatalog("en").then((catalog) => {
i18n.load("en", catalog.messages);
i18n.activate("en");
});
}, []);
return <I18nProvider i18n={i18n}>{/* ... */}</I18nProvider>;
}Memoization with useLingui
When using memoization, use the t function from the macro version:
import { useLingui } from "@lingui/react/macro";
import { msg } from "@lingui/core/macro";
import { useMemo } from "react";
const welcomeMessage = msg`Welcome!`;
function MyComponent() {
const { t } = useLingui(); // Macro version - reference changes with locale
// ✅ Safe - t reference updates with locale
const message = useMemo(() => t(welcomeMessage), [t]);
return <div>{message}</div>;
}Troubleshooting
If you encounter issues:
- Messages not extracted: Check
includepatterns inlingui.config.js - Translations not applied: Ensure catalogs are compiled with
lingui compile - Runtime errors: Verify
I18nProviderwraps your app - Type errors: Run
lingui compile --typescriptfor TypeScript projects
For detailed common mistakes and pitfalls, see common-mistakes.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

