feat(core): Resolve configurable operation strings from i18n catalogs by michaelbromley · Pull Request #5079 · vendurehq/vendure

michaelbromley · 2026-07-31T11:56:57Z

Configurable operation descriptions and arg labels are currently defined inline in each operation's .ts file as a LocalizedStringArray. Supporting a new language means editing every one of those files, which is why core has never gone beyond a handful of languages for these strings while the dashboard has reached 28.

This adds a second source for those strings: the server-side i18n message catalogs core already ships. There is no user-visible change in this PR — the mechanism lands, and the 1242 translations it enables are a follow-up.

Approach

Resolution happens server-side in toGraphQlType, so the GraphQL contract is unchanged and existing API consumers keep working.

The keys are derived from the operation itself, so ConfigurableOperationDefOptions is untouched and every existing plugin works unmodified:

configurableOperation.<type>.<code>.description
configurableOperation.<type>.<code>.args.<argName>.label
configurableOperation.<type>.<code>.args.<argName>.description
configurableOperation.<type>.<code>.args.<argName>.options.<optionValue>.label

<type> is the registry the operation belongs to. It has to be part of the key because a code is only unique within its own registry — core itself uses buy_x_get_y_free for both a PromotionCondition and a PromotionAction.

English stays inline. The catalogs hold translations only, so a missing translation falls back to the English already in the source file rather than to a raw key, and adding a 29th language adds zero lines to any .ts file.

Resolution order

For each language in turn — the requested language, then the Channel's default, then English — the catalog is checked first, then the inline array:

for (const languageCode of [ctx.languageCode, ctx.channel.defaultLanguageCode, DEFAULT_LANGUAGE_CODE]) {
    const fromCatalog = this.translator?.getConfigurableOperationTranslation(...);
    if (fromCatalog) return fromCatalog;
    const fromInline = inline?.find(x => x.languageCode === languageCode);
    if (fromInline) return fromInline.value;
}
return inline?.[0]?.value;

Checking both sources per language rather than exhausting the catalogs first matters: the other ordering would reach core's English catalog entry before a plugin's own German inline string, silently breaking every plugin that ships non-English strings today.

Catalog beating inline for the same language is deliberate, and is what allows a user to override a third-party operation's wording via addTranslation() without forking it.

Why the lookup bypasses `t()`

Six core descriptions are templates rather than sentences, such as Discount order by { discount }%. The Admin UI substitutes the live argument values client-side, so the braces have to survive the round trip untouched. Core's i18next is initialised with .use(ICU), which would treat { discount } as an argument reference.

I18nService.getConfigurableOperationTranslation() therefore reads the resource straight out of the store and walks the path segment by segment. That also sidesteps i18next's key splitting, so a plugin is free to use a code containing dots such as acme.shipping.handler.

Changes

Resolution and key derivation on ConfigurableOperationDef, covering the operation description, each arg's label and description, and ui.options[].label
getConfigurableOperationTranslation() on I18nService, plus a configurableOperation member on VendureTranslationResources (optional, so existing typed resource objects still compile)
A Symbol token in common/constants.ts, registered by I18nModule as useExisting: I18nService and captured in the base init(injector). A token rather than the class itself keeps the low-level ConfigurableOperationDef from importing the i18n module.
defType on the nine ConfigurableOperationDef subclasses. ConfigDefType in the registry is now an alias of the new ConfigurableOperationDefType union, so indexing ConfigDefTypeMap by it keeps the two lists in step.
getTranslationKeys(), which returns each key path with its English source value. Plugin authors can call it to check a key; the extraction tooling uses it as its input.
npm run i18n:extract / i18n:apply in packages/core, modelled on the dashboard's tooling and sharing its locale-profiles.js script validation, so a batch labelled ru with no Cyrillic in it is refused rather than written to disk.
Guide docs under "Server message translations".

Behaviour changes

Two small ones, both improvements:

An operation with an empty description: [] array previously threw inside localizeString. It now resolves to an empty string.
An arg label or description is now resolved even when the operation defines no inline array for it, so a label can be supplied purely from a catalog.

Testing

17 unit tests for the resolution chain in configurable-operation.spec.ts, including the case that proves existing plugins are not broken, and the case proving the shared ui config is not mutated across requests
6 unit tests for the catalog lookup against a real i18next instance, covering dotted codes and verbatim placeholders
3 e2e tests in translations.e2e-spec.ts exercising the token-based DI wiring end to end, which is the part that would fail silently if the token were wrong
Full core unit suite (1219 passed) and the e2e suites that exercise toGraphQlType: translations, promotion, order-promotion, promotion-side-effects, shipping-method, shipping-method-eligibility, collection, payment-method, payment-process, configurable-operation-secrets (235 passed)

Follow-ups

Generate and land the configurableOperation translations for all 27 non-English locales. i18n:extract reports 46 distinct strings across 23 core operations, so 1242 translations. This is the point at which a Czech administrator finally sees Czech.
Backfill core's error / errorResult / message namespaces from 8 locales to 28. They have already drifted — en.json has 58 error keys, de.json has 45, ru.json has 44.
Custom field label and description. The same underlying pain, but a different architecture: CustomField.label goes over the wire as a full LocalizedString[] and is resolved client-side, so covering it means a breaking schema change.

Relates to #4820

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Relates to #4820

vendure-developer-hub · 2026-07-31T11:57:00Z

Vendure Core — View preview

Changed pages:

_ffe8c49

vercel · 2026-07-31T11:57:03Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vendure-storybook	Ready	Preview	Aug 4, 2026 9:51am

coderabbitai · 2026-07-31T11:57:06Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 53f87e6f-3ed0-453c-a6b2-7333c67721a4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-07-31T12:02:56Z

Dashboard Preview: https://admin-dashboard-4wo69zgtl-vendure.vercel.app

Relates to #4820

grolmus

Second-eyes review @michaelbromley — this is really cleanly built. The token-based CONFIGURABLE_OPERATION_TRANSLATOR (rather than importing I18nService into the low-level base class), reading via getResourceBundle + manual path walk instead of t() to preserve { arg } placeholders, and the ConfigDefType = ConfigurableOperationDefType alias with the compile-error-on-omission guarantee are all the right calls. The resolution order (per-language: catalog → inline, so a plugin's own non-English inline string isn't beaten by core's English catalog) is subtle and correctly handled, and the test suite genuinely covers it — including the shared-ui-mutation case with the follow-up assertion that the source array isn't truncated. Nothing blocking below; one thing worth confirming and a few minor notes.

Worth confirming: `ui.options[].label` shape narrowing

Previously toGraphQlType passed ui: arg.ui through verbatim, so ui.options[].label reached the client as the full multi-language LocalizedStringArray. localizeUiOptions now resolves it server-side to a single-entry array:

? option
: { ...option, label: [{ languageCode: ctx.languageCode, value: label }] };

Two consequences:

The stamped language can be inaccurate on fallback. The entry is always stamped with ctx.languageCode, even when the resolved value came from the channel default or the English inline fallback — e.g. a de request with only an English inline option label returns [{ languageCode: de, value: 'Automatic' }]. Harmless for display, but the array no longer tells the truth about what language the string is in.
Client-side language switching no longer re-localizes option labels. The dashboard consumer (select-with-options.tsx) does label.find(t => t.languageCode === displayLanguage). At fetch time languageCode === displayLanguage, so it matches and works today. But a cache-then-render-at-a-different-language flow would now fall through to label[0] instead of picking the right language from a full array. This is consistent with how description and arg label already resolve to a single string server-side, so it's a narrowing rather than a regression — just want to confirm no admin-ui/dashboard flow relies on receiving all languages for option labels in one fetch. (The mutation-safety e2e covers cross-request isolation well, but not this cache-then-switch angle.)

Minor

if (fromCatalog) in localizeString is a truthiness check, so an intentionally empty-string catalog entry is treated as "no translation" and a catalog can't blank out an inline string. Almost certainly intended — just flagging it's truthiness, not !== undefined.
The PR ships the mechanism with no populated core catalogs (src/i18n/messages/<lng>.json aren't in the diff), so every core op still resolves to its inline strings until the tooling is run and committed. Assuming that's the intended "plumbing now, content follow-up" split — worth a line in the description confirming it.
Doc nit: a few docblocks / the guide say getTranslationKeys() is used to "print" the key paths — it returns them.
Test gap: getTranslationKeys is covered for a normal op and the no-defType case, but not for an arg whose ui has no options (non-select) — getUiOptions handles it, but there's no direct assertion that such an arg contributes no option keys.

Thanks — nice mechanism, and the "no user-visible change, translations are a follow-up" framing makes it easy to reason about.

Relates to #4820

sonarqubecloud · 2026-08-04T09:52:14Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

michaelbromley added 4 commits July 31, 2026 13:52

feat(core): Resolve configurable operation strings from i18n catalogs

06bf099

Relates to #4820

chore(core): Add translation tooling for configurable operations

6e2a404

Relates to #4820

docs: Document configurable operation translations

f3fa0e2

Relates to #4820

chore(core): Fix import grouping in configurable operation registry

6d9a2b8

vendure-ci-automation-bot Bot added 3 commits July 31, 2026 11:57

docs: Regenerate manifest.json

7e236fd

docs: Generate docs for source changes

decdfd5

docs: Regenerate manifest.json

de37128

vercel Bot deployed to Preview July 31, 2026 12:02 View deployment

Merge remote-tracking branch 'origin/minor' into columbia

5ae3989

vercel Bot deployed to Preview July 31, 2026 14:04 View deployment

michaelbromley and others added 3 commits July 31, 2026 16:41

refactor(core): Assign configurable operation type at bootstrap

4c9a223

Relates to #4820

docs: Generate docs for source changes

45eb08b

docs: Regenerate manifest.json

177584b

vercel Bot deployed to Preview July 31, 2026 14:45 View deployment

grolmus reviewed Aug 3, 2026

View reviewed changes

chore(core): Fail loudly when translation tooling loses an operation

ffe8c49

Relates to #4820

vercel Bot deployed to Preview August 4, 2026 09:51 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(core): Resolve configurable operation strings from i18n catalogs - #5079

feat(core): Resolve configurable operation strings from i18n catalogs#5079
michaelbromley wants to merge 12 commits into
minorfrom
columbia

michaelbromley commented Jul 31, 2026 •

edited by blacksmith-sh Bot

Loading

Uh oh!

vendure-developer-hub Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 31, 2026 •

edited

Loading

Review skipped

Uh oh!

github-actions Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

grolmus left a comment

Uh oh!

sonarqubecloud Bot commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

michaelbromley commented Jul 31, 2026 • edited by blacksmith-sh Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approach

Resolution order

Why the lookup bypasses t()

Changes

Behaviour changes

Testing

Follow-ups

Uh oh!

vendure-developer-hub Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

github-actions Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grolmus left a comment

Choose a reason for hiding this comment

Worth confirming: ui.options[].label shape narrowing

Minor

Uh oh!

sonarqubecloud Bot commented Aug 4, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

michaelbromley commented Jul 31, 2026 •

edited by blacksmith-sh Bot

Loading

Why the lookup bypasses `t()`

vendure-developer-hub Bot commented Jul 31, 2026 •

edited

Loading

vercel Bot commented Jul 31, 2026 •

edited

Loading

coderabbitai Bot commented Jul 31, 2026 •

edited

Loading

github-actions Bot commented Jul 31, 2026 •

edited

Loading

Worth confirming: `ui.options[].label` shape narrowing