Lingui Skills

This repository contains Agent Skills for Lingui, a lightweight internationalization (i18n) framework for JavaScript and TypeScript.

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

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.

Alternatively, install the skills as a Claude Code plugin. In Claude Code, run:

/plugin marketplace add lingui/skills
/plugin install lingui@lingui-skills

All skills load automatically and stay up to date via /plugin marketplace update.

The repo is also installable as a plugin via the plugins CLI, which auto-detects your installed agent tools (Claude Code, Cursor, Codex, Grok Build, Kimi Code, GitHub Copilot CLI, VS Code) and installs through each tool's native plugin system:

npx plugins add lingui/skills

The repo is a Gemini CLI extension — install it with:

gemini extensions install https://github.com/lingui/skills

The GitHub CLI (v2.90+) can install the skills for GitHub Copilot or any other supported agent:

gh skill install lingui/skills --all

Use --agent <name> (e.g. --agent cursor) to target a specific tool, and gh skill update to pull newer versions.

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

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})

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)

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

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"
   

If you prefer, you can install specific skills:

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

These skills are compatible with:

• Claude Code
• Cursor
• OpenAI Codex
• Gemini CLI
• GitHub Copilot
• OpenCode
• Cline
• Windsurf
• And other agents supporting the Agent Skills format

• Lingui Documentation
• Lingui GitHub
• Skills.sh
• Lingui Discord Community

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

MIT — see LICENSE.