Saltar a contenido

Internacionalización (i18n)

MageObsidian traduce frases en la capa Vue/ESM con el mismo diccionario que el resto de la tienda —el js-translation.json nativo de Magento por locale. Escribes $t('…') en los componentes exactamente como el $t / $.mage.__ de Magento, y aplica el flujo estándar CSV → language pack.

Traducir en Componentes

El plugin de i18n (obsidianI18n) viene cableado en cada isla Vue automáticamente —no registras nada. En templates, usa $t:

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

En <script setup>, usa el composable useTranslate():

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` es el locale activo de la tienda, p. ej. "en_US"
</script>

%1, %2, … son placeholders posicionales, sustituidos en orden. Un placeholder fuera de rango se deja intacto, así que una frase mal formada nunca lanza error.

Cómo Funciona

  1. PHP publica la config de runtime en la página como window.__MAGE_OBSIDIAN_I18N__ = { locale, dictionaryUrl } (lo emite una vez el bloque I18nRuntime).
  2. El navegador descarga el diccionario desde dictionaryUrl —el js-translation.json nativo de Magento para el locale activo— una sola vez, compartido entre todas las apps montadas, guardado de forma reactiva para que $t se re-renderice en cuanto resuelve.
  3. Una frase se busca en el diccionario, con fallback a la propia frase si falta; luego se interpolan los placeholders.

Como el diccionario es el propio js-translation.json de Magento, las traducciones vienen del mismo CSV / language packs que el resto de la tienda —no hay un sistema de traducción paralelo.

Recolectar Frases

Las llamadas $t('…') escritas en archivos .vue no son visibles para los escáneres de frases de Magento (basados en PHP), así que MageObsidian incluye un recolector:

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

Escanea las frases $t('…') en las fuentes .vue de cada módulo y tema compatible y las fusiona en el diccionario estándar de Magento de ese componente, i18n/<locale>.csv. Las frases nuevas se defaultean a sí mismas, así que fluyen a js-translation.json mediante el deploy nativo de contenido estático una vez traducidas.

Opción Descripción
--locale Locale del CSV a escribir (por defecto en_US).

De punta a punta

1
2
3
4
5
6
7
# 1. Escribe frases $t('...') en tus componentes .vue
# 2. Recoléctalas en i18n/<locale>.csv
bin/magento mage-obsidian:i18n:collect --locale=en_US

# 3. Traduce las filas del CSV (o entrega un language pack)
# 4. Deploy — js-translation.json se regenera con las traducciones
bin/magento setup:static-content:deploy

Notas Clave

  • $t funciona en cualquier componente de isla de fábrica —el plugin ya lo instala el runtime de islas.
  • El diccionario es el js-translation.json nativo de Magento; sin backend de i18n aparte.
  • Si el global de config no está presente (p. ej. una página sin islas), la capa degrada a passthrough —las frases se renderizan tal cual.
  • Corre siempre mage-obsidian:i18n:collect tras añadir nuevas frases $t('…') para que lleguen al CSV y, tras el deploy, al diccionario.

Próximos Pasos