Discussion: Implementing Reactive i18n for Wizard in Grav 2 Admin-Next

[pmoreno-rodriguez]

I've been working on internationalization (i18n) support for the git-sync wizard and have created a branch: feat/wizard-i18n-admin2.

Current Status

✅ Grav 1.7 + Admin (Classic)

• Wizard translations work perfectly
• Language switching displays correct translations
• All translation keys properly implemented in en.yaml / es.yaml

❌ Grav 2 + Admin-Next/Admin2

• Translation infrastructure is in place (language files, templates)
• However, wizard modal doesn't update when user changes language in the SPA
• The issue: translations are resolved at initialization time, not reactively

What's Complete

• Comprehensive translation keys in languages/en.yaml and languages/es.yaml
• Updated templates: modal-wizard.html.twig, modal-reset.html.twig, etc.
• Enhanced admin-next/fields/enc-password.js component
• Blueprint configuration using proper i18n keys

What's Needed

The Admin-Next implementation requires changes to handle reactive language switching in the SPA:

• Likely changes needed in git-sync.php (onApiFloatingWidgets/onApiPluginPageInfo methods)
• Likely changes needed in admin-next/widgets/git-sync.js (translation lookup during runtime)
• Possibly both files need coordination

Feel free to check out the feat/wizard-i18n-admin2 branch in my fork to review the current
foundation work. We could continue investigating and testing solutions there collaboratively to
find the best approach following Grav 2 best practices.

Any guidance on how other plugins handle reactive

Thanks for your time!

[rhukster]

Good writeup, and thanks for pushing on this. The premise is half right: Admin-Next's i18n is fully reactive and it does expose a runtime bridge to plugin code, but there was a bug underneath that meant it wouldn't have worked for you even with the right calls. That's now fixed, so the path is clear.

The bridge you want is window.__GRAV_I18N. It gives you t(), tHtml(), has(), locale, dir and subscribe(), and it's documented in docs/i18n.md in the admin-next repo. Language switching happens in place with no reload, so a widget just subscribes and re-renders.

Your enc-password.js reads this._field.i18n and window.__GRAV_CONFIG.i18n. Neither exists: the serialized blueprint field has no i18n map, and the global is window.__GRAV_CONFIG__ with trailing double underscores, which carries no i18n key either. So your t() was always returning its fallback and never reacting. That's the whole of your "resolved at initialization time" symptom.

The bug underneath. GET /translations/{lang} was shipping no plugin strings at all, and no Grav core strings either:

/api/v1/translations/en-US?prefix=ICU.ADMIN_NEXT.SETTINGS  -> 140
/api/v1/translations/en-US?prefix=GRAV                     -> 0
/api/v1/translations/en-US?prefix=PLUGIN_FORM              -> 0

normalizeLangCode() aliases en to en-US, and core's flattenByLang() is a bare bucket read with no region fallback. Only admin2 ships an en-US.yaml; core and every plugin ship en.yaml, which landed in a bucket nothing read. So __GRAV_I18N.t('PLUGIN_GIT_SYNC.WIZARD_TITLE') humanized to "Wizard Title".

Fixed in grav-plugin-api on develop: the dictionary now merges a code with its primary subtag, so en-US reaches en and ru-RU reaches ru, with the requested code winning. Same numbers now read 140 / 137 / 102, and your own keys come back as 73 under ICU.PLUGIN_GIT_SYNC.

Two things to do on your side.

For the wizard body, in admin-next/widgets/git-sync.js:

const I18N = () => window.__GRAV_I18N;
function t(key, fallback, params) {
  const b = I18N();
  if (!b) return fallback;
  const full = 'PLUGIN_GIT_SYNC.' + key;
  return b.has(full) ? b.t(full, params) : fallback;
}

The has() check matters. Without it a missing key humanizes to "Wizard Title" rather than falling back to your real English string. Then subscribe in open() and unsubscribe in close():

this._i18nUnsub = I18N()?.subscribe?.(() => this._render());

Your _render() already rebuilds innerHTML wholesale on every state change, so that's all the reactivity you need.

For strings that travel through onApi* payloads, resolve them in PHP instead. onApiFloatingWidgets, onApiPluginPageInfo and onApiMenubarItems render their labels raw, so a bare PLUGIN_GIT_SYNC.FOO key shows up as the literal key. The sidebar and blueprints get translated server-side, but those three don't. Use the adminString() helper already in git-sync.php for the widget label, the plugin page title and the action labels, which are all still hardcoded English.

On your branch specifically. The dual-block YAML (flat PLUGIN_GIT_SYNC: plus a mirrored ICU: block) is exactly right and necessary. Namespace and flat keys are right too. Four things to change:

• WIZARD_NEXT: 'Next →' bakes a direction into the string and will point the wrong way in RTL. Put the arrow in markup and let dir handle it.
• WIZARD_STEP: 'Step' plus WIZARD_OF: 'of' won't reorder for languages that need it. Since these are ICU keys, make it one string: WIZARD_STEP_OF: 'Step {current} of {total}'.
• Several values embed raw <strong>, <code> and <a href>. Use tHtml() and write them as markdown instead, which gets sanitized on the way out.
• "GitSync" / "Git Sync" inside translated bodies should stay literal or become a placeholder, rather than being open to translation.

You'll need the api plugin from develop to see any of it working. Open a PR whenever you're ready and I'll review it.

[pmoreno-rodriguez]

Thanks for the detailed guidance. I've implemented your recommendations on the feat/wizard-i18n-admin2 branch, and everything is working well. Here's what I've done:

✅ Implemented:

• Added const I18N = () => window.__GRAV_I18N bridge and t() / tHtml() helpers with proper has() checks in admin-next/widgets/git-sync.js
• Subscribed to i18n changes in open() and unsubscribed in close() for reactive re-rendering
• Wrapped admin UI strings (wizard, synchronize, reset, save labels) with adminString() helper in git-sync.php for onApiPluginPageInfo()
• Added _syncDir() to keep text direction (LTR/RTL) in sync with the current locale
• Added WIZARD_STEP: 'Step' translation key (was missing for Grav 1.7)

✅ Verified working:

• Wizard modal updates reactively when language changes in Admin-Next
• RTL arrow handling on WIZARD_NEXT button works correctly
• Markdown formatting in Admin and Admin-Next renders properly
• Grav 1.7 wizard displays correctly

❌ One remaining issue:

The action buttons (Wizard, Synchronize, Reset Local Copy) in the plugin page header don't update when language changes. The issue is in Admin-Next's src/routes/plugin/[slug]/+page.svelte: the definition object (containing action labels) is loaded once in loadPage() and never refreshed when i18n.locale changes.

Question: Should I add a $effect in Admin-Next to refresh definition when the locale changes? Or do you have a different approach in mind?

Ready to open a PR when you give the go-ahead.

[rhukster]

Proceed with PR. Cheers.