Multilingual UIs: an i18n Pattern Without vue-i18n or react-intl

1. Why a heavy i18n framework is often overkill for Alpine

Libraries like vue-i18n or react-intl bring their own build step, their own runtime, and a full concept for locale detection, formatting, and message catalogs, which makes sense in a Vue or React project with hundreds of components. In an Alpine component that typically holds only a few dozen text strings and does not require a dedicated build system anyway, that overhead is out of proportion with the actual need.

On top of that, in a Magento context most translations already ship server-side through Magento's translation files and store views. The client-side Alpine component often only needs to translate a handful of dynamic text fragments that change at runtime, such as a status message or a tooltip, for which a simple object lookup is entirely sufficient.

2. Basic pattern: a translation object plus Alpine.store()

The core of the pattern is a global Alpine store that holds two things: the currently active locale and a nested object with all translations per locale code. A t(key) translation function reads the current locale from the store and returns the matching text from the nested object, falling back to the key itself if a translation is missing, so a missing string never renders as an empty gap in the UI.

Because the store is registered globally, any Alpine component in the markup can reach the same translation function through $store.i18n.t('key'), with no need to pass data explicitly from component to component. On a small scale, that mirrors exactly the principle vue-i18n follows with its global $t function, just without plugin registration and without a separate compilation step for the messages.

document.addEventListener('alpine:init', () => {
  Alpine.store('i18n', {
    locale: document.documentElement.lang || 'en',
    messages: {
      de: {
        addToCart: 'In den Warenkorb',
        itemsInCart: '{count} Artikel im Warenkorb',
      },
      en: {
        addToCart: 'Add to cart',
        itemsInCart: '{count} items in cart',
      },
    },

    t(key, params = {}) {
      const dict = this.messages[this.locale] || this.messages.en;
      let text = dict[key] ?? key;
      for (const [param, value] of Object.entries(params)) {
        text = text.replace(`{${param}}`, value);
      }
      return text;
    },
  });
});

3. Implementing runtime language switching

Since locale is a reactive store property, a simple x-on:click that sets $store.i18n.locale to a new locale code is enough to make every component bound through x-text="$store.i18n.t('key')" re-render automatically. No manual page reload and no re-initializing of Alpine components is needed, because Alpine's reactivity system propagates the change directly.

In a Magento shop with multiple store views, the actual language switch usually stays solved server-side, because switching the store view can also change prices, tax, and availability, which a purely client-side approach cannot represent. The Alpine store shown here therefore suits isolated widgets that need to react before the next page load, independent of a store-view switch, such as a cookie banner or a language preview widget.

4. Organizing nested keys and namespaces

Once a project grows beyond a handful of translations, it pays off to organize them by namespace, such as cart, checkout, or search, as a nested object level instead of one single flat key-value object. That avoids naming collisions between similar terms used in different contexts, for example a word like remove that might need different phrasing in the cart versus the wishlist.

The t() function can easily be extended to resolve a dot-separated path such as cart.remove, by splitting the key on every dot and navigating recursively through the nested object. This approach stays a simple object lookup with no external dependency, but scales considerably better to several hundred text strings before switching to a real i18n library becomes necessary at all.

5. Handling plural forms without a library

Real i18n libraries resolve plural forms through the ICU MessageFormat standard, which distinguishes several categories such as one, few, many, and other for languages with complex plural rules like Polish or Arabic. For a lightweight Alpine pattern that primarily serves German and English, a simple singular-plural distinction is usually enough, driven by a small helper function that picks the right key based on the passed-in number.

It matters to know this boundary deliberately: as soon as a target language with more differentiated plural rules needs support, for example Russian with three distinct plural forms depending on the last digit, the simple singular-plural distinction hits its limit and switching to a library with full ICU support becomes necessary, instead of branching the logic by hand ever further.

// simple singular/plural distinction, enough for DE/EN
plural(count, key) {
  const dict = this.messages[this.locale] || this.messages.en;
  const variant = count === 1 ? `${key}.one` : `${key}.other`;
  const text = variant.split('.').reduce((obj, part) => obj?.[part], dict) ?? key;
  return text.replace('{count}', count);
}

// usage in markup:
// <span x-text="$store.i18n.plural(itemCount, 'cart.items')"></span>

6. Placeholders and interpolation in translation strings

The replace-based interpolation shown in the basic pattern, using curly braces like {count}, covers the vast majority of practical cases where a single dynamic value has to be inserted into an otherwise static sentence. For multiple placeholders in the same string, the same loop over Object.entries works fine, as long as the placeholder names within the translation text are unique.

What it does not cover is context-dependent grammar, where a placeholder's word form would need to change based on the surrounding sentence structure, which occasionally happens in inflected languages like German. For that case, the usual fallback is to define separate full sentence variants as their own translation keys, rather than trying to model grammar generically through placeholders.

7. Persisting the language choice via localStorage and server sync

For a language choice made inside the Alpine store to survive a page change, the current locale code additionally gets mirrored into localStorage and read back from there during the store's init(), before falling back to the value from document.documentElement.lang. That keeps a deliberate user decision, for example inside an embedded widget, intact across a reload.

For the actual, binding language switch of the whole shop, Magento's server-side store view routing stays the authoritative source, because it additionally carries correct prices, availability, and SEO-relevant hreflang links, which a plain browser-side localStorage flag cannot provide. The Alpine store should therefore treat the value from document.documentElement.lang as the primary source and use localStorage only as a secondary addition for isolated widgets.

8. Limits of the lightweight approach compared to real i18n libraries

A simple translation object with Alpine.store covers neither date formatting according to locale conventions nor number and currency formatting, for which the browser's native Intl API should be used in practice anyway, independent of any i18n pattern. Neither of the two functions shown handles automatic text direction detection for RTL languages like Arabic or Hebrew either, that requires its own dir-attribute logic.

The lightweight approach also lacks any form of extraction tooling that real i18n libraries provide to automatically find missing translation keys in the code, or to export translation files for an external localization vendor. In a project with a few dozen keys that can still be maintained by hand, but with several hundred keys spread across many components, this missing tooling quickly becomes the actual bottleneck.

9. When switching to a real i18n library pays off

A clear signal for switching is when the number of translation keys grows past a mid two-digit to low three-digit count, more than two or three languages with complex plural rules need support, or a translation team without developer knowledge needs to work on the text independently. In all of these cases, the extra overhead of a real library outweighs the loss of simplicity.

As long as an Alpine widget stays isolated, holds a few dozen text strings, and primarily serves languages with simple plural rules like German and English, the store pattern shown here remains the more pragmatic choice, since it requires no extra build step and fits seamlessly into an existing Hyvä codebase without adding a new dependency to the project.

10. Summary

11. FAQ: Lightweight i18n With Alpine: Key Takeaways