К основному содержанию
скилл CX Codex

find-unwrapped-strings — скилл для Claude Code: аудит Lingui

Скилл find-unwrapped-strings находит пользовательские строки в проекте Lingui, которые не обёрнуты макросами перевода. Запускайте его после настройки или миграции, чтобы проверить, что осталось вне каталогов.

MIT 165 установок ★ 12 обновлён 2026-10-20

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add lingui/skills --skill find-unwrapped-strings -a claude-code
Открыть на GitHub

Что делает find-unwrapped-strings

Скилл проверяет код проекта с Lingui на строковые литералы, которые могут отображаться пользователю без перевода. Он помогает найти пропуски в данных, конфигурациях и вспомогательных функциях, а не только в JSX. Каждое совпадение нужно оценить по роли: например, видимую пользователю подпись переводят, а сегмент URL — нет.

Для сканирования скилл настраивает правило lingui/no-unlocalized-strings из eslint-plugin-lingui и запускает ESLint по файлам проекта. Вне компонентов он предлагает описывать перевод через msg, а разрешать его в месте отображения; после исправлений — извлечь и скомпилировать каталоги Lingui, затем просканировать код ещё раз.

Для постоянной проверки нужен eslint-plugin-lingui как зависимость разработки. Пресеты recommended и flat/recommended не включают нужное правило, поэтому его следует настроить явно. Аудит ограничен двумя раундами исправлений или примерно 40 файлами: при достижении предела скилл останавливается и сообщает об этом.

Какие задачи решает

  • найти пользовательские строки без макросов Lingui
  • проверить покрытие переводами после миграции
  • отличить видимые подписи от slug и кодовых значений
  • исправить строки в данных и конфигурациях
  • повторно просканировать проект после обновления каталогов

Примеры запросов агенту

  • Проверь проект Lingui и найди пользовательские строки, которые не обёрнуты макросами.
  • Проведи аудит покрытия переводами после миграции на Lingui и разбери каждое совпадение.
  • Найди строки интерфейса, которые продолжают отображаться на исходном языке, хотя каталоги заполнены.

Как установить find-unwrapped-strings

1Через Skills CLI (Vercel)

npx skills add lingui/skills --skill find-unwrapped-strings -a claude-code

2Вручную: положить файлы

~/.claude/skills/find-unwrapped-strings/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/find-unwrapped-strings/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о find-unwrapped-strings

Как установить find-unwrapped-strings в Claude Code?

Выполните npx skills add lingui/skills --skill find-unwrapped-strings -a claude-code. Файл скилла находится по пути ~/.claude/skills/find-unwrapped-strings/SKILL.md.

Что делает find-unwrapped-strings?

Скилл сканирует проект Lingui на строки, которые могут показываться пользователю без перевода. Он помогает определить, какие совпадения обернуть макросами, а какие оставить без перевода.

Что нужно для сканирования проекта?

Скилл использует ESLint и правило lingui/no-unlocalized-strings из eslint-plugin-lingui. Для постоянной проверки плагин нужно установить как зависимость разработки и явно включить правило.

Исходный текст

SKILL.md · MIT
---
name: find-unwrapped-strings
description: Audit a Lingui project for hardcoded user-facing strings that were never wrapped in macros. Use when asked to find untranslated, unwrapped, or hardcoded strings, to check i18n coverage, to audit what an i18n setup or migration missed, or when text renders in the source language after everything was supposedly translated.
---

# Find Unwrapped Strings

## When to run this

- After a Lingui setup or a migration onto Lingui — both wrap what they touch, and neither proves the rest of the codebase was touched.
- When the report is "the build is green and the catalogs are full, but this screen still shows English in every locale."
- As a periodic coverage audit on a project where i18n is already established.

The misses are systematic, not random. Strings in JSX get wrapped because they look like UI; what survives is display copy that doesn't — inside data modules (`export const products = [{ name: "AeroPress Go" }]`), message maps in toast and error helpers, labels in config objects.

**The scan is over-inclusive by design.** Precision comes from judging each hit against the skip-list, never from tuning the scanner until it goes quiet. A quiet scanner is indistinguishable from a clean codebase, and only one of those is worth having.

Judge by role, never by language. The scanner flags string literals structurally and the skip-list decides which are user-facing — what natural language a string appears to be written in is not an input to that decision, and working it out is pure overhead.

## Step 1 — Ensure the guardrail

Install `eslint-plugin-lingui` and enable `no-unlocalized-strings` at `warn` with the tuned options from [references/eslint-config.md](references/eslint-config.md):

```bash
npm install --save-dev eslint-plugin-lingui
```

Take the current release — it's a lint-only dev dependency, so there's nothing a pinned range protects.

**This install is permanent.** The audit is a one-time sweep; the rule is what stops the next regression. An audit that finds 30 strings and leaves no guardrail behind buys a few weeks.

Enable the rule explicitly. The plugin's `recommended` and `flat/recommended` presets do **not** include it, so extending a preset is not coverage — the reference has the detail.

If the user declines a new dev dependency, there is a one-shot mode — write the tuned config outside the repo and point ESLint at it, leaving the project untouched:

```bash
npx eslint -c /tmp/lingui-audit.config.js --no-config-lookup 'src/**/*.{ts,tsx}' --format json
```

Offer that only after they decline, and say what it costs: the audit works, but nothing prevents the next unwrapped string and the next audit starts from zero. Recommend the install.

Either way, this step is done once a scan runs and the rule reports.

## Step 2 — Scan

```bash
npx eslint 'src/**/*.{ts,tsx}' --format json > /tmp/lingui-scan.json
```

Filter to `ruleId === "lingui/no-unlocalized-strings"` and reduce to `file:line` plus the offending source line — the reference has the `jq` recipe. That list is the worklist; work it top to bottom.

Keep the rule's options in the config file and run the CLI with no rule flags. An options-bearing `--rule` replaces the configured options rather than merging, roughly doubling the hit list with class names and log arguments — and the longer list reads as *more* thorough, so its garbage gets "fixed" by wrapping identifiers. The reference has the measurements.

When a scan comes back clean on a codebase you have reason to suspect, check the glob before believing it: a `files` pattern of `src/**/*.ts` never lints `.tsx`, and the run still exits 0.

## Step 3 — Judge each hit

Every hit gets a **disposition** — wrapped, or skipped with a recorded reason. No hit leaves this step without one.

The skip-list lives in the **lingui-best-practices** skill, section "Don't Wrap Non-UI Strings" — the authority on what stays unwrapped. Read it there before dispositioning. If it's out of reach, the role test below carries the judgment.

Dispositions turn on the string's **role**, not its shape. `"Best seller"` in a data module is a badge a shopper reads — wrap it. `"aero-press-go"` in the same object is a URL segment — skip it. Two questions settle the ambiguous ones:

- Could a translator change this without breaking anything? (`"DRAFT"` as a status value: no.)
- If this rendered in Japanese, would that be correct or a bug? (A `sku` in Japanese is a bug.)

When the line alone can't answer, read the consuming site. A string's role lives where it's used, not where it's defined.

## Step 4 — Fix in bounded batches

Wrap per the macro decision tree in **lingui-best-practices**. The cases this audit turns up most:

- JSX content → `Trans`
- A string inside a component (attribute, `alert`, function argument) → `useLingui()` + `` t`…` ``
- **A string outside any component** — data module, module-level map, config object → `msg` descriptor from `@lingui/core/macro`, resolved at the consuming site.

That last case is what this audit exists for, and it's the one that gets fixed wrongly. `t` at module scope resolves once, at import time, against whatever locale happened to be active, and then never changes. Define with `msg`, resolve where it renders:

```ts
// src/data/products.ts — definition
import { msg } from "@lingui/core/macro";

export const products = [
  { sku: "sku-1001", slug: "aero-press-go", name: msg`AeroPress Go` },
];
```

```tsx
// consuming component — resolution
const { t } = useLingui();
<h2>{t(products[0].name)}</h2>;
```

The field's type changes from `string` to `MessageDescriptor`, so TypeScript points at every consuming site — follow it. In non-React code with no render moment, `i18n._(descriptor)` resolves at call time, which is what a toast helper wants.

Add translator comments as you wrap, per **enhanced-message-context**: data-module labels and one-word badges are its must-comment cases, arriving with no surrounding UI to infer meaning from.

Then, once per round:

```bash
npx lingui extract --clean
npx lingui compile
```

and re-scan from Step 2.

**Bounds: at most 2 fix rounds, or ~40 files.** On hitting either, stop and report. A human can rerun the audit; a human cannot review a 200-file diff.

## Step 5 — Terminate

Stop when one of these is true, and say which:

1. **The scan is clean.**
2. **A round wrapped zero new strings** — every remaining hit is a confirmed false positive. Grow the rule's configured ignores from those specific cases, per the reference's discipline, so the guardrail stays quiet while still reporting everything else. Severity stays at `warn`, the rule stays enabled, and hits get ignores rather than `eslint-disable` comments.
3. **The bound is exhausted** (2 rounds / ~40 files).

## Step 6 — Report

Every hit from every scan lands in one of three buckets, stated with `file:line`:

- **Wrapped** — what changed, and which macro.
- **Skipped** — with the skip-list reason (`slug`, `enum value`, `log output`).
- **Residual** — still open, reviewed or not, listed individually so the next run starts here.

Report the guardrail state too: severity, and which ignores you added with the evidence that earned each.

Account for every hit before claiming the audit is finished. "I wrapped 16 strings" is not a result; "wrapped 16, skipped 16 as identifiers and log output, 0 residual, rule left at `warn`" is. Unreported residuals are the one outcome this skill exists to prevent — the misses were invisible in the first place precisely because nobody wrote them down.

## Invoked by another workflow?

An orchestrator (a setup skill, a TMS-connection skill) may supply scope (`src/features/checkout` only, or the files a migration touched), extra skip-list entries from a project rules file (brand names, product codes), or known misses ("an earlier pass missed the data layer").

Honor all three. The pipeline and the reporting contract don't change: scope narrows what you scan, never what you report. Findings outside the given scope are reported as out-of-scope, not omitted.

## Related skills

- **lingui-best-practices** — owns the skip-list and the macro decision tree that Steps 3 and 4 run on.
- **enhanced-message-context** — translator comments for the short, context-free labels this audit surfaces.

© lingui · MIT · lingui/skills

Похожие скиллы

Все скиллы по теме «Языки программирования» →
i18n-strings rerun-build Скилл i18n-strings для Claude Code помогает проводить строки интерфейса через систему переводов Rerun. Включается при добавлении текста в apps/ui или packages/ui, работе с датами и числами или подключении нового языка. CX Codex +1 ★ 1 120звёзд репо internationalization-i18n aj-geddes Скилл internationalization-i18n для Claude Code помогает внедрять интернационализацию и локализацию в приложении. Он включается для работы с переводами, форматами и языками с письмом справа налево. CX Codex +1 648установок blog-locale-audit AgriciDaniel Скилл blog-locale-audit для Claude Code проверяет папку с многоязычными постами: ищет пропуски и расхождения между версиями. Запускается по запросу проверить переводы, hreflang или локали. CX Codex +1 2 600установок mcp Translatize MCP-сервер mcp подключает API Translatize к ассистенту через stdio. Позволяет искать, менять метки локализации и заполнять недостающие переводы прямо из чата. CX Codex +1 dart-multiline-strings kevmoo Скилл dart-multiline-strings для Claude Code учит переписывать цепочки print() и конкатенации в тройные кавычки. Запускается при рефакторинге CLI-вывода, шаблонных сообщений и многострочных блоков в Dart. CX Codex +1 116установок localize-unity-project Unity-Technologies Скилл localize-unity-project для Claude Code настраивает локализацию Unity: языки, таблицы строк и ресурсов, шрифты для китайского, японского и корейского. Работает с задачами добавления языков и перевода интерфейса. CX Codex +1 659установок

Из того же набора6

lingui-best-practices Скилл lingui-best-practices помогает внедрять Lingui для локализации интерфейсов и каталогов переводов. Пригодится при добавлении i18n в приложения на React, Vue или JavaScript. CX Codex +1 811установок enhanced-message-context Скилл enhanced-message-context для Claude Code расставляет комментарии для переводчиков в сообщениях Lingui и решает, каким строкам они нужны — двусмысленным подписям и непрозрачным плейсхолдерам вроде {count}. CX Codex +1 630установок swc-plugin-compatibility Скилл swc-plugin-compatibility помогает устранить сбои сборки и несовместимость @lingui/swc-plugin с Next.js, Vite и Rspack, когда макросы локализации не преобразуются. CX Codex +1 305установок migrate-i18next-to-lingui Скилл migrate-i18next-to-lingui для Claude Code переносит проект с i18next и react-i18next на Lingui — от конфигурации до каталогов переводов. Помогает поэтапно заменить API. CX Codex +1 197установок lingui-framework-setup Скилл lingui-framework-setup настраивает интернационализацию с Lingui под Next.js, Remix, TanStack Start или Vite. Предотвращает ошибки сборки макросов и утечки локалей на сервере. CX Codex +1 159установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой