Feature: Updating Listreners, Separating Logic from listeners, Queuing Policies

src/Localization/Listeners/FlushLanguageCache.php

@@ -2,12 +2,21 @@
 
 namespace Modules\Core\Localization\Listeners;
 
+use Illuminate\Contracts\Queue\ShouldQueue;
 use Modules\Core\Localization\Events\LanguageCreated;
 use Modules\Core\Localization\Events\LanguageDeleted;
 use Modules\Core\Localization\Events\LanguageUpdated;
 use Modules\Core\Localization\Services\LanguageCache;
 
-class FlushLanguageCache
+/**
+ * Queued — the only reader of this cache is Modules\Core\Localization\
+ * Middleware\LocaleMiddleware on a LATER storefront request, never the
+ * same admin request that edited/created/deleted the Language row (that
+ * request redirects to a fresh page read straight from the DB, not this
+ * cache). A few seconds of eventual consistency before the queue worker
+ * picks this up is an acceptable trade for not blocking the admin save.
+ */
+class FlushLanguageCache implements ShouldQueue
 {
     public function __construct(private readonly LanguageCache $languages) {}
 

src/Localization/Listeners/FlushTranslationCache.php

@@ -2,6 +2,7 @@
 
 namespace Modules\Core\Localization\Listeners;
 
+use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Support\Facades\Cache;
 use Modules\Core\Localization\Events\TranslationCreated;
 use Modules\Core\Localization\Events\TranslationDeleted;
@@ -15,8 +16,13 @@ use Spatie\TranslationLoader\LanguageLine;
  * `group`/`key` (the old group's cached array never gets told a row left it).
  * This listener flushes every group+locale combination touched by either the
  * old or new state so nothing can remain stale.
+ *
+ * Queued — this cache backs `__('storefront.*')` lookups on a LATER
+ * storefront request, never the same admin request that just edited the
+ * translation (Filament redirects to a fresh index read straight from the
+ * DB, not this cache). Safe to let a queue worker pick up.
  */
-class FlushTranslationCache
+class FlushTranslationCache implements ShouldQueue
 {
     public function handle(TranslationCreated|TranslationUpdated|TranslationDeleted $event): void
     {

src/Localization/Listeners/LogTranslationActivity.php

@@ -2,6 +2,7 @@
 
 namespace Modules\Core\Localization\Listeners;
 
+use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Support\Arr;
 use Modules\Core\Localization\Events\TranslationCreated;
 use Modules\Core\Localization\Events\TranslationDeleted;
@@ -9,7 +10,12 @@ use Modules\Core\Localization\Events\TranslationUpdated;
 use Modules\Core\Logging\ActivityLogService;
 use Spatie\TranslationLoader\LanguageLine;
 
-class LogTranslationActivity
+/**
+ * Queued — a pure audit-log write with no same-request reader (Filament
+ * redirects to a fresh index page after save, which doesn't read the
+ * activity log at all).
+ */
+class LogTranslationActivity implements ShouldQueue
 {
     public function __construct(
         private readonly ActivityLogService $activityLog,

src/Localization/Listeners/MigrateTranslationsForRenamedLanguage.php

@@ -2,6 +2,7 @@
 
 namespace Modules\Core\Localization\Listeners;
 
+use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Support\Facades\Cache;
 use Modules\Core\Localization\Events\LanguageUpdated;
 use Spatie\TranslationLoader\LanguageLine;
@@ -12,8 +13,15 @@ use Spatie\TranslationLoader\LanguageLine;
  * getTranslationsForGroup($newCode, ...) would silently return nothing for
  * that locale even though the translated content still exists. Move the
  * text.{oldCode} key to text.{newCode} on every affected row instead.
+ *
+ * Queued — this walks every LanguageLine row containing the old locale key
+ * with no upper bound, and nothing in the same request needs the migration
+ * to have completed before responding (a rename is a rare admin action;
+ * the affected storefront locale is briefly unavailable until the queue
+ * worker finishes, the same window that already exists before this
+ * listener runs at all).
  */
-class MigrateTranslationsForRenamedLanguage
+class MigrateTranslationsForRenamedLanguage implements ShouldQueue
 {
     public function handle(LanguageUpdated $event): void
     {