{
  "markdown": "# Lingui Skills\n\nThis repository contains Agent Skills for [Lingui](https://lingui.dev), a lightweight internationalization (i18n) framework for JavaScript and TypeScript.\n\n## What are Agent Skills?\n\nSkills are reusable capabilities for AI coding agents. They provide procedural knowledge and best practices that help AI agents implement features correctly and efficiently.\n\n## Installation\n\nInstall all Lingui skills with a single command:\n\n```bash\nnpx skills add lingui/skills\n```\n\nThis gives your AI coding agent access to comprehensive Lingui knowledge including best practices, common pitfalls, and configuration patterns.\n\n### Claude Code Plugin\n\nAlternatively, install the skills as a [Claude Code plugin](https://code.claude.com/docs/en/discover-plugins). In Claude Code, run:\n\n```\n/plugin marketplace add lingui/skills\n/plugin install lingui@lingui-skills\n```\n\nAll skills load automatically. Every commit to `main` is a new plugin version, so newly added skills reach you as soon as the plugin updates. Turn on auto-update once (run `/plugin`, open the **Marketplaces** tab, select `lingui-skills`, choose **Enable auto-update**), or update by hand:\n\n```\n/plugin update lingui@lingui-skills\n/reload-plugins\n```\n\nWhere the `/plugin` panel is not available, such as in IDE extensions, run `claude plugin update lingui@lingui-skills` in a terminal instead. A running session keeps the version it started with, so new skills appear after `/reload-plugins` or a restart. Note that `/plugin marketplace update` only refreshes the catalog and does not update the installed plugin.\n\n### Other Agent Tools (Plugin Install)\n\nThe repo is also installable as a plugin via the [`plugins` CLI](https://npmx.dev/package/plugins), 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:\n\n```bash\nnpx plugins add lingui/skills\n```\n\n### Gemini CLI\n\nThe repo is a [Gemini CLI extension](https://geminicli.com/docs/extensions/) — install it with:\n\n```bash\ngemini extensions install https://github.com/lingui/skills\n```\n\n### GitHub CLI\n\nThe [GitHub CLI](https://cli.github.com) (v2.90+) can install the skills for GitHub Copilot or any other supported agent:\n\n```bash\ngh skill install lingui/skills --all\n```\n\nUse `--agent <name>` (e.g. `--agent cursor`) to target a specific tool, and `gh skill update` to pull newer versions.\n\n## Available Skills\n\n### lingui-best-practices\n\nComprehensive guide for implementing internationalization with Lingui in React and JavaScript applications.\n\n**What it covers:**\n\n- Choosing the right macro (`Trans`, `t`, `msg`, `Plural`) for each situation\n- Setting up Lingui with `I18nProvider`\n- Using `Trans` macro for JSX translations\n- Using `useLingui()` for non-JSX translations\n- Pluralization with `Plural` component\n- Naming placeholders with `ph()` instead of positional `{0}`\n- Date and number formatting\n- Message extraction and compilation workflow\n- Catalog hygiene: build-script integration, gitignore rules, CI drift check\n- Single-sourced locale metadata (direction, display names, fallback resolution)\n- Configuration patterns and Lingui 6 upgrade notes (ESM-only, Node ≥ 22.19)\n- Common mistakes and how to avoid them\n\n**Use when:**\n\n- Adding internationalization to a new or existing project\n- Translating React components\n- Working with message catalogs\n- Setting up or modifying `lingui.config.js`\n- Debugging i18n issues\n\n### lingui-framework-setup\n\nFramework-native Lingui setup recipes for the five major React stacks: Next.js App Router (RSC), Vite SPA (SWC and Babel), React Router 7 framework mode, Remix v2, and TanStack Start.\n\n**What it covers:**\n\n- Detection-first setup: identify the framework, compiler (SWC vs Babel), and router before recommending anything\n- Server-side locale resolution under SSR (cookie + `Accept-Language`) and why browser detection breaks there\n- Per-request/per-locale i18n instances — avoiding cross-request locale bleed\n- The `@vitejs/plugin-react` v6 trap (removed `babel` option) and the SWC plugin pinning discipline\n- Locale-prefixed URL strategies, middleware/proxy handling (including the Next 16 rename), language switchers per stack\n- A verification sequence that proves the macro transform actually ran\n\n**Use when:**\n\n- Adding Lingui to a Next.js, Vite, React Router 7, Remix, or TanStack Start project\n- Wiring locale detection, locale-prefixed URLs, or SSR locale resolution\n- A working Lingui setup breaks after a framework upgrade\n- Macros silently stop being transformed after a build-tool change\n\n### enhanced-message-context\n\nAdd 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.\n\n**What it covers:**\n\n- Tiered guidance on when to add `comment` fields (must / should / lower priority)\n- Detecting the app domain and using it to disambiguate terms\n- How to write effective comments (location, action/purpose, disambiguation, under ~80 chars)\n- `comment` vs `context` — and why `context` must not be used for namespacing\n- A post-extraction review pass to catch uncommented `.po` entries\n- API usage for `t`, `Trans`, and `defineMessage` with comments\n\n**Use when:**\n\n- Adding or modifying translatable messages\n- Working with short or ambiguous strings (e.g., \"Back\", \"Delete\", \"Post\")\n- Creating table headers, button labels, or tooltips without surrounding UI context\n- Messages with placeholders whose meaning isn't obvious (e.g., `{count}`, `{name}`)\n\n### swc-plugin-compatibility\n\nDiagnose and fix `@lingui/swc-plugin` compatibility errors with Next.js, Rspack, or other SWC runtimes.\n\n**Use when you see errors like:**\n\n- `failed to invoke plugin on 'Some(\"...\")'`\n- `failed to run Wasm plugin transform`\n- `RuntimeError: out of bounds memory access`\n- `LayoutError called Result::unwrap()`\n- A successful build where macros are silently not transformed\n\n**What it covers:**\n\n- Why SWC plugin compatibility errors happen\n- How to find compatible plugin versions\n- Version pinning strategies\n- The plugin tuple-shape trap that silently disables macros\n- Alternative solutions (Babel plugin) and the `@vitejs/plugin-react@6` caveat\n\n### find-unwrapped-strings\n\nAudits a Lingui project for hardcoded user-facing strings that were never wrapped — the ones a green build hides: display copy in data modules, toast and error helper maps, config labels.\n\n**What it covers:**\n\n- Installing `eslint-plugin-lingui` as a permanent guardrail, with tuned `no-unlocalized-strings` options\n- Why the plugin's `recommended` presets don't enable the rule, and why `--rule` on the CLI discards tuned ignores\n- Judging every hit against the skip-list — string *role*, not string shape\n- Wrapping display copy defined outside components with `msg` descriptors, and why `t` at module scope silently never updates\n- A bounded fix loop (2 rounds / ~40 files) that always reports residuals as wrapped / skipped-with-reason / out-of-budget\n- Growing the rule's ignores from confirmed false positives instead of weakening it\n\n**Use when:**\n\n- Text renders in the source language even though the catalogs look complete\n- Auditing what an i18n setup or migration missed\n- Checking i18n coverage on a project where Lingui is already established\n- The audit lint rule is noisy and you need it quiet without losing the guardrail\n\n### migrate-i18next-to-lingui\n\nMigration playbook for converting i18next/react-i18next projects to Lingui.\n\n**What it covers:**\n\n- Setup and tooling for Babel/SWC/Vite\n- Code migration patterns for React and JS/TS (`useTranslation`, `Trans`, `t`)\n- Plural/context/namespace migration strategies\n- Catalog conversion and verification (`lingui extract`, `lingui compile`)\n- A post-migration recall check that finds leftover i18next code and unwrapped strings\n\n**Use when:**\n\n- Migrating an existing i18next or react-i18next codebase\n- Preserving translation keys with explicit Lingui IDs\n- Moving from JSON namespaces to Lingui catalogs\n\n## Quick Start\n\n1. **Install all Lingui skills:**\n   ```bash\n   npx skills add lingui/skills\n   ```\n\n2. **Use with your AI coding agent:**\n   The skills will automatically be available when working on projects that use Lingui, or when you mention terms like \"i18n\", \"internationalization\", \"translation\", \"Lingui\", etc.\n\n3. **Manual trigger:**\n   You can explicitly reference the skills in your prompts:\n   ```\n   \"Using the Lingui skills, help me add internationalization to my React app\"\n   ```\n\n### Installing Individual Skills\n\nIf you prefer, you can install specific skills:\n```bash\nnpx skills add lingui/skills --skill lingui-best-practices\nnpx skills add lingui/skills --skill lingui-framework-setup\nnpx skills add lingui/skills --skill swc-plugin-compatibility\nnpx skills add lingui/skills --skill enhanced-message-context\nnpx skills add lingui/skills --skill find-unwrapped-strings\nnpx skills add lingui/skills --skill migrate-i18next-to-lingui\n```\n\n## Compatibility\n\nThese skills are compatible with:\n- [Claude Code](https://claude.ai/product/claude-code)\n- [Cursor](https://cursor.sh)\n- [OpenAI Codex](https://openai.com/codex/)\n- [Gemini CLI](https://geminicli.com)\n- [GitHub Copilot](https://github.com/features/copilot)\n- [OpenCode](https://opencode.ai)\n- [Cline](https://cline.bot/)\n- [Windsurf](https://codeium.com/windsurf)\n- And other agents supporting the [Agent Skills](https://agentskills.io) format\n\n## Resources\n\n- [Lingui Documentation](https://lingui.dev)\n- [Lingui GitHub](https://github.com/lingui/js-lingui)\n- [Skills.sh](https://skills.sh)\n- [Lingui Discord Community](https://discord.gg/gFWwAYnMtA)\n\n## Contributing\n\nHave suggestions for improving these skills? Found an error?\n\n1. Open an issue in this repository\n2. Submit a pull request with improvements\n3. Join the [Lingui Discord](https://discord.gg/gFWwAYnMtA) to discuss\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 10033,
  "sha": "3286227acf3ff2b54fc533a2b43f991ca00b13e69656b9f77e500cc536b071d6",
  "repo_slug": "lingui/skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_lingui_skills_ca32d2a9/readme"
}