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:

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

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

<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¶

PHP publica la config de runtime en la página como window.__MAGE_OBSIDIAN_I18N__ = { locale, dictionaryUrl } (lo emite una vez el bloque I18nRuntime).
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.
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:

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

Escanea cada módulo y tema compatible y fusiona lo que encuentra 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.

Fuente	Qué se recolecta
`.vue`, `.ts`, `.js`	Llamadas `$t('…')`, incluida la fachada `i18n.$t('…')`
`.twig`	Llamadas `__('…')`

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

Qué acepta el lector de Twig¶

Las plantillas Twig se leen con un escáner léxico, nunca se ejecutan, así que el recolector no necesita un motor Twig: funciona esté o no instalado el módulo Twig opcional. Solo mira dentro de los bloques {{ … }} y {% … %} de Twig, y toma una frase únicamente cuando el primer argumento es un literal completo:

{{ __('Add to Cart') }}                        {# se recolecta #}
{{ __("Items %1 to %2 of %3", first, last, n) }}  {# se recolecta; los argumentos no son frases #}
{{ __('It\'s on its way') }}                    {# se recolecta; los escapes se resuelven #}

{# {{ __('Commented out') }} #}                {# no se recolecta: es un comentario Twig #}
{% verbatim %}{{ __('Shown as an example') }}{% endverbatim %}  {# no se recolecta #}
{{ __(label) }}                                {# no se recolecta: es dinámico #}
{{ __('Hello ' ~ name) }}                      {# no se recolecta: está concatenado #}
{{ hint("write __('x') here") }}               {# no se recolecta: es una cadena, no una llamada #}

Una llamada repartida en varias líneas se lee completa. El texto fuera de un bloque Twig es contenido de la página, así que un __('…') escrito ahí nunca se recolecta.

Idempotencia y propiedad¶

Cada componente escribe en su propio i18n/<locale>.csv: las frases de un tema nunca aterrizan en el diccionario de un módulo. Las filas existentes se conservan tal cual —una frase ya traducida nunca se sobrescribe, y una fila cuya frase ya no aparece en las fuentes nunca se elimina—. Ejecutar el comando dos veces sobre las mismas fuentes produce archivos idénticos byte a byte.

De punta a punta¶

# 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

Los locales son exactos¶

Magento resuelve un diccionario por el código de locale exacto de la vista de tienda. Un tema que distribuye i18n/es_ES.csv traduce una tienda configurada como es_ES y ninguna otra: una tienda en es_VE, es_MX o es_AR lee i18n/es_VE.csv, i18n/es_MX.csv o i18n/es_AR.csv, y cae a la frase sin traducir cuando ese archivo no existe. No hay fallback implícito de es_VE a es_ES.

Para adaptar un diccionario distribuido al locale que tu tienda usa de verdad:

# 1. Genera el diccionario del locale exacto
bin/magento mage-obsidian:i18n:collect --locale=es_VE

# 2. Siémbralo desde el más cercano que se distribuya, conservando las filas que ya tradujiste.
#    Copia hacia tu propio tema o módulo, nunca dentro del paquete vendor.
#    (es_ES.csv y es_VE.csv llevan las mismas frases; solo cambian las traducciones.)

# 3. Ajusta la redacción y despliega ese locale
bin/magento setup:static-content:deploy es_VE

Como el recolector nunca sobrescribe una traducción existente, puedes copiar un diccionario, editar las filas que necesiten redacción regional y volver a ejecutar el comando para incorporar frases nuevas sin perder los cambios. Un override colocado en tu propio tema gana sobre el que distribuye el paquete, igual que cualquier archivo de tema.

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¶

Islas Vue — el runtime que cablea el plugin de i18n.
Componentes Vue — autoría de componentes.