feat: decouple component library from vue-i18n

[Arnold Stoba (arnoldstoba)]

Closes #1070

What?

Make the component library translation-solution agnostic: it no longer depends on vue-i18n. Components use an internal i18n layer with an optional host adapter, bundled EN/DE snippets, a reactive locale, and predictable fallbacks. Hosts and plugins can now override Meteor snippets and add languages.

⚠️ Breaking change → ships as a major (6.0.0).

Why?

Meteor declared vue-i18n@^9 as a hard dependency. This forced a specific library and version on every consumer. Apps on a newer vue-i18n (e.g. the Admin on v10, a Nuxt app on @nuxtjs/i18n) ended up with two vue-i18n instances — Meteor's useI18n() resolved a different instance than the host's, breaking translations.

We chose an internal layer + adapter (over simply bumping vue-i18n) because it removes the forced dependency entirely and is the only way to be truly version- and library-agnostic. It also unlocks snippet overriding/extension, which the old per-component local scope did not allow.

How?

• Removed vue-i18n from dependencies and the build externals (nothing in the bundle imports it anymore).
• Added useMeteorI18n + createMeteorI18nPlugin({ adapter?, messages? }) (source under src/i18n/). Resolution order: host adapter → override registry → bundled locale → bundled English → key, with a locale fallback chain (de-DE → de → en, en-US → en).
• Snippets now have public keys mt.<component>.<key> so hosts/plugins can target them.
• Shipped createVueI18nAdapter (accepts a createI18n instance or a composer, so it also works with @nuxtjs/i18n).
• Migrated all 34 translated components; updated tests, Storybook (EN/DE toggle), README, developer docs, and the example apps.

Testing?

• Unit tests cover the resolution order, locale chain, pluralization, and overrides (655 passing).
• lint:all, lint:types, and the production build all pass; the bundle contains 0 vue-i18n imports.
• A separate manual verification guide exists for validating the Admin integration end-to-end before bumping shopware/shopware.

Anything Else?

Consumer migration

Zero setup now works — components render bundled English out of the box and no longer throw without vue-i18n:

- npm i @shopware-ag/meteor-component-library vue-i18n
+ npm i @shopware-ag/meteor-component-library

To drive the locale reactively / let your app provide translations, install the plugin:

// already using vue-i18n (or @nuxtjs/i18n):
import { createMeteorI18nPlugin, createVueI18nAdapter } from "@shopware-ag/meteor-component-library";
app.use(i18n);
app.use(createMeteorI18nPlugin({ adapter: createVueI18nAdapter(i18n) }));

// or, standalone with bundled snippets only:
app.use(createMeteorI18nPlugin());

Override wording / add a language (host-first, or via the registry):

app.use(createMeteorI18nPlugin({
  messages: { fr: { mt: { pagination: { nextPage: "Suivant" } } } },
}));

💥 Breaking changes

1. vue-i18n is no longer a dependency. Meteor no longer installs it for you; if your app uses it, declare it yourself.
2. Translations are no longer auto-wired from a shared vue-i18n instance. To get non-English / reactive locale in Meteor components you must install createMeteorI18nPlugin (with an adapter). Without it, Meteor renders English instead of throwing.
3. Snippet keys for the previously global-scoped components were renamed (mt- → mt.): mt-field-error.* → mt.field-error.*, mt-text-editor*.* → mt.text-editor*.*, mt-action-menu-item.* → mt.action-menu-item.*. Plugins overriding these must update the key path. The Admin's global.error-codes.* keys are unchanged.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
meteor-component-library	Ready	Preview, Comment	Jun 29, 2026 1:13pm