[1.x] fix: resolve translation references in implicitly-loaded fallback catalogues

[gianniguida]

Backport of #5023 to 1.x. See that PR for the full write-up; summary below.

Symptom

Compiled locale JS assets (e.g. admin-en.js) sometimes contain unresolved translation references — literal values like:

"core.admin.nav.dashboard_button":"=> core.admin.dashboard.title"

so the admin UI displays raw => core.admin.… strings. Only the fallback locale (en) is affected; the poisoned compiled asset persists until a cache flush (its revision exists, so it is never recompiled). Found in production on Flarum 1.8.19 (community.sbb.ch) and confirmed end-to-end there: touching getCatalogue('de') before recompiling the English admin locale asset deterministically produces the broken asset; removing that single line produces a clean one.

Root cause

Translator::getCatalogue() gated =>-reference resolution on a locale-keyed flag (! isset($this->catalogues[$locale])). But Symfony's Translator::loadFallbackCatalogues() (symfony/translation v5.4), when loading any other locale, pre-stores the original en catalogue in $this->catalogues['en'] while attaching only a copy to the requesting catalogue. Loading de first therefore stores a raw, never-parsed en original; a later getCatalogue('en') finds the locale already set, skips parsing, and returns it raw. Flarum\Frontend\AddTranslations then compiles the literal => … strings into the locale JS asset.

Deterministic repro (locale de, fallback ['en'], non-debug, cache dir — mirroring LocaleServiceProvider):

$t->getCatalogue('en');
$t->getCatalogue('en')->get('core.admin.nav.dashboard_button'); // "Dashboard"            ✔

// fresh translator, fresh cache:
$t->getCatalogue('de');   // implicit fallback load of 'en'
$t->getCatalogue('en')->get('core.admin.nav.dashboard_button'); // "=> core.admin.dashboard.title"  ✘

Fix

Track parsed state per catalogue object instead of per locale name, and walk the fallback chain on every getCatalogue() call — the raw stored original and its parsed copy share a locale name, so a locale-keyed flag cannot distinguish them. Per-object tracking parses each catalogue object exactly once; parseCatalogue() is unchanged.

Differences from the 2.x fix, for PHP 7.3 compatibility: SplObjectStorage (contains()/attach()) instead of WeakMap, untyped private property.

Tests

New TranslatorReferenceResolutionTest (PHPUnit 9 style), wired like LocaleServiceProvider:

• en loaded directly → resolved (regression guard).
• en first loaded implicitly as de's fallback, then requested directly → resolved (failed before this fix with '=> bar' vs 'Resolved').
• de's attached fallback copy resolved, via getFallbackCatalogue() and trans() fallthrough (regression guard).

Full unit suite and PHPStan pass on 1.x.

Context

Surfaced while working on FriendsOfFlarum/redis#34 — multi-instance cache invalidation increases recompile frequency, raising exposure — but reproducible on a bare single-instance install.

🤖 Generated with Claude Code

[gianniguida]

Adding context on why I think this qualifies under the 1.x critical-fixes-only policy, with what we've learned running it in production since the PR was opened.

It's user-visible breakage that doesn't heal itself. Once the raw => core.… strings are baked into admin-en.js / forum-en.js, the asset's revision exists, so core never recompiles it. English users see the broken UI until an admin clears the cache — and the very next admin action can re-poison it. On our forum this presented as "the admin panel is unreadable in English after saving any setting", which was escalated as a production incident before we understood it was core.

It's not a multi-instance edge case. The trigger is simply: a non-English catalogue gets compiled before the English one is touched, in the same request. That happens on a single-instance install whenever the site's default locale isn't en and catalogues have just been cleared — i.e. right after cache:clear, an extension toggle, or a settings save (Extend\Locales::onEnable/onDisable → LocaleManager::clearCache()). Every multilingual forum whose default locale isn't English is exposed on every admin action. Multi-instance setups just roll the dice N times instead of once.

There is no admin-level workaround. The only mitigation short of this patch is site-level PHP: a middleware that calls getCatalogue('en') before anything else in the request (we ship one, with a control test that reproduces the bug against the installed core). That's not something a forum operator can do, and it costs an extra catalogue load + parse on every non-English request forever.

The fix is already accepted on 2.x (#5023, merged 2026-09-02). This backport is the same logic with SplObjectStorage in place of WeakMap for PHP 7.3; parseCatalogue() itself is untouched, and the new test fails before / passes after. Risk surface is one method in Translator.

Happy to adjust anything for 1.x conventions. If a 1.8.20 is on the table at all, I'd argue this belongs in it: deterministic, silent, persists until manual intervention, and every non-English-default forum is affected.