Find Unwrapped Strings

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:

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:

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

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.