Skip to content

Internationalization (i18n)

MageObsidian translates phrases in the Vue/ESM layer with the same dictionary as the rest of the storefront — Magento's native per-locale js-translation.json. You write $t('…') in components exactly like Magento's $t / $.mage.__, and the standard CSV → language-pack flow applies.

Translating in Components

The i18n plugin (obsidianI18n) is wired into every Vue island automatically — you don't register anything. In templates, use $t:

1
2
3
4
<template>
    <button>{{ $t('Add to cart') }}</button>
    <p>{{ $t('Hello %1', userName) }}</p>
</template>

In <script setup>, use the useTranslate() composable:

1
2
3
4
5
6
7
<script setup>
import { useTranslate } from 'MageObsidian_ModernFrontend::js/i18n';

const { t, locale } = useTranslate();
const label = t('Items in cart: %1', count);
// `locale` is the active store locale, e.g. "en_US"
</script>

%1, %2, … are positional placeholders, substituted in order. An out-of-range placeholder is left untouched, so a malformed phrase never throws.

How It Works

  1. PHP publishes the runtime config on the page as window.__MAGE_OBSIDIAN_I18N__ = { locale, dictionaryUrl } (emitted once by the I18nRuntime block).
  2. The browser fetches the dictionary from dictionaryUrl — Magento's native js-translation.json for the active locale — once, shared across every mounted app, held reactively so $t re-renders as soon as it resolves.
  3. A phrase is looked up in the dictionary, falling back to the phrase itself when absent; then placeholders are interpolated.

Because the dictionary is Magento's own js-translation.json, translations come from the same CSV / language packs as the rest of the storefront — there is no parallel translation system.

Collecting Phrases

$t('…') calls written in .vue files are not visible to Magento's PHP-based phrase scanners, so MageObsidian ships a collector:

1
bin/magento mage-obsidian:i18n:collect --locale=en_US

It scans the $t('…') phrases in the .vue sources of every compatible module and theme and merges them into that component's standard Magento dictionary, i18n/<locale>.csv. New phrases default to themselves, so they flow into js-translation.json through the native static-content deploy once translated.

Option Description
--locale Locale of the CSV to write (default en_US).

End-to-end

1
2
3
4
5
6
7
# 1. Write $t('...') phrases in your .vue components
# 2. Collect them into i18n/<locale>.csv
bin/magento mage-obsidian:i18n:collect --locale=en_US

# 3. Translate the CSV rows (or ship a language pack)
# 4. Deploy — js-translation.json is regenerated with the translations
bin/magento setup:static-content:deploy

Key Notes

  • $t works in any island component out of the box — the plugin is already installed by the island runtime.
  • The dictionary is Magento's native js-translation.json; no separate i18n backend.
  • If the config global is absent (e.g. no islands on the page), the layer degrades to passthrough — phrases render as written.
  • Always run mage-obsidian:i18n:collect after adding new $t('…') phrases so they reach the CSV and, after deploy, the dictionary.

Next Steps