Adonis0123/adonis-skills / .agents/skills/lingui-best-practices
lingui-best-practices
VerifiedImplement 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.
| File | Kind | Size |
|---|---|---|
| LICENSE.txt | markdown | 1.0 KB |
| SKILL.md | skill md | 9.6 KB |
| references/common-mistakes.md | markdown | 10.4 KB |
| references/configuration.md | markdown | 3.2 KB |
references/configuration.md
View on GitHub# Configuration Patterns
Essential patterns for `lingui.config.js` (or `.ts`).
## Basic Configuration
The minimal configuration:
```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/**"],
},
],
});
```
**Key fields**:
- `sourceLocale` - Your source code's language (usually "en")
- `locales` - Array of BCP-47 locale codes
- `catalogs` - Where to find/store message catalogs
## Common Catalog Patterns
### Pattern 1: Single Directory (Recommended for most projects)
```js
catalogs: [
{
path: "src/locales/{locale}/messages",
include: ["src"],
},
]
```
**Structure**:
```
src/locales/
├── en/messages.po
├── es/messages.po
└── fr/messages.po
```
### Pattern 2: Separate Catalogs per Feature
For large projects where you want to split translations:
```js
catalogs: [
{
path: "src/{name}/locales/{locale}",
include: ["src/{name}/"],
},
]
```
**Structure**:
```
src/
├── auth/locales/en.po
├── dashboard/locales/en.po
└── settings/locales/en.po
```
Use `catalogsMergePath` to compile into single files:
```js
catalogsMergePath: "src/locales/{locale}"
```
## Essential Configuration Options
### Fallback Locales
Handle missing translations by falling back to other locales:
```js
fallbackLocales: {
"en-US": "en", // en-US → en
"es-MX": "es", // es-MX → es
default: "en" // Everything else → en
}
```
### Compilation Format
Control the output format of compiled catalogs:
```js
compileNamespace: "es" // ES6 modules (default: "cjs")
```
**Common options**:
- `cjs` - CommonJS: `module.exports = {messages: {...}}`
- `es` - ES6: `export const messages = {...}`
- `ts` - TypeScript with type definitions
### TypeScript Support
For TypeScript projects:
```js
compileNamespace: "ts"
```
Then compile with:
```bash
lingui compile --typescript
```
### Parser Options
If using TypeScript experimental decorators or Flow:
```js
extractorParserOptions: {
tsExperimentalDecorators: true,
}
```
## Message Ordering
Control catalog message order:
```js
orderBy: "messageId" // Options: "message", "messageId", "origin"
```
## Common Issues & Solutions
### Issue: Messages Not Extracted
**Problem**: CLI doesn't find your messages.
**Solution**: Check your `include` patterns are correct:
```js
catalogs: [
{
path: "src/locales/{locale}/messages",
include: ["src/**/*.{js,jsx,ts,tsx}"], // Be specific
exclude: ["**/*.test.*", "**/*.spec.*"],
},
]
```
### Issue: Can't Import Compiled Catalogs
**Problem**: Import path doesn't match compiled location.
**Solution**: Ensure `path` matches your import:
```js
// Config
path: "src/locales/{locale}/messages"
// Import must match
import { messages } from "./locales/en/messages";
```
## Best Practices
1. **Use `<rootDir>` token** for portable paths
2. **Always exclude test files** in `exclude` patterns
3. **Set `sourceLocale`** to your development language
4. **Add `.gitignore` for compiled files**: `*.js` in locale directories
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |