Skip to content

Adonis0123/adonis-skills / .agents/skills/lingui-best-practices

lingui-best-practices

Verified

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.

FileKindSize
LICENSE.txtmarkdown1.0 KB
SKILL.mdskill md9.6 KB
references/common-mistakes.mdmarkdown10.4 KB
references/configuration.mdmarkdown3.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
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall