agentleFS
LedgerHQLedgerHQ/ledger-live/.agents/skills/i18n-keys/SKILL.md

i18n-keys

Skill628 starsChanged 4 days agoMITView on GitHub

Write wording keys the i18n key check can verify. Read when adding or changing t() / Trans i18nKey calls, key tables (titleKey, labelKey, ...) or English catalog entries in features/, domain/ or shared/, or when `lint:i18n-keys` fails.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Prefer, in this order:

    line 27
  2. Distinctive:

    missing in an app: add the key to that app's English catalog.

    line 54
  3. Very specific:

    a union member has no key in an app: add the key, or remove the member if that app never uses it.

    line 57

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

i18n keys

pnpm lint:i18n-keys (tools/nx-plugins/enforce-i18n-keys) checks that every key used in features/, domain/ and shared/ exists in the English catalog of each app consuming the package: Desktop static/i18n/en/app.json, Mobile src/locales/en/common.json. .web.* files are checked against Desktop only, .native.* against Mobile only. Other locales are not checked: only edit English.

Principle: the feature owns its keys

A feature resolves its own wording with useTranslation(). Apps must not inject keys or labels into features: pass a domain id or variant (stage, status) and let the feature map it to wording. A key prop coming from apps/* is a smell; key props between components of the same package are fine.

Write keys the check can verify

A key is verified when its type is a finite set of literals. A key typed string is unverifiable: it is counted and the count may never go up (unverifiable-baseline.json). Prefer, in this order:

  1. Literal at the call site: t("payTab.login.title"). Greppable, needs no types.
  2. Domain union, key derived in one place: a new member fails the check until its key exists.
    type Stage = "intro" | "login";
    declare const stage: Stage;
    t(`payTab.login.${stage}.title`); // every Stage member is expanded and checked
  3. Internal prop typed as a union of full keys: last resort, it duplicates key strings in a type.
    type Props = { titleKey: "x.intro.title" | "x.login.title" };

What widens a key to string and hides it:

const COPY: Record<Id, { titleKey: string }> = { ... }; // annotation widens: use as const satisfies
const rows = [{ key: "a" }, { key: "b" }]; // add as const
function labelKey(kind: Kind): string { ... } // annotate the literal union

Template spans must be unions or literal consts, not string or number. Template keys are not greppable: the check, not search, protects a "dead" key from deletion.

When the check fails

  • missing in an app: add the key to that app's English catalog.
  • unverifiable count went up: narrow the type (above), never raise the baseline.
  • count went down (CI fails until the baseline is lowered): run node tools/nx-plugins/enforce-i18n-keys/validate.js --update-baseline.
  • a union member has no key in an app: add the key, or remove the member if that app never uses it. allowMissing in unverifiable-baseline.json lists known gaps for the owning product team to fix; do not add to it without a reason in the PR.
  • stale allowMissing entry: the gap is fixed, remove the entry.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.