i18n-keyless-rails 3.5.0

data/lib/i18n_keyless/helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # The `i18nk` helper, mixed into views, controllers, mailers and jobs by the
+  # Railtie. `t()` with an i18n-keyless `context`, for ambiguous strings:
+  #
+  #   i18nk("8 heures", context: "duration")    # "8 hours"
+  #   i18nk("8 heures", context: "clock time")  # "8 AM"
+  #   i18nk("Bienvenue %{name}", name: user.name, context: "greeting")
+  #   i18nk("Payer", namespace: "checkout")
+  #
+  # The string is stored as "key__context", exactly like the SDKs. `%{name}`
+  # placeholders are I18n's own replacement. Unlike `t()`, `i18nk` never treats
+  # its argument as a Rails key: `i18nk("close")` is the source string "close".
+  module Helper
+    def i18nk(text, values = nil, context: nil, locale: nil, namespace: nil, **more_values)
+      values = (values || {}).merge(more_values)
+      I18nKeyless.translate(text, values, context: context, locale: locale, namespace: namespace)
+    end
+  end
+end

data/lib/i18n_keyless/locale.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # Maps a Rails locale ("fr", :"pt-BR", "zh_CN", "en-GB") onto one of the 48
+  # i18n-keyless language codes. A port of `resolveLang` from i18n-keyless-core.
+  module Locale
+    # The 48 languages i18n-keyless translates into, as the API spells them (v3).
+    AVAILABLE_LANGS = %w[
+      ar bn ca zh-Hans zh-Hant hr cs da nl en en-GB fi
+      fr fr-CA de el gu he hi hu id it ja kn ko ms
+      ml mr no or pl pt pt-BR pa ro ru sk sl es es-MX
+      sv ta te th tr uk ur vi
+    ].freeze
+
+    # Chinese is selected by script, not by region, and the regions do not map
+    # to a script by name, so the common region tags are spelled out.
+    CHINESE_REGION_SCRIPTS = {
+      "cn" => "zh-Hans", "sg" => "zh-Hans", "hans" => "zh-Hans",
+      "tw" => "zh-Hant", "hk" => "zh-Hant", "mo" => "zh-Hant", "hant" => "zh-Hant"
+    }.freeze
+
+    # The App Store Connect listing slot of each code (a convenience the SDKs
+    # ship; not a wire concern).
+    APP_STORE_LOCALES = {
+      "ar" => "ar-SA", "bn" => "bn", "ca" => "ca", "zh-Hans" => "zh-Hans", "zh-Hant" => "zh-Hant",
+      "hr" => "hr", "cs" => "cs", "da" => "da", "nl" => "nl-NL", "en" => "en-US", "en-GB" => "en-GB",
+      "fi" => "fi", "fr" => "fr-FR", "fr-CA" => "fr-CA", "de" => "de-DE", "el" => "el", "gu" => "gu",
+      "he" => "he", "hi" => "hi", "hu" => "hu", "id" => "id", "it" => "it", "ja" => "ja", "kn" => "kn",
+      "ko" => "ko", "ms" => "ms", "ml" => "ml", "mr" => "mr", "no" => "no", "or" => "or", "pl" => "pl",
+      "pt" => "pt-PT", "pt-BR" => "pt-BR", "pa" => "pa", "ro" => "ro", "ru" => "ru", "sk" => "sk",
+      "sl" => "sl", "es" => "es-ES", "es-MX" => "es-MX", "sv" => "sv", "ta" => "ta", "te" => "te",
+      "th" => "th", "tr" => "tr", "uk" => "uk", "ur" => "ur", "vi" => "vi"
+    }.freeze
+
+    BY_LOWERCASE = AVAILABLE_LANGS.to_h { |lang| [lang.downcase, lang] }.freeze
+    private_constant :BY_LOWERCASE
+
+    module_function
+
+    # The i18n-keyless code for a locale tag, most specific match first, or
+    # nil when no supported language matches.
+    #
+    #   to_lang("pt_BR")  # => "pt-BR"
+    #   to_lang("pt-AO")  # => "pt"
+    #   to_lang("zh_CN")  # => "zh-Hans"
+    #   to_lang("zh_TW")  # => "zh-Hant"
+    #   to_lang("es-419") # => "es-MX"
+    #   to_lang("xx")     # => nil
+    def to_lang(tag)
+      resolve(tag)
+    end
+
+    # `resolveLang(tag, { supported, fallback })` of the SDKs: the first
+    # candidate present in `supported` (when given), else `fallback`.
+    #
+    #   resolve("pt-BR", supported: ["pt", "en"], fallback: "en") # => "pt"
+    #   resolve("ja", supported: ["pt", "en"], fallback: "en")    # => "en"
+    def resolve(tag, supported: nil, fallback: nil)
+      candidates(tag).each do |candidate|
+        return candidate if supported.nil? || supported.include?(candidate)
+      end
+      fallback
+    end
+
+    # `to_app_store_locale("fr")` # => "fr-FR"
+    def to_app_store_locale(lang)
+      APP_STORE_LOCALES[lang.to_s]
+    end
+
+    def lang?(code)
+      AVAILABLE_LANGS.include?(code.to_s)
+    end
+
+    def candidates(tag)
+      return [] if tag.nil?
+
+      normalized = tag.to_s.tr("_", "-").strip.downcase
+      return [] if normalized.empty?
+
+      parts = normalized.split("-")
+      language = parts.first
+      region = parts.last
+      list = []
+      push = ->(lang) { list << lang if lang && !list.include?(lang) }
+
+      # 1. the tag as written ("pt-BR", "zh-Hans")
+      push.call(BY_LOWERCASE[normalized])
+
+      # 2. Chinese resolves by script and never falls back to a bare language
+      if language == "zh"
+        push.call(CHINESE_REGION_SCRIPTS.fetch(region, "zh-Hans"))
+        return list
+      end
+
+      # 3. UN M49 code for Latin America, which is what the es-MX slot really covers
+      push.call("es-MX") if normalized == "es-419"
+
+      # 4. the bare language ("pt-AO" => "pt")
+      push.call(BY_LOWERCASE[language])
+      list
+    end
+  end
+end

data/lib/i18n_keyless/middleware.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+begin
+  require "rack/body_proxy"
+rescue LoadError
+  # Rack is not a dependency of the gem: without it the flush runs before the response leaves.
+end
+
+module I18nKeyless
+  # Flushes the misses, the revalidations and the usage after each response
+  # is sent (the body is closed), so a translation never delays a page.
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      if defined?(::Rack::BodyProxy)
+        [status, headers, ::Rack::BodyProxy.new(body) { I18nKeyless.flush }]
+      else
+        I18nKeyless.flush
+        [status, headers, body]
+      end
+    rescue Exception # rubocop:disable Lint/RescueException -- the flush still runs after a failed request
+      I18nKeyless.flush
+      raise
+    end
+  end
+end

data/lib/i18n_keyless/miss.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # One source string that had no translation, with the languages it was
+  # requested in. Sent to POST /translate once per (namespace, key, context).
+  class Miss
+    attr_reader :key, :context, :namespace, :langs
+
+    def initialize(key, context = nil, namespace = Translator::DEFAULT_NAMESPACE, langs = [])
+      @key = key
+      @context = context.to_s.empty? ? nil : context
+      @namespace = namespace.to_s.empty? ? Translator::DEFAULT_NAMESPACE : namespace
+      @langs = Array(langs).dup
+    end
+
+    # The lookup key, stored exactly like the SDKs: "key__context".
+    def lookup_key
+      self.class.lookup_key_for(key, context)
+    end
+
+    def self.lookup_key_for(key, context)
+      context.nil? || context.to_s.empty? ? key.to_s : "#{key}__#{context}"
+    end
+
+    # Dedupe id: one POST per (namespace, key, context), whatever the languages.
+    def id
+      "#{namespace}:#{lookup_key}"
+    end
+
+    def add_lang(lang)
+      @langs << lang unless @langs.include?(lang)
+    end
+
+    # A plain Hash (string keys), for an ActiveJob argument.
+    def to_h
+      { "key" => key, "context" => context, "namespace" => namespace, "langs" => langs.dup }
+    end
+
+    def self.from_h(data)
+      data = data.transform_keys(&:to_s)
+      new(data["key"], data["context"], data["namespace"] || Translator::DEFAULT_NAMESPACE, data["langs"] || [])
+    end
+  end
+end

data/lib/i18n_keyless/railtie.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # Auto-loaded by Rails. Chains the backend after the application's I18n
+  # backend, mixes `i18nk` into views, controllers, mailers and jobs, and
+  # flushes the misses after each response (Rack middleware), after each job,
+  # and at exit (rake tasks, `rails runner`).
+  class Railtie < ::Rails::Railtie
+    initializer "i18n_keyless.middleware" do |app|
+      app.middleware.use I18nKeyless::Middleware
+    end
+
+    initializer "i18n_keyless.helpers" do
+      ActiveSupport.on_load(:action_view) { include I18nKeyless::Helper }
+      ActiveSupport.on_load(:action_controller) { include I18nKeyless::Helper }
+      ActiveSupport.on_load(:action_mailer) { include I18nKeyless::Helper }
+      ActiveSupport.on_load(:active_job) do
+        include I18nKeyless::Helper
+        after_perform { I18nKeyless.flush }
+      end
+    end
+
+    # After the application's own `config.i18n.backend`, which Rails applies in
+    # its own after_initialize (registered before this one).
+    config.after_initialize do
+      I18nKeyless.reset!
+      I18nKeyless.install! if I18nKeyless.enabled?
+      at_exit { I18nKeyless.flush }
+    end
+  end
+end

data/lib/i18n_keyless/translate_missing_keys_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # Sends the misses of one request to POST /translate from a queue worker.
+  # Enqueued when `config.queue` (I18N_KEYLESS_QUEUE) is set.
+  class TranslateMissingKeysJob < ::ActiveJob::Base
+    def perform(misses)
+      I18nKeyless.translator.translate_now(misses.map { |miss| Miss.from_h(miss) })
+    end
+  end
+end

data/lib/i18n_keyless/translator.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # The bridge between Rails' I18n and the i18n-keyless API.
+  #
+  # Nothing happens until the first lookup that misses in a non-primary
+  # locale. That miss loads the locale's dictionary (from the cache, or from the
+  # API once) and keeps it in this process. A miss that is not in the dictionary
+  # either is recorded and the source text is returned. The misses are sent to
+  # POST /translate after the response (the Rack middleware), or as an
+  # ActiveJob when `queue` is set.
+  #
+  # With usage reporting on (the default, like the node SDK), the date each
+  # key was last served is recorded and POSTed to
+  # /translate/last-used-translations after the response, at most once every
+  # 10 s across processes.
+  #
+  # One instance per process, shared by every thread: the per-request state
+  # (misses, usage, dictionaries to revalidate) sits behind a mutex, and a
+  # flush takes whatever is there, whichever request recorded it.
+  class Translator
+    DEFAULT_NAMESPACE = "default"
+
+    NO_LANGUAGES_WARNING = "I18N_KEYLESS_LANGUAGES is required for translation: set it to every language " \
+                           "your app serves (for example \"en,fr,es\"). Missing strings are served as their " \
+                           "source text until then."
+
+    attr_reader :store, :api, :primary, :languages, :default_namespace, :queue, :logger
+
+    def self.build(config)
+      api_key = config.api_key.to_s
+      new(
+        store: DictionaryStore.new(
+          cache: config.resolved_cache,
+          prefix: config.cache_prefix.to_s.empty? ? "i18n-keyless" : config.cache_prefix.to_s,
+          ttl: config.cache_ttl,
+          api_key_hash: DictionaryStore.hash_key(api_key)
+        ),
+        api: ApiClient.new(
+          api_key: api_key,
+          api_url: config.resolved_api_url,
+          timeout: [config.timeout.to_i, 1].max,
+          retry_delays: config.resolved_retry,
+          concurrency: [config.concurrency.to_i, 1].max,
+          logger: config.resolved_logger
+        ),
+        primary: config.resolved_primary,
+        languages: config.resolved_languages,
+        default_namespace: config.resolved_namespace,
+        queue: config.queue,
+        usage_enabled: config.usage?,
+        logger: config.resolved_logger
+      )
+    end
+
+    def initialize(store:, api:, primary:, languages: [], default_namespace: DEFAULT_NAMESPACE, queue: nil,
+                   usage_enabled: true, logger: nil)
+      @store = store
+      @api = api
+      @primary = primary
+      @languages = languages
+      @default_namespace = default_namespace
+      @queue = queue.to_s.empty? ? nil : queue.to_s
+      @usage_enabled = usage_enabled
+      @logger = logger
+      @mutex = Mutex.new
+      @loaded = {}      # "lang|namespace" => lines loaded in this process
+      @misses = {}      # Miss#id => Miss
+      @revalidate = {}  # "lang|namespace" => [lang, namespace]
+      @usage = {}       # namespace => lookup key => YYYY-MM-DD
+      @warned_no_languages = false
+    end
+
+    def usage_enabled?
+      @usage_enabled
+    end
+
+    # `resolveNamespace` of the SDKs: the per-call namespace, else the
+    # configured default, else the literal `default`. Empty strings fall through.
+    def self.resolve_namespace(per_call, config_default)
+      return per_call.to_s unless per_call.nil? || per_call.to_s.empty?
+      return config_default.to_s unless config_default.nil? || config_default.to_s.empty?
+
+      DEFAULT_NAMESPACE
+    end
+
+    # The `i18nk` helper: a translation with an optional `context`, `%{name}`
+    # placeholders replaced by I18n after the lookup.
+    def get(text, values = {}, context: nil, locale: nil, namespace: nil)
+      text = text.to_s
+      return text if text.empty?
+
+      locale = (locale || I18n.locale).to_s
+      translated = lookup(locale, text, context: context, namespace: namespace) || text
+      I18nKeyless.interpolate(translated, values)
+    end
+
+    # The backend path. Returns the translation when the dictionary has it,
+    # the source text otherwise (never nil for a context lookup, so
+    # "key__context" never leaks to the page).
+    def lookup(locale, key, context: nil, namespace: nil)
+      key = key.to_s
+      return key if key.empty?
+
+      namespace = self.class.resolve_namespace(namespace, default_namespace)
+      lookup_key = Miss.lookup_key_for(key, context)
+      lang = Locale.to_lang(locale.to_s)
+      return key if lang.nil?
+
+      # Usage is recorded in the primary locale too, so the API does not prune
+      # keys that only ever render in their source language (node SDK rule).
+      record_usage(namespace, lookup_key)
+      return key if lang == primary
+
+      lines = ensure_loaded(lang, namespace)
+      value = lines[lookup_key]
+      # An empty stored translation counts as missing, like in the SDKs.
+      return value if value.is_a?(String) && !value.empty?
+
+      record_miss(key, context, namespace, lang)
+      key
+    end
+
+    # Loads the (lang, namespace) dictionary once per process.
+    def ensure_loaded(lang, namespace)
+      id = "#{lang}|#{namespace}"
+      @mutex.synchronize do
+        return @loaded[id] if @loaded.key?(id)
+
+        entry = store.get(lang, namespace)
+        if entry.nil?
+          # First time ever for this language: the one blocking fetch.
+          result = api.fetch_dictionary(lang, namespace, nil)
+          entry = if result.ok
+                    store.put(lang, namespace, result.translations, result.etag)
+                  else
+                    store.put(lang, namespace, {}, nil, failed: true)
+                  end
+        elsif store.stale?(entry)
+          # Serve what we have now, ask the API after the response.
+          @revalidate[id] = [lang, namespace]
+        end
+        @loaded[id] = entry[:translations]
+      end
+    end
+
+    # Forgets the dictionaries loaded in this process (I18n.reload!).
+    def reset_loaded!
+      @mutex.synchronize { @loaded.clear }
+    end
+
+    def pending_usage
+      @mutex.synchronize { @usage.transform_values(&:dup) }
+    end
+
+    def pending_misses
+      @mutex.synchronize { @misses.values }
+    end
+
+    # Runs after the response is sent: POSTs the misses, then revalidates the
+    # stale dictionaries served during the request, then sends the usage.
+    # Never raises.
+    def flush
+      misses, revalidate = @mutex.synchronize do
+        taken = [@misses.values, @revalidate.values]
+        @misses = {}
+        @revalidate = {}
+        taken
+      end
+
+      misses = [] if !misses.empty? && !can_translate?
+      claimed = misses.select { |miss| store.claim_miss(miss) }
+      unless claimed.empty?
+        if queue && defined?(I18nKeyless::TranslateMissingKeysJob)
+          TranslateMissingKeysJob.set(queue: queue).perform_later(claimed.map(&:to_h))
+        else
+          translate_now(claimed)
+        end
+      end
+
+      revalidate.each { |(lang, namespace)| revalidate_now(lang, namespace) }
+
+      flush_usage
+    rescue StandardError => e
+      warn("flush error: #{e.message}")
+    end
+
+    # POST /translate for each miss and merge the answers into the cache, so
+    # the very next request has them. The dictionaries are then marked stale:
+    # the next request revalidates them with the API after its response.
+    def translate_now(misses)
+      return if misses.empty? || !can_translate?
+
+      results = api.translate(misses, primary, languages)
+      touched = {}
+      misses.each do |miss|
+        translation = results[miss.id]
+        if translation.nil?
+          store.release_miss(miss)
+          next
+        end
+        lookup_key = miss.lookup_key
+        translation.each do |lang, text|
+          next if lang == primary || !Locale.lang?(lang) || text.to_s.empty?
+
+          (touched["#{miss.namespace}|#{lang}"] ||= {})[lookup_key] = text
+        end
+      end
+      touched.each do |id, lines|
+        namespace, lang = id.split("|", 2)
+        store.merge(lang, namespace, lines)
+        refresh_loaded(lang, namespace, lines)
+      end
+    end
+
+    private
+
+    def record_usage(namespace, lookup_key)
+      return if !usage_enabled? || lookup_key.empty?
+
+      date = Time.now.utc.strftime("%Y-%m-%d")
+      @mutex.synchronize { (@usage[namespace] ||= {})[lookup_key] = date }
+    end
+
+    def record_miss(key, context, namespace, lang)
+      return if key.empty?
+
+      miss = Miss.new(key, context, namespace)
+      @mutex.synchronize do
+        miss = (@misses[miss.id] ||= miss)
+        miss.add_lang(lang)
+      end
+    end
+
+    # Merges this request's usage dates into the stored map, then POSTs the
+    # whole map when it holds unsent changes and no POST left in the last 10 s.
+    # Fire and forget: a failure keeps the changes for a later request.
+    def flush_usage
+      recorded = @mutex.synchronize do
+        taken = @usage
+        @usage = {}
+        taken
+      end
+      return unless usage_enabled?
+
+      store.merge_usage(recorded) unless recorded.empty?
+      return if !store.usage_dirty? || !store.claim_usage_slot
+
+      result = api.send_usage(primary, store.usage)
+      store.clear_usage_dirty if result.ok
+    rescue StandardError
+      # Analytics must never affect the response.
+    end
+
+    # POST /translate overwrites the project's language list with the one it
+    # receives, so a miss is never sent without a configured list: it would
+    # shrink the project to the primary language and damage every other client
+    # on the same API key. The source text is served instead.
+    def can_translate?
+      return true unless languages.empty?
+
+      unless @warned_no_languages
+        @warned_no_languages = true
+        warn(NO_LANGUAGES_WARNING)
+      end
+      false
+    end
+
+    def revalidate_now(lang, namespace)
+      entry = store.get(lang, namespace)
+      result = api.fetch_dictionary(lang, namespace, entry && entry[:etag])
+      unless result.ok
+        # Remember the failure briefly, so the next requests do not all retry.
+        store.put(lang, namespace, entry ? entry[:translations] : {}, entry && entry[:etag], failed: true)
+        return
+      end
+      if result.not_modified
+        store.touch(lang, namespace)
+        return
+      end
+      store.put(lang, namespace, result.translations, result.etag)
+      refresh_loaded(lang, namespace, result.translations)
+    end
+
+    # Keeps this process's loaded lines current (a long-lived process keeps
+    # the dictionaries between requests).
+    def refresh_loaded(lang, namespace, lines)
+      id = "#{lang}|#{namespace}"
+      @mutex.synchronize do
+        @loaded[id] = @loaded[id].merge(lines) if @loaded.key?(id)
+      end
+    end
+
+    def warn(message)
+      logger&.warn("i18n-keyless: #{message}")
+    rescue StandardError
+      # Logging must never take a translation down.
+    end
+  end
+end

data/lib/i18n_keyless/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # Sent as the `Version` header. The API reads its major to pick the wire
+  # dialect: >= 3 means the v3 language codes ("zh-Hans", "cs"). One version
+  # for every package and port of the monorepo (scripts/set-version.mjs).
+  VERSION = "3.5.0"
+end

data/lib/i18n_keyless.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "i18n"
+require "logger"
+require "active_support"
+require "active_support/cache"
+require "active_support/core_ext/object/blank"
+
+require_relative "i18n_keyless/version"
+require_relative "i18n_keyless/config"
+require_relative "i18n_keyless/locale"
+require_relative "i18n_keyless/miss"
+require_relative "i18n_keyless/api_client"
+require_relative "i18n_keyless/dictionary_store"
+require_relative "i18n_keyless/translator"
+require_relative "i18n_keyless/backend"
+require_relative "i18n_keyless/helper"
+require_relative "i18n_keyless/middleware"
+
+# Keyless translations for Ruby on Rails.
+#
+# `t('Welcome to our app')` resolves through the i18n-keyless API: a missing
+# string is translated by AI once, for every language, cached in `Rails.cache`
+# and served from there. The gem is an `I18n` backend chained AFTER the
+# application's own backend, so `config/locales/*.yml` keeps working and wins.
+#
+#   I18nKeyless.configure do |c|
+#     c.api_key = "..."
+#     c.languages = %w[en fr es]
+#   end
+#
+# Every value also has an `I18N_KEYLESS_*` environment counterpart (see Config).
+module I18nKeyless
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    # Yields the config, then rebuilds the translator so the new values apply.
+    def configure
+      yield config if block_given?
+      reset!
+      config
+    end
+
+    # Forgets the built translator (and its per-process dictionaries). The next
+    # call builds a new one from `config`.
+    def reset!
+      @translator = nil
+    end
+
+    def enabled?
+      config.enabled?
+    end
+
+    def translator
+      @translator ||= Translator.build(config)
+    end
+
+    # The `i18nk` helper: a translation with an optional `context`, `%{name}`
+    # placeholders replaced by I18n. Returns the source text when the gem is
+    # disabled, when the locale is the primary language, or on a miss.
+    #
+    #   I18nKeyless.translate("8 heures", context: "duration")
+    #   I18nKeyless.translate("Bienvenue %{name}", name: "Ada", context: "greeting")
+    def translate(text, values = nil, context: nil, locale: nil, namespace: nil, **more_values)
+      text = text.to_s
+      values = (values || {}).merge(more_values).transform_keys(&:to_sym)
+      return interpolate(text, values) unless enabled?
+
+      translator.get(text, values, context: context, locale: locale, namespace: namespace)
+    end
+    alias t translate
+
+    # POSTs the recorded misses, revalidates the stale dictionaries served
+    # since the last flush, and sends the usage analytics. Called by the Rack
+    # middleware after each response, after each ActiveJob, and at exit.
+    # Never raises.
+    def flush
+      return unless enabled? && @translator
+
+      @translator.flush
+    end
+
+    # Chains the keyless backend after `base` (the current `I18n.backend` by
+    # default). Idempotent: an already chained backend is left alone.
+    def install!(base = I18n.backend)
+      return base if base.is_a?(Backend)
+      return base if base.is_a?(I18n::Backend::Chain) && base.backends.any? { |b| b.is_a?(Backend) }
+
+      I18n.backend = I18n::Backend::Chain.new(base, Backend.new)
+    end
+
+    # Removes the keyless backend from the chain, restoring the application's own backend.
+    def uninstall!
+      backend = I18n.backend
+      return backend unless backend.is_a?(I18n::Backend::Chain) && backend.backends.any? { |b| b.is_a?(Backend) }
+
+      rest = backend.backends.reject { |b| b.is_a?(Backend) }
+      I18n.backend = rest.length == 1 ? rest.first : I18n::Backend::Chain.new(*rest)
+    end
+
+    # Is this `I18n.t` key a keyless source string, or a Rails key?
+    #
+    # A Rails key is a lowercase identifier path: `hello`, `users.index.title`,
+    # `activerecord.errors.models.user`. Those are left to the YAML files (and
+    # never sent to the API). Anything else, a space, an uppercase letter, a
+    # punctuation mark, is a source string. `config.rails_key_pattern` holds the
+    # rule; `nil` makes every string keyless.
+    def keyless_key?(key)
+      return false unless key.is_a?(String) && !key.empty?
+
+      pattern = config.rails_key_pattern
+      pattern.nil? || !pattern.match?(key)
+    end
+
+    # `%{name}` placeholders, I18n's own replacement, applied only when values
+    # are given (like I18n::Backend::Base#translate).
+    def interpolate(text, values)
+      return text if values.nil? || values.empty?
+
+      I18n.interpolate(text, values)
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_job) { require_relative "i18n_keyless/translate_missing_keys_job" }
+
+require_relative "i18n_keyless/railtie" if defined?(::Rails::Railtie)