Skip to content

Add unused translation key check#1213

Draft
jamesmengo wants to merge 1 commit into
mainfrom
jm/unused-translation-key
Draft

Add unused translation key check#1213
jamesmengo wants to merge 1 commit into
mainfrom
jm/unused-translation-key

Conversation

@jamesmengo
Copy link
Copy Markdown
Contributor

@jamesmengo jamesmengo commented May 27, 2026

What are you adding in this PR?

Adds UnusedTranslationKey, a new Theme Check rule that reports default locale keys that are not statically referenced by the theme.

This checks:

  • locales/*.default.json
  • locales/*.default.schema.json

I'm only adding this to all config for now

What is covered / ignored

Example What happens
{{ 'cart.title' | t }} Protects cart.title as a literal storefront reference.
{{ 'cart.title' | translate }} Protects cart.title; translate is handled the same as t.
"label": "t:sections.header.settings.title.label" Protects sections.header.settings.title.label for schema locale files.
{{ 'cart.' | append: 'title' | t }} Resolves the literal append chain and protects cart.title.
{{ 'title' | prepend: 'cart.' | t }} Resolves the literal prepend chain and protects cart.title.
{{ 'products.product.' | append: state | t }} Treats products.product. as a safe prefix and protects products.product.*.
{{ 'cart.items' | t: count: cart.item_count }} Protects pluralization leaves such as cart.items.one and cart.items.other.
{{ translation_key | t }} Treats the storefront reference as unbounded dynamic and disables storefront unused-key reporting.
{% assign key = 'actions.' | append: action %} + {{ key | t }} Also treated as unbounded dynamic; this PR does not trace Liquid assignment/data flow.
shopify.sentence.words_connector in a locale file Ignored by default; not reported as unused.
customer_accounts.order.title in a locale file Ignored by default; not reported as unused. Reviewer callout: this default is worth checking.

What did you learn?

Resolving dynamic keys can be a much larger problem than I initially thought 😆. Oh, silly me.

Tophatting

  • I added screenshots of the changes (before and after the changes if applicable)

Automated checks run:

  • pnpm --dir packages/theme-check-common build
  • pnpm --dir packages/theme-check-common type-check
  • pnpm --dir packages/theme-check-node build
  • pnpm exec changeset status --since=origin/main
  • pnpm build currently fails before Theme Check on unrelated packages/prettier-plugin-liquid TypeScript errors
  • pnpm test packages/theme-check-common/src/utils/translation-references.spec.ts packages/theme-check-common/src/checks/translation-key-exists/index.spec.ts packages/theme-check-common/src/checks/matching-translations/index.spec.ts packages/theme-check-common/src/checks/valid-schema-translations/index.spec.ts packages/theme-check-common/src/checks/unused-translation-key/index.spec.ts --run

Before you deploy

  • This PR includes a new checks or changes the configuration of a check
    • I included a minor bump changeset
    • I ran the Theme Check build/config generator and confirmed there are no additional generated config changes
    • theme-app-extension.yml is not applicable here; generated config did not change
    • [Shopifolk] I've made a PR to update the shopify.dev theme check docs if applicable (link PR here).
  • My feature is backward compatible

@jamesmengo jamesmengo force-pushed the jm/unused-translation-key branch 5 times, most recently from 9bc501e to da72b57 Compare May 27, 2026 23:33
expect(offenses).to.have.length(0);
});

it('ignores Shopify-provided translation key namespaces by default', async () => {
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@karreiro please sanity check this

@jamesmengo jamesmengo force-pushed the jm/unused-translation-key branch from da72b57 to 201bcb2 Compare May 27, 2026 23:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant