Lingui Skills

April 28, 2026 ยท View on GitHub

This repository contains Agent Skills for Lingui - a powerful internationalization framework for JavaScript applications.

What are Agent Skills?

Skills are reusable capabilities for AI coding agents. They provide procedural knowledge and best practices that help AI agents implement features correctly and efficiently.

Installation

Install all Lingui skills with a single command:

npx skills add lingui/skills

This gives your AI coding agent access to comprehensive Lingui knowledge including best practices, common pitfalls, and configuration patterns.

Available Skills

lingui-best-practices

Comprehensive guide for implementing internationalization with Lingui in React and JavaScript applications.

What it covers:

  • Setting up Lingui with I18nProvider
  • Using Trans macro for JSX translations
  • Using useLingui() for non-JSX translations
  • Pluralization with Plural component
  • Date and number formatting
  • Message extraction and compilation workflow
  • Configuration patterns
  • Common mistakes and how to avoid them

Use when:

  • Adding internationalization to a new or existing project
  • Translating React components
  • Working with message catalogs
  • Setting up or modifying lingui.config.js
  • Debugging i18n issues

enhanced-message-context

Add translator comments to Lingui messages so translators get the context they need. Comments describe where a message appears, what it does, and how to disambiguate it - improving translation quality without runtime cost.

What it covers:

  • When to add comment fields (ambiguous words, isolated labels, domain terms, unclear variables)
  • When to skip comments (self-explanatory or already descriptive messages)
  • How to write effective comments (location, action/purpose, disambiguation)
  • API usage for t, Trans, and defineMessage with comments

Use when:

  • Adding or modifying translatable messages
  • Working with short or ambiguous strings (e.g., "Back", "Delete", "Post")
  • Creating table headers, button labels, or tooltips without surrounding UI context
  • Messages with placeholders whose meaning isn't obvious (e.g., {count}, {name})

swc-plugin-compatibility

Diagnose and fix @lingui/swc-plugin compatibility errors with Next.js, Rspack, or other SWC runtimes.

Use when you see errors like:

  • failed to invoke plugin on 'Some("...")'
  • failed to run Wasm plugin transform
  • RuntimeError: out of bounds memory access
  • LayoutError called Result::unwrap()

What it covers:

  • Why SWC plugin compatibility errors happen
  • How to find compatible plugin versions
  • Version pinning strategies
  • Alternative solutions (Babel plugin)

migrate-i18next-to-lingui

Migration playbook for converting i18next/react-i18next projects to Lingui.

What it covers:

  • Setup and tooling for Babel/SWC/Vite
  • Code migration patterns for React and JS/TS (useTranslation, Trans, t)
  • Plural/context/namespace migration strategies
  • Catalog conversion and verification (lingui extract, lingui compile)

Use when:

  • Migrating an existing i18next or react-i18next codebase
  • Preserving translation keys with explicit Lingui IDs
  • Moving from JSON namespaces to Lingui catalogs

Quick Start

  1. Install all Lingui skills:

    npx skills add lingui/skills

  2. Use with your AI coding agent: The skills will automatically be available when working on projects that use Lingui, or when you mention terms like "i18n", "internationalization", "translation", "Lingui", etc.

  3. Manual trigger: You can explicitly reference the skills in your prompts:

    "Using the Lingui skills, help me add internationalization to my React app"

Installing Individual Skills

If you prefer, you can install specific skills:

npx skills add lingui/skills/lingui-best-practices
npx skills add lingui/skills/swc-plugin-compatibility
npx skills add lingui/skills/enhanced-message-context
npx skills add lingui/skills/migrate-i18next-to-lingui

Compatibility

These skills are compatible with:

Resources

Contributing

Have suggestions for improving these skills? Found an error?

  1. Open an issue in this repository
  2. Submit a pull request with improvements
  3. Join the Lingui Discord to discuss

License

MIT License - See the main Lingui repository for details.