rails_error_dashboard 0.8.4 → 0.9.0

data/app/helpers/rails_error_dashboard/application_helper.rb

@@ -183,7 +183,8 @@ module RailsErrorDashboard
     # @param format [Symbol] Format preset (:full, :short, :date_only, :time_only, :datetime)
     # @param fallback [String] Text to show if time is nil
     # @return [String] HTML safe span with data attributes for JS conversion
-    def local_time(time, format: :full, fallback: "N/A")
+    def local_time(time, format: :full, fallback: nil)
+      fallback ||= red_t("red.common.not_available")
       return fallback if time.nil?
 
       # Convert to UTC if not already
@@ -192,18 +193,13 @@ module RailsErrorDashboard
       # ISO 8601 format for JavaScript parsing
       iso_time = utc_time.iso8601
 
-      # Format presets for data-format attribute
+      # Format presets come from the locale, not from literals here: "%B %d, %Y"
+      # is a US ordering as much as it is English words, and other locales want
+      # a different one (German: "%d. %B %Y"). An unrecognised format is still
+      # treated as a caller-supplied strftime pattern, as before.
       format_string = case format
-      when :full
-        "%B %d, %Y %I:%M:%S %p"  # December 31, 2024 11:59:59 PM
-      when :short
-        "%m/%d %I:%M%p"          # 12/31 11:59PM
-      when :date_only
-        "%B %d, %Y"              # December 31, 2024
-      when :time_only
-        "%I:%M:%S %p"            # 11:59:59 PM
-      when :datetime
-        "%b %d, %Y %H:%M"        # Dec 31, 2024 23:59
+      when :full, :short, :date_only, :time_only, :datetime
+        red_time_format(format)
       else
         format.to_s
       end
@@ -234,7 +230,8 @@ module RailsErrorDashboard
     # @param time [Time, DateTime, nil] The timestamp to display
     # @param fallback [String] Text to show if time is nil
     # @return [String] HTML safe span with data attributes for JS conversion
-    def local_time_ago(time, fallback: "N/A")
+    def local_time_ago(time, fallback: nil)
+      fallback ||= red_t("red.common.not_available")
       return fallback if time.nil?
 
       # Convert to UTC if not already
@@ -243,7 +240,16 @@ module RailsErrorDashboard
 
       content_tag(
         :span,
-        time_ago_in_words(time) + " ago",  # Fallback for non-JS browsers
+        # Interpolated, not concatenated: several languages put the equivalent
+        # of "ago" before the duration, and some inflect it.
+        #
+        # NOTE: time_ago_in_words is Rails' own helper and translates through
+        # the HOST app's I18n, not RED's. In practice the browser replaces this
+        # text immediately (see formatRelativeTime in the layout) and it only
+        # shows for non-JS clients, so a host/dashboard locale mismatch here is
+        # cosmetic and brief. Phase 3 localizes the JS side, which is what
+        # users actually see.
+        red_t("red.time.ago", duration: time_ago_in_words(time)),  # Fallback for non-JS browsers
         class: "local-time-ago",
         data: {
           utc: iso_time

data/app/helpers/rails_error_dashboard/backtrace_helper.rb

@@ -2,6 +2,11 @@
 
 module RailsErrorDashboard
   module BacktraceHelper
+    # These helpers translate, so they depend on red_t explicitly rather
+    # than on the controller happening to mix every engine helper into
+    # one view context.
+    include I18nHelper
+
     # Language mapping for syntax highlighting
     LANGUAGE_MAP = {
       ".rb" => "ruby",
@@ -115,19 +120,23 @@ module RailsErrorDashboard
       end
     end
 
-    # Format category name
+    # Format category name.
+    #
+    # This labels where a frame came from, not what it says — the backtrace
+    # itself is diagnostic output and is never translated. "Gem", "Rails" and
+    # "Ruby" inside these labels are product names.
     def frame_category_name(category)
       case category
       when :app
-        "Your Code"
+        red_t("red.common.frame_category.app")
       when :gem
-        "Gem"
+        red_t("red.common.frame_category.gem")
       when :framework
-        "Rails Framework"
+        red_t("red.common.frame_category.framework")
       when :ruby_core
-        "Ruby Core"
+        red_t("red.common.frame_category.ruby_core")
       else
-        "Unknown"
+        red_t("red.common.frame_category.unknown")
       end
     end
 

data/app/helpers/rails_error_dashboard/i18n_helper.rb

@@ -0,0 +1,154 @@
+module RailsErrorDashboard
+  # View-layer entry point for RED's translations.
+  #
+  # The helper is deliberately named red_t, not t. Two reasons:
+  #
+  #   1. Overriding `t` in an engine helper risks colliding with the host app's
+  #      own helpers and with Rails' built-in translate, which has lazy-lookup
+  #      behaviour ("t('.title')") that RED's private backend does not provide.
+  #   2. An explicit name makes every translated site greppable — worth a lot
+  #      when the remaining ~1,600 strings get extracted a page at a time.
+  module I18nHelper
+    # red_js_t needs escape_javascript. In a request the controller mixes every
+    # engine helper into one view context, so it happens to be there — but that
+    # is incidental, and it is absent in a type: :helper spec or anywhere this
+    # module is included on its own. Include it explicitly rather than depend on
+    # the ambient context; the same fix P2-T11 applied to the T10 helpers.
+    include ActionView::Helpers::JavaScriptHelper
+    # Translate a key in the current request's locale.
+    #
+    # Output is HTML-escaped unless the key ends in _html, matching Rails'
+    # convention. Escaping happens here rather than in I18nStore because it is
+    # a view concern — mailers' text parts and JS payloads must not be escaped.
+    #
+    # @param key [String, Symbol] e.g. "red.nav.errors"
+    # @return [String] never nil, never raises
+    def red_t(key, **options)
+      value = I18nStore.translate(key, locale: red_locale, **options)
+
+      if key.to_s.end_with?("_html")
+        value.html_safe
+      else
+        ERB::Util.html_escape(value)
+      end
+    rescue StandardError
+      ""
+    end
+
+    # Pluralized translation. Selects the plural form from +count+ using the
+    # locale's CLDR rules, so it handles languages with more than English's
+    # two forms.
+    #
+    # Always use this rather than a ternary on "s" — an English binary plural
+    # is wrong in most languages, and several have no plural distinction at all.
+    #
+    # @param count [Integer] drives form selection and is available as %{count}
+    def red_tp(key, count:, **options)
+      red_t(key, count: count, **options)
+    end
+
+    # The locale this render should use.
+    #
+    # An explicit @red_locale wins over Current. Mailer and notification
+    # templates render outside the dashboard's around_action: there is no
+    # request, so Current.locale is nil at best and — on a reused Puma or
+    # job-runner thread — another request's leftover value at worst. That is
+    # the #143/#148 bug class. Those templates are handed a locale resolved at
+    # enqueue time (Concerns::LocalizedJob) and assigned to @red_locale, so
+    # reading it here is what makes the async path independent of thread state.
+    #
+    # Views rendered in a real dashboard request set no @red_locale and fall
+    # through to Current, which is correct there.
+    #
+    # @return [String] a locale RED ships
+    def red_locale
+      explicit = defined?(@red_locale) ? @red_locale : nil
+      return I18nStore.resolve(explicit) if explicit.present?
+
+      Current.locale_or_default
+    rescue StandardError
+      I18nStore::DEFAULT_LOCALE
+    end
+
+    # Translate for interpolation into a JavaScript string literal.
+    #
+    # red_t html-escapes, which is right for page text and wrong here. The two
+    # sinks in the layout's script blocks disagree about entities: showToast
+    # and innerHTML decode ' back to an apostrophe, but textContent renders
+    # it literally, so a French string would display "d'accéder" on screen.
+    #
+    # escape_javascript is what the surrounding code already uses for flash
+    # messages (`<%= j flash[:notice] %>`), and it is the correct escaping for
+    # this position: it neutralizes quotes, backslashes and line terminators
+    # that would break out of or truncate the literal, without touching
+    # characters the sink will render.
+    #
+    # Values still pass through the same total lookup, so a missing key is
+    # readable text rather than a raise inside a <script> block.
+    #
+    # @param key [String, Symbol] e.g. "red.ui_js.toast.copied"
+    # @return [String] html_safe, escaped for a JS string literal
+    def red_js_t(key, **options)
+      escape_javascript(I18nStore.translate(key, locale: red_locale, **options)).html_safe
+    rescue StandardError
+      ""
+    end
+
+    # Pluralized variant of red_js_t, for counts written by JS.
+    def red_js_tp(key, count:, **options)
+      red_js_t(key, count: count, **options)
+    end
+
+    # The translation payload handed to the browser as window.RED_I18N.
+    #
+    # Deliberately NOT the whole dictionary. This ships inside every dashboard
+    # page, so it carries only what JavaScript re-renders on the client: the
+    # red.js.* subtree and the strftime patterns that formatDateTime() is
+    # handed via data-format. Server-rendered strings already arrive as HTML
+    # and must never be sent twice.
+    #
+    # Values are raw, not html-escaped. They are serialized as JSON by
+    # js_safe_json — which neutralizes "</" against a </script> breakout — and
+    # then consumed as JS strings, so ERB escaping here would render literal
+    # &amp;amp; in the browser.
+    #
+    # @return [Hash] never nil, never raises. {} at worst.
+    def red_js_translations
+      locale = red_locale
+
+      {
+        "locale" => locale,
+        "js" => I18nStore.subtree("red.js", locale: locale),
+        "formats" => I18nStore.subtree("red.time.formats", locale: locale),
+        # Not under red.js because the server renders it too — local_time_ago
+        # wraps the same key. Sharing one key is the point: both sides then
+        # put "ago" wherever the language wants it, rather than each guessing.
+        "ago" => I18nStore.translate("red.time.ago", locale: locale)
+      }
+    rescue StandardError
+      {}
+    end
+
+    # A strftime pattern for one of ApplicationHelper#local_time's presets,
+    # localized. Falls back to the English pattern for an unknown preset.
+    #
+    # Kept here rather than inline in the view so the Ruby fallback rendering
+    # and the browser's data-format re-render always agree on the pattern.
+    #
+    # @param preset [Symbol, String] :full, :short, :date_only, :time_only, :datetime
+    # @return [String] a raw strftime pattern — NOT html-escaped, since it is
+    #   consumed by strftime and by the JS date formatter, not rendered as text
+    def red_time_format(preset)
+      key = "red.time.formats.#{preset}"
+      pattern = I18nStore.translate(key, locale: red_locale)
+
+      # A miss returns humanized key text, which would be a nonsense strftime
+      # pattern. Detect it by the absence of any % directive and fall back.
+      return pattern if pattern.include?("%")
+
+      I18nStore.translate("red.time.formats.full", locale: I18nStore::DEFAULT_LOCALE)
+    rescue StandardError
+      "%B %d, %Y %I:%M:%S %p"
+    end
+  end
+end

data/app/helpers/rails_error_dashboard/mailer_i18n_helper.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  # Translation entry points for mailer templates.
+  #
+  # Mailers need two things the dashboard's I18nHelper does not provide.
+  #
+  # 1. AN UNESCAPED VARIANT, for the .text.erb parts.
+  #
+  #    red_t html-escapes, which is right for a web page and wrong for a plain
+  #    text email: a French string would arrive in the recipient's mail client
+  #    as "Impossible d'accéder". The .html.erb parts still use red_t. The
+  #    split mirrors I18nHelper vs. Translation elsewhere in the gem — the test
+  #    is where the string lands, not what it looks like.
+  #
+  # 2. A DATE FORMATTER THAT DOES NOT DEPEND ON JAVASCRIPT.
+  #
+  #    ApplicationHelper#local_time renders a <span data-format> that the
+  #    dashboard's JS re-renders in the reader's timezone and locale. Email has
+  #    no JS, so a mailer must produce finished text server-side.
+  #
+  #    Ruby's strftime is not locale-aware: %B is "August" whatever RED's
+  #    locale is. P3-T2 already put localized month, day and meridian names in
+  #    red.js.* for the browser's formatDateTime(); red_mail_time substitutes
+  #    the same vocabulary before handing the rest to strftime, so an email and
+  #    the dashboard render a date identically.
+  module MailerI18nHelper
+    # red_locale and red_time_format live in I18nHelper. Include it explicitly
+    # rather than relying on the mailer's view context happening to have both
+    # mixed in: a helper that calls another helper without including it works
+    # in a request and fails everywhere else, and the total rescues in this
+    # path would swallow the NoMethodError into an empty string. That failure
+    # mode already bit P2-T11 and P3-T3.
+    include I18nHelper
+
+    # Translate for a text/plain mailer part. Same lookup as red_t, no HTML
+    # escaping. Use red_t in the .html.erb parts.
+    #
+    # @return [String] never nil, never raises
+    def red_mail_t(key, **options)
+      I18nStore.translate(key, locale: red_locale, **options)
+    rescue StandardError
+      ""
+    end
+
+    # Pluralized variant of red_mail_t.
+    def red_mail_tp(key, count:, **options)
+      red_mail_t(key, count: count, **options)
+    end
+
+    # A finished, localized timestamp for an email.
+    #
+    # @param time [Time, nil]
+    # @param format [Symbol] a preset from red.time.formats
+    # @return [String] "" for nil — a mailer must never render "undefined",
+    #   and must never raise on the way to a notification
+    def red_mail_time(time, format: :full)
+      return "" if time.nil?
+
+      utc = time.respond_to?(:utc) ? time.utc : time
+      pattern = red_time_format(format)
+
+      "#{Services::LocalizedTimeFormatter.call(utc, pattern: pattern, locale: red_locale)} UTC"
+    rescue StandardError
+      # A timestamp is worth losing; the notification is not.
+      time.to_s
+    end
+  end
+end

data/app/helpers/rails_error_dashboard/overview_helper.rb

@@ -2,6 +2,11 @@
 
 module RailsErrorDashboard
   module OverviewHelper
+    # These helpers translate, so they depend on red_t explicitly rather
+    # than on the controller happening to mix every engine helper into
+    # one view context.
+    include I18nHelper
+
     # All helper methods return Bootstrap semantic classes (success, warning, danger)
     # These automatically map to Catppuccin Mocha colors in dark theme via CSS variables:
     # - success → --ctp-green
@@ -29,14 +34,17 @@ module RailsErrorDashboard
       value > 0 ? "text-danger" : "text-success"
     end
 
+    # The direction is a machine symbol; these are its display labels. An
+    # unrecognized value reads as stable, which is what the English original
+    # did with its else branch.
     def trend_text(direction)
       case direction
       when :increasing
-        "Increasing"
+        red_t("red.common.trend.increasing")
       when :decreasing
-        "Decreasing"
+        red_t("red.common.trend.decreasing")
       else
-        "Stable"
+        red_t("red.common.trend.stable")
       end
     end
 
@@ -64,14 +72,18 @@ module RailsErrorDashboard
       end
     end
 
+    # The emoji is part of the English rendering and lives in the key so a
+    # locale can drop it. These are deliberately not the
+    # red.analytics.platform_comparison.health_card keys — that page renders
+    # the same states without emoji.
     def health_status_text(status)
       case status
       when :healthy
-        "✅ Healthy"
+        red_t("red.common.health_status.healthy")
       when :warning
-        "⚠️ Warning"
+        red_t("red.common.health_status.warning")
       else
-        "🔴 Critical"
+        red_t("red.common.health_status.critical")
       end
     end
   end

data/app/helpers/rails_error_dashboard/user_agent_helper.rb

@@ -2,6 +2,11 @@
 
 module RailsErrorDashboard
   module UserAgentHelper
+    # These helpers translate, so they depend on red_t explicitly rather
+    # than on the controller happening to mix every engine helper into
+    # one view context.
+    include I18nHelper
+
     # Parse user agent string into browser, OS, and device info
     def parse_user_agent(user_agent_string)
       return default_user_agent_info if user_agent_string.blank?
@@ -13,7 +18,11 @@ module RailsErrorDashboard
         browser_version: browser.version,
         os_name: os_name(browser),
         device_type: device_type(browser),
-        platform: browser.platform.to_s.titleize,
+        # No titleize: the platform is a machine identifier from the browser
+        # gem, and titleize applies English morphology to it. Nothing renders
+        # this value today; it stays raw so a future reader gets the identifier
+        # rather than a mangled version of one.
+        platform: browser.platform.to_s,
         is_mobile: browser.device.mobile?,
         is_tablet: browser.device.tablet?,
         is_bot: browser.bot?
@@ -76,6 +85,8 @@ module RailsErrorDashboard
 
     private
 
+    # Browser and OS names are brands and stay as written in every locale.
+    # Only the "Unknown" fallback is a word rather than a name.
     def browser_name(browser)
       return "Chrome" if browser.chrome?
       return "Firefox" if browser.firefox?
@@ -83,7 +94,7 @@ module RailsErrorDashboard
       return "Edge" if browser.edge?
       return "Opera" if browser.opera?
       return "Internet Explorer" if browser.ie?
-      "Unknown"
+      red_t("red.common.unknown")
     end
 
     def os_name(browser)
@@ -92,23 +103,26 @@ module RailsErrorDashboard
       return "Linux" if browser.platform.linux?
       return "Android" if browser.platform.android?
       return "iOS" if browser.platform.ios?
-      "Unknown"
+      red_t("red.common.unknown")
     end
 
+    # Unlike the browser and OS, these four are ordinary words, not brands.
     def device_type(browser)
-      return "Mobile" if browser.device.mobile?
-      return "Tablet" if browser.device.tablet?
-      return "Bot" if browser.bot?
-      "Desktop"
+      return red_t("red.common.device_type.mobile") if browser.device.mobile?
+      return red_t("red.common.device_type.tablet") if browser.device.tablet?
+      return red_t("red.common.device_type.bot") if browser.bot?
+      red_t("red.common.device_type.desktop")
     end
 
     def default_user_agent_info
+      unknown = red_t("red.common.unknown")
+
       {
-        browser_name: "Unknown",
+        browser_name: unknown,
         browser_version: nil,
-        os_name: "Unknown",
-        device_type: "Unknown",
-        platform: "Unknown",
+        os_name: unknown,
+        device_type: unknown,
+        platform: unknown,
         is_mobile: false,
         is_tablet: false,
         is_bot: false

data/app/jobs/rails_error_dashboard/application_job.rb

@@ -1,5 +1,10 @@
 module RailsErrorDashboard
   class ApplicationJob < ActiveJob::Base
+    # Explicit, serialized locale for any job that renders user-facing text.
+    # Jobs run outside the dashboard's around_action, so they must never read
+    # the request-scoped locale directly — see Concerns::LocalizedJob for why.
+    include Concerns::LocalizedJob
+
     # CRITICAL: Ensure job failures don't break the app or spam error logs
     # Retry failed jobs with exponential backoff, but limit attempts
     retry_on StandardError, wait: :exponentially_longer, attempts: 3

data/app/jobs/rails_error_dashboard/baseline_alert_job.rb

@@ -11,7 +11,9 @@ module RailsErrorDashboard
 
     # @param error_log_id [Integer] The error log that triggered the alert
     # @param anomaly_data [Hash] Anomaly information from baseline check
-    def perform(error_log_id, anomaly_data)
+    # @param locale [String, nil] resolved at enqueue time. nil for jobs
+    #   enqueued by a pre-Phase-4 version still draining from the queue.
+    def perform(error_log_id, anomaly_data, locale = nil)
       error_log = ErrorLog.find_by(id: error_log_id)
       return unless error_log
 
@@ -36,49 +38,49 @@ module RailsErrorDashboard
       )
 
       # Send notifications through all enabled channels
-      send_notifications(error_log, anomaly_data, config)
+      send_notifications(error_log, anomaly_data, config, job_locale(locale))
     end
 
     private
 
-    def send_notifications(error_log, anomaly_data, config)
+    def send_notifications(error_log, anomaly_data, config, locale)
       # Slack notification
       if config.enable_slack_notifications && config.slack_webhook_url.present?
-        send_slack_notification(error_log, anomaly_data, config)
+        send_slack_notification(error_log, anomaly_data, config, locale)
       end
 
       # Email notification
       if config.enable_email_notifications && config.notification_email_recipients.any?
-        send_email_notification(error_log, anomaly_data, config)
+        send_email_notification(error_log, anomaly_data, config, locale)
       end
 
       # Discord notification
       if config.enable_discord_notifications && config.discord_webhook_url.present?
-        send_discord_notification(error_log, anomaly_data, config)
+        send_discord_notification(error_log, anomaly_data, config, locale)
       end
 
       # Webhook notification
       if config.enable_webhook_notifications && config.webhook_urls.any?
-        send_webhook_notification(error_log, anomaly_data, config)
+        send_webhook_notification(error_log, anomaly_data, config, locale)
       end
 
       # PagerDuty for critical anomalies
       if config.enable_pagerduty_notifications &&
          config.pagerduty_integration_key.present? &&
          anomaly_data[:level] == :critical
-        send_pagerduty_notification(error_log, anomaly_data, config)
+        send_pagerduty_notification(error_log, anomaly_data, config, locale)
       end
     end
 
-    def send_slack_notification(error_log, anomaly_data, config)
-      payload = Services::BaselineAlertPayloadBuilder.slack_payload(error_log, anomaly_data)
+    def send_slack_notification(error_log, anomaly_data, config, locale)
+      payload = Services::BaselineAlertPayloadBuilder.slack_payload(error_log, anomaly_data, locale: locale)
 
       post_json(config.slack_webhook_url, payload)
     rescue => e
       Rails.logger.error("Failed to send baseline alert to Slack: #{e.message}")
     end
 
-    def send_email_notification(error_log, _anomaly_data, _config)
+    def send_email_notification(error_log, _anomaly_data, _config, _locale)
       Rails.logger.info(
         "Baseline alert email would be sent for #{error_log.error_type}"
       )
@@ -86,16 +88,16 @@ module RailsErrorDashboard
       Rails.logger.error("Failed to send baseline alert email: #{e.message}")
     end
 
-    def send_discord_notification(error_log, anomaly_data, config)
-      payload = Services::BaselineAlertPayloadBuilder.discord_payload(error_log, anomaly_data)
+    def send_discord_notification(error_log, anomaly_data, config, locale)
+      payload = Services::BaselineAlertPayloadBuilder.discord_payload(error_log, anomaly_data, locale: locale)
 
       post_json(config.discord_webhook_url, payload)
     rescue => e
       Rails.logger.error("Failed to send baseline alert to Discord: #{e.message}")
     end
 
-    def send_webhook_notification(error_log, anomaly_data, config)
-      payload = Services::BaselineAlertPayloadBuilder.webhook_payload(error_log, anomaly_data)
+    def send_webhook_notification(error_log, anomaly_data, config, locale)
+      payload = Services::BaselineAlertPayloadBuilder.webhook_payload(error_log, anomaly_data, locale: locale)
 
       config.webhook_urls.each do |url|
         post_json(url, payload)
@@ -120,7 +122,7 @@ module RailsErrorDashboard
       end
     end
 
-    def send_pagerduty_notification(error_log, _anomaly_data, _config)
+    def send_pagerduty_notification(error_log, _anomaly_data, _config, _locale)
       Rails.logger.info(
         "Baseline alert PagerDuty notification for #{error_log.error_type}"
       )

data/app/jobs/rails_error_dashboard/concerns/localized_job.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Concerns
+    # Gives a job an explicit, serialized locale instead of an inherited one.
+    #
+    # WHY JOBS CANNOT JUST READ Current.locale
+    #
+    # Mailers and notification jobs render outside the dashboard's
+    # around_action. There is no request, so there is no request locale.
+    # Reading Current.locale in a job returns nil at best — and at worst, on a
+    # reused Puma or job-runner thread, whatever an unrelated request left
+    # behind. That is the same bug class as #143 and #148: state outliving the
+    # request that set it.
+    #
+    # So the locale is resolved at ENQUEUE time (see .enqueue_locale) and
+    # travels in the job's arguments. The job then reads only its own argument.
+    #
+    # WHY ENQUEUE TIME RESOLVES TO CONFIG, NOT TO A USER
+    #
+    # Notifications are enqueued from the capture path — log_error, the storm
+    # gate — which runs inside a *host app* request, not a dashboard one. There
+    # is no dashboard user in scope and Current.locale is correctly nil there.
+    # The meaningful answer is config.dashboard_locale, which is what
+    # Current.locale_or_default returns when Current.locale is unset. Resolving
+    # through that one path keeps a single precedence chain for the whole gem
+    # and lets a dashboard-initiated enqueue (a future "send test notification"
+    # button) pick up the acting user's locale for free.
+    #
+    # BACKWARD COMPATIBILITY IS NOT OPTIONAL HERE
+    #
+    # Queues drain across a deploy. Jobs enqueued by the previous version have
+    # no locale argument at all, and they must still run — a notification is
+    # never worth losing over a translation detail. Every consumer therefore
+    # defaults the argument, and #job_locale hardens whatever arrives.
+    module LocalizedJob
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # The locale to serialize into a job's arguments, resolved in the
+        # enqueueing thread while its context is still valid.
+        #
+        # Returns a String, never a Symbol: ActiveJob serializes Symbols
+        # inconsistently across adapters, and Sidekiq's JSON round-trip turns
+        # one into a String anyway. Being explicit avoids a locale that is a
+        # Symbol on the inline adapter and a String in production.
+        #
+        # @return [String] a locale RED ships. Never nil, never raises.
+        def enqueue_locale
+          Current.locale_or_default
+        rescue StandardError
+          I18nStore::DEFAULT_LOCALE
+        end
+      end
+
+      private
+
+      # The locale this job should render in, from its own argument.
+      #
+      # Total by design. A nil (pre-upgrade payload), a garbage string, a
+      # Symbol, or a locale RED does not ship all degrade to
+      # config.dashboard_locale and then to English. REQ-4: a notification must
+      # never be lost because of a locale problem.
+      #
+      # @param value [Object] whatever arrived in the job arguments
+      # @return [String] a locale RED ships
+      def job_locale(value)
+        candidate = value.to_s.strip
+        return Current.locale_or_default if candidate.empty?
+
+        # resolve/1 already degrades an unknown tag to English, but an unknown
+        # tag should first get a chance at the configured locale — a queued job
+        # carrying a stale tag is closer to "no opinion" than to "wants
+        # English".
+        return I18nStore.resolve(candidate) if I18nStore.available?(candidate)
+
+        Current.locale_or_default
+      rescue StandardError
+        I18nStore::DEFAULT_LOCALE
+      end
+    end
+  end
+end