i18n-embedded-references 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db4b2544a71629739e076e47d845285f077a7e35343283debc38bd28a5eebede
+  data.tar.gz: 186b04b8c04e0d77def14c9fd3feab88c609690c7857973e0689aa1d339e86d6
+SHA512:
+  metadata.gz: 10036be6315e7fd4bd7bbd49ab80a029b64a9d24e446da5ae4acfe641b474d2163562268699d71e0fa685095e8d1722ef243144712bd12ca0ed5c6c9e6f3ba34
+  data.tar.gz: 7ebb506a3da0dbfb4f473f90eee32e756f518f81256c47c944945a2da1a3108cac96bcfbc7379305e8b55f6196f85600becdc8cf0560bf8678aeb56404500c60

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## 1.2.0
+
+- The requested locale is taken from the `fallback_original_locale` option
+  that `I18n::Backend::Fallbacks` passes down, so references resolve with the
+  right locale when Fallbacks is included above the backend (Rails includes
+  it into the root backend class, a Chain in many apps). Requires i18n >= 1.9.
+- Every reference in a translation resolves with the requested locale. Before,
+  with an explicit `locale:` different from `I18n.locale`, only the first
+  `${ref}` did and the rest fell back to `I18n.locale`. Thanks to @seff73 for
+  reporting it and pinning the plain-backend case with a test (#3).
+- Inside hashes and arrays a missing referenced key is handled per element
+  by the standard exception handler instead of making the whole structure
+  missing.
+- `I18n.exists?` no longer resolves references, it only tells whether the
+  key is defined. Before, a broken reference raised `UncaughtThrowError` and
+  references resolved with `I18n.locale` instead of the given locale.
+- `require 'i18n-embedded-references'` (Bundler's default autorequire for
+  the gem name) now works; `require 'i18n/embedded_references'` stays valid.
+- `rake i18n:embedded_references:check` boots the app when an `:environment`
+  task exists and mirrors `I18n.fallbacks`, so Rails apps no longer need
+  `--default-fallback`/`--fallback`. App chains are used verbatim, in their
+  own order and without prepending the locale when the chain does not start
+  with it, since that is exactly what the backend walks at runtime.
+  Precedence is flags > config file > app: a locale configured there ignores
+  the app chain and defaults. `APP_FALLBACKS=false` disables it. When the
+  app's backend does not include `I18n::Backend::Fallbacks`, the task checks
+  without fallbacks (no regional parent) and prints a warning naming the
+  environment. New `IGNORE_MISSING` variable for the task.
+- The checker and the backend share one grammar for `${key}`
+  (`I18n::EmbeddedReferences::Syntax`), so they no longer disagree: the
+  checker takes the key verbatim (`${ name }` is reported as broken, like the
+  runtime treats it), only an exact `${key}` counts as a whole-string
+  reference (`" ${menu}"` is a scope error), and references in hashes inside
+  arrays are checked too.
+
+## 1.1.0
+
+- Static checker for locale files: `i18n-embedded-references check` (CLI),
+  `rake i18n:embedded_references:check` (Rails railtie or manual require).
+  Reports broken references honouring fallbacks, circular references and
+  hash/array targets embedded in text. Config via `.i18n-embedded-references.yml`
+  or flags (`--fallback`, `--default-fallback`, `--ignore-missing`, `--quiet`).
+
+## 1.0.0
+
+Initial release. Successor of [i18n-recursive-lookup](https://github.com/annkissam/i18n-recursive-lookup),
+rewritten without ActiveSupport.
+
+- `${key}` references inside strings, hashes and arrays, resolved recursively.
+- `$${key}` escapes to the literal `${key}`.
+- References resolve with the originally requested locale, so fallbacks and
+  backend chains apply to the referenced key too.
+- Circular references raise `I18n::Backend::EmbeddedReferences::CircularReferenceError`.
+- `raise:` and `throw:` options propagate to referenced lookups.
+- No write-back cache into the translation store.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,239 @@
+# i18n-embedded-references
+
+Reference other translations from inside a translation with `${key}`.
+
+```yaml
+en:
+  company: Acme Corp
+  welcome: "Welcome to ${company}"
+  footer:
+    legal: "${company} is a registered trademark."
+```
+
+```ruby
+I18n.t(:welcome)        # => "Welcome to Acme Corp"
+I18n.t(:'footer.legal') # => "Acme Corp is a registered trademark."
+```
+
+Change `company` once and every translation that embeds it follows.
+
+This gem is the successor of [i18n-recursive-lookup](https://github.com/annkissam/i18n-recursive-lookup),
+which has been unmaintained since 2015. It keeps the `${}` syntax, drops the
+ActiveSupport dependency, resolves references recursively with cycle detection,
+and is locale-aware when fallbacks are in play.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'i18n-embedded-references'
+```
+
+Then include the module in your backend. In Rails, for example in
+`config/initializers/i18n.rb`:
+
+```ruby
+require 'i18n/embedded_references'
+
+I18n::Backend::Simple.include(I18n::Backend::EmbeddedReferences)
+```
+
+It works with `I18n::Backend::Fallbacks` wherever that is included: on the
+same backend, or on a `Chain` above it (which is what Rails does with
+`config.i18n.fallbacks`, so the initializer line above is all Rails needs).
+Requires i18n >= 1.9.
+
+## Syntax
+
+| Written                | Result                                             |
+|------------------------|----------------------------------------------------|
+| `${some.key}`          | the value of `some.key`                            |
+| `$${some.key}`         | the literal text `${some.key}`                     |
+| `"${some.hash}"`       | the hash itself, when the string is only that ref  |
+| `"${some.array}"`      | the array itself, when the string is only that ref |
+
+The key is taken verbatim: `${ some.key }` refers to `" some.key "`, not to
+`some.key`. Only an exact `"${some.hash}"` returns the structure; with any
+text around it, whitespace included, the value is spliced into a string.
+
+References are resolved anywhere in the translation tree: in plain strings,
+inside hashes returned by `I18n.t(:some_scope)`, and inside arrays.
+
+## Semantics
+
+**Recursive.** A referenced value may contain references of its own. A cycle
+raises `I18n::Backend::EmbeddedReferences::CircularReferenceError`
+with the full chain (`en.a -> en.b -> en.a`).
+
+**Resolved before interpolation and pluralization.** Interpolation values and
+`count` given to `I18n.t` are forwarded to referenced keys, so this works:
+
+```yaml
+en:
+  body: "Dear %{name}"
+  letter: "${body}, see you soon"
+```
+
+```ruby
+I18n.t(:letter, name: 'Ann') # => "Dear Ann, see you soon"
+```
+
+**Locale-aware.** A reference is looked up with the locale that was originally
+requested, not the locale where the referencing string was found. With
+fallbacks `en-CL -> en`:
+
+```yaml
+en:
+  name: notice
+  alert: "alert ${name}"
+en-CL:
+  name: notice-cl
+```
+
+```ruby
+I18n.t(:alert, locale: :'en-CL') # => "alert notice-cl"
+```
+
+`alert` comes from `en` via fallback, but `${name}` still prefers `en-CL`.
+Explicit `locale:` options and `I18n::Backend::Chain` are honoured the same way.
+
+**Missing references.** A missing referenced key makes the referencing
+string translation missing. Your usual `raise:`, `throw:` and exception handler
+apply, and the message names the key that is actually absent
+(`Translation missing: en.company`). Inside a hash or array (`I18n.t(:scope)`)
+each element is resolved on its own, so a broken reference in one value does
+not take the whole structure down.
+
+**`I18n.exists?` does not resolve references.** It tells whether the key is
+defined, the same way it ignores `%{}` placeholders, so a translation with a
+broken reference still exists. Use `I18n.t` or the checker below to find
+broken references.
+
+**No write-back.** Resolved values are never stored back into the translation
+store, so `store_translations` at runtime is picked up on the next lookup and
+the raw `${}` source is preserved in the backend.
+
+## Checking references statically
+
+The gem ships a checker that reads your locale files without booting the app
+and reports, per file and key:
+
+- **broken references**: the target key does not exist in the locale or its
+  fallbacks (at runtime this would surface as a missing translation)
+- **circular references**: `a -> b -> a` (at runtime: `CircularReferenceError`)
+- **scope references embedded in text**: `"See ${menu}"` where `menu` is a
+  hash or array
+
+```bash
+bundle exec i18n-embedded-references check config/locales packs/**/config/locales
+```
+
+```
+config/locales/en.yml
+  en.footer.legal
+    error: broken reference ${company_name} (not found in en)
+  en.nav.label
+    error: reference ${menu} is embedded in text but points to a hash or array
+
+config/locales/es-CL.yml
+  es-CL.welcome
+    error: broken reference ${compnay} (not found in es-CL, es)
+
+3 errors, 0 warnings, 142 references checked in 12 files (0.1s)
+```
+
+Exit status is 1 when there are errors, so it drops straight into CI.
+
+Fallbacks default to the region-stripped parent (`es-CL` -> `es`). Anything
+else, plus keys that another backend resolves at runtime, goes in
+`.i18n-embedded-references.yml` (picked up automatically) or `--config FILE`:
+
+```yaml
+paths:
+  - config/locales
+  - packs/**/config/locales
+default_fallbacks: [es]        # I18n.fallbacks = [:es]
+fallbacks:
+  ca: [es]                     # extra per-locale chains
+ignore_missing:
+  - 'custom_translations.*'    # resolved by a database backend, not YAML
+```
+
+The same options exist as flags: `--fallback ca:es`, `--default-fallback es`,
+`--ignore-missing 'custom_translations.*'`, `--quiet`.
+
+In Rails, prefer the rake task: it boots the app and reads `I18n.fallbacks`,
+so the checker follows the same fallback chains as runtime without repeating
+them as flags:
+
+```bash
+bin/rake i18n:embedded_references:check \
+  PATHS="config/locales packs/**/config/locales" \
+  IGNORE_MISSING="custom_translations.*"
+```
+
+```
+Using fallbacks from I18n.fallbacks (4 locales, defaults: es)
+3 errors, 0 warnings, 142 references checked in 12 files (1.8s)
+```
+
+Fallbacks are only taken from the app when its backend actually includes
+`I18n::Backend::Fallbacks` (what `config.i18n.fallbacks` does). Each app chain
+(`I18n.fallbacks[locale]`) is exactly what the backend walks at runtime, so it
+is used verbatim: in its own order, without inserting the regional parent, and
+without prepending the locale if the chain does not start with it (a custom
+fallbacks object may return `[:en]` for `:pt`). Precedence is flags >
+config file > app: a locale given in `fallbacks` (config or `CONFIG=file`)
+ignores the app chain and the app defaults, and the app defaults only apply to
+locales without an app chain. `APP_FALLBACKS=false` skips booting the app. Keys resolved by another backend still have to be listed in
+`IGNORE_MISSING` (space separated globs): there is no way to infer them.
+Outside Rails, add `require 'i18n/embedded_references/tasks'` to your Rakefile.
+
+When the booted app does not use `I18n::Backend::Fallbacks`, the task checks
+without fallbacks (no regional parent either, only the ones given by flags or
+config) and says so:
+
+```
+App backend does not use I18n::Backend::Fallbacks (RAILS_ENV=test): checking without fallbacks
+```
+
+Mind the environment: Rails generates `production.rb` with
+`config.i18n.fallbacks = true`, but development and test leave it off, and the
+task usually runs in CI with `RAILS_ENV=test`. If production uses fallbacks and
+test does not, the task reports references that production resolves. Align
+`config.i18n.fallbacks` in test with production, or pass the fallbacks as
+flags or config.
+
+## Differences from i18n-recursive-lookup
+
+- No ActiveSupport dependency.
+- References resolve with the requested locale (see above); the original used
+  the fallback locale, which returned the wrong value for locale overrides.
+- No compiled-value cache written into the store. The original cached under the
+  fallback locale, leaking locale-specific values across locales.
+- Cycle detection instead of a stack overflow.
+- Missing references surface through the standard I18n missing-translation
+  handling instead of being spliced in as text.
+- Interpolation values and `count` are forwarded to referenced keys.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+To release, bump `VERSION` in `lib/i18n/embedded_references/version.rb`, add
+the entry to `CHANGELOG.md`, merge, and push a tag with the same version:
+
+```bash
+git tag v1.2.0 && git push origin v1.2.0
+```
+
+The `Release` workflow checks that the tag matches the version, runs the
+tests and publishes to RubyGems.org through trusted publishing.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/i18n-embedded-references

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'i18n/embedded_references/cli'
+
+exit I18n::EmbeddedReferences::CLI.new.run(ARGV)

data/lib/i18n/backend/embedded_references.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'i18n'
+require_relative '../embedded_references/syntax'
+
+module I18n
+  module Backend
+    # Resolves `${some.key}` markers found inside translations by looking up
+    # the referenced key and splicing its value in place. `$${some.key}`
+    # produces the literal text `${some.key}`.
+    #
+    # Include it in any backend that implements `lookup`:
+    #
+    #   I18n::Backend::Simple.include(I18n::Backend::EmbeddedReferences)
+    #
+    # References are resolved through `I18n.translate`, with the locale that
+    # was originally requested, so fallback chains and backend chains are
+    # honoured for the referenced key as well as for the referencing one. The
+    # requested locale is taken from the `fallback_original_locale` option
+    # that `I18n::Backend::Fallbacks` passes down (i18n >= 1.9), so it works
+    # whether Fallbacks sits on this backend or on a Chain above it.
+    # Resolution happens before interpolation and pluralization, so a
+    # referenced value may itself contain `%{}` placeholders.
+    #
+    # A missing referenced key makes a string translation missing (the
+    # MissingTranslation names the absent key). Inside hashes and arrays the
+    # missing reference is handled per element by the standard exception
+    # handler, so one broken value does not take the whole structure down.
+    #
+    # `exists?` does not resolve references: it answers whether the key is
+    # defined, like I18n does for interpolations.
+    module EmbeddedReferences
+      class CircularReferenceError < I18n::ArgumentError
+        def initialize(chain)
+          super("circular embedded reference: #{chain.join(' -> ')}")
+        end
+      end
+
+      REQUESTED_LOCALE_KEY = :i18n_embedded_references_requested_locale
+      RESOLUTION_STACK_KEY = :i18n_embedded_references_stack
+      SKIP_RESOLUTION_KEY = :i18n_embedded_references_skip_resolution
+
+      # Options that only make sense for the referencing lookup and must not
+      # leak into the nested translate call. Everything else (interpolation
+      # values, `count`, `exception_handler`, ...) is forwarded so that a
+      # referenced value is interpolated and pluralized like the caller asked.
+      NOT_FORWARDED_OPTIONS = %i[
+        scope default separator locale object format resolve cascade deep_interpolation
+        fallback fallback_in_progress fallback_original_locale
+      ].freeze
+
+      def translate(locale, key, options = EMPTY_HASH)
+        with_requested_locale(options[:fallback_original_locale] || locale) { super }
+      end
+
+      # `Base#exists?` calls `lookup` outside `translate`, so resolving there
+      # would use `I18n.locale` instead of the given locale, and a broken
+      # reference would `throw` with nobody to catch it.
+      def exists?(locale, key, options = EMPTY_HASH)
+        previous = Thread.current[SKIP_RESOLUTION_KEY]
+        Thread.current[SKIP_RESOLUTION_KEY] = true
+        super
+      ensure
+        Thread.current[SKIP_RESOLUTION_KEY] = previous
+      end
+
+      protected
+
+      def lookup(locale, key, scope = [], options = EMPTY_HASH)
+        result = super
+        return result if Thread.current[SKIP_RESOLUTION_KEY]
+        return result unless result.is_a?(String) || result.is_a?(Hash) || result.is_a?(Array)
+
+        resolve_embedded(result, options, nested: false)
+      end
+
+      private
+
+      # Records the locale of the outermost translate call so that nested
+      # reference lookups use it instead of whatever fallback locale the
+      # referencing translation was found in. Only the call that set the
+      # locale clears it: nested calls re-enter with the same locale and must
+      # not wipe it before the remaining references are resolved.
+      def with_requested_locale(locale)
+        owner = Thread.current[REQUESTED_LOCALE_KEY].nil?
+        Thread.current[REQUESTED_LOCALE_KEY] = locale if owner
+        yield
+      ensure
+        Thread.current[REQUESTED_LOCALE_KEY] = nil if owner
+      end
+
+      def requested_locale
+        Thread.current[REQUESTED_LOCALE_KEY] || I18n.locale
+      end
+
+      # `nested` is true for values found inside a hash or array.
+      def resolve_embedded(subject, options, nested:)
+        case subject
+        when Hash
+          subject.each_with_object({}) { |(k, v), h| h[k] = resolve_embedded(v, options, nested: true) }
+        when Array
+          subject.map { |v| resolve_embedded(v, options, nested: true) }
+        when String
+          resolve_string(subject, options, nested: nested)
+        else
+          subject
+        end
+      end
+
+      def resolve_string(string, options, nested:)
+        return string unless I18n::EmbeddedReferences::Syntax.markers?(string)
+
+        tokens = I18n::EmbeddedReferences::Syntax.tokenize(string)
+        resolved = tokens.map do |token|
+          token.is_a?(String) ? token : resolve_reference(token.key, options, nested: nested)
+        end
+
+        # A translation consisting of a single reference keeps the referenced
+        # value as-is, so `${some.hash}` and `${some.array}` return structures.
+        I18n::EmbeddedReferences::Syntax.single_reference?(tokens) ? resolved.first : resolved.join
+      end
+
+      def resolve_reference(key, options, nested:)
+        locale = requested_locale
+        stack = (Thread.current[RESOLUTION_STACK_KEY] ||= [])
+        entry = "#{locale}.#{key}"
+        raise CircularReferenceError, stack + [entry] if stack.include?(entry)
+
+        stack.push(entry)
+        forwarded = options.reject { |k, _| NOT_FORWARDED_OPTIONS.include?(k) }
+        # For a string translation, `throw: true` hands the MissingTranslation
+        # of the referenced key to the outermost translate call, which applies
+        # the caller's raise/throw/exception handler. Inside a structure the
+        # element is resolved on its own so the rest of the hash or array
+        # survives a broken reference.
+        I18n.translate(key, **forwarded, locale: locale, throw: !nested)
+      ensure
+        stack.pop
+        Thread.current[RESOLUTION_STACK_KEY] = nil if stack.empty?
+      end
+    end
+  end
+end

data/lib/i18n/embedded_references/app_fallbacks.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module I18n
+  module EmbeddedReferences
+    # Reads the fallback configuration of the running app, so the checker
+    # resolves references the same way I18n does at runtime without having to
+    # repeat `config.i18n.fallbacks` as command line flags.
+    module AppFallbacks
+      module_function
+
+      # Returns `{ enabled: true, chains: { locale => [chain] }, default_fallbacks: [...] }`
+      # built from `I18n.fallbacks`. Each chain is the full runtime chain of the
+      # locale. Defaults are only read when the fallbacks object exposes them (a
+      # custom object may only implement `#[]`). When the backend does not use
+      # fallbacks, returns `{ enabled: false, chains: {}, default_fallbacks: [] }`:
+      # at runtime there is no fallback at all, not even the regional parent.
+      def from_i18n
+        return { enabled: false, chains: {}, default_fallbacks: [] } unless fallbacks_enabled?
+
+        fallbacks = I18n.fallbacks
+        chains = Array(I18n.available_locales).to_h do |locale|
+          [locale.to_s, Array(fallbacks[locale]).map(&:to_s)]
+        end
+        defaults = fallbacks.respond_to?(:defaults) ? Array(fallbacks.defaults).map(&:to_s) : []
+        { enabled: true, chains: chains, default_fallbacks: defaults }
+      end
+
+      # Fallbacks only apply at runtime when the backend class includes
+      # I18n::Backend::Fallbacks (Rails does it with `config.i18n.fallbacks`).
+      def fallbacks_enabled?
+        defined?(I18n::Backend::Fallbacks) &&
+          I18n.respond_to?(:fallbacks) &&
+          I18n.backend.class.include?(I18n::Backend::Fallbacks)
+      end
+
+      def describe(app)
+        unless app[:enabled]
+          return 'App backend does not use I18n::Backend::Fallbacks ' \
+                 "(RAILS_ENV=#{environment}): checking without fallbacks"
+        end
+
+        defaults = app[:default_fallbacks].empty? ? 'none' : app[:default_fallbacks].join(', ')
+        "Using fallbacks from I18n.fallbacks (#{app[:chains].size} locales, defaults: #{defaults})"
+      end
+
+      def environment
+        return Rails.env if defined?(Rails) && Rails.respond_to?(:env)
+
+        ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'unknown'
+      end
+    end
+  end
+end

data/lib/i18n/embedded_references/checker.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'set'
+require 'date'
+require_relative 'syntax'
+
+module I18n
+  module EmbeddedReferences
+    # Static analysis of `${key}` references across locale YAML files.
+    #
+    # Loads the files without booting I18n or Rails, flattens them into
+    # `{ locale => { "dotted.key" => value } }` and verifies every reference:
+    #
+    # - broken:  the target key does not exist in the locale or its fallbacks
+    # - cycle:   following references leads back to the starting key
+    # - scope:   a reference embedded in text points at a Hash/Array target
+    #
+    # Fallbacks default to the region-stripped parent (`es-CL` -> `es`), can be
+    # extended per locale, and `default_fallbacks` are appended to every chain
+    # (the equivalent of `I18n.fallbacks = [:es]`). `ignore_missing` takes key
+    # globs for keys resolved elsewhere (another backend, a database, ...).
+    #
+    # `app_chains` and `app_default_fallbacks` hold the fallbacks of the
+    # running app (see AppFallbacks). An app chain is exactly what the runtime
+    # walks, so it is used verbatim: no regional parent is inserted and the
+    # locale itself is not prepended when the chain omits it. A locale listed
+    # in `fallbacks` ignores the app entirely. When the app runs
+    # without I18n::Backend::Fallbacks, `app_fallbacks_disabled` drops the
+    # regional parent for the other locales: their chain is only the locale
+    # plus the `default_fallbacks` given by the user.
+    class Checker
+      Problem = Struct.new(:kind, :severity, :locale, :key, :file, :message, keyword_init: true) do
+        def error?
+          severity == :error
+        end
+      end
+
+      Report = Struct.new(:problems, :references, :files, :seconds, keyword_init: true) do
+        def errors
+          problems.select(&:error?)
+        end
+
+        def warnings
+          problems.reject(&:error?)
+        end
+
+        def ok?
+          errors.empty?
+        end
+      end
+
+      YAML_CLASSES = [Symbol, Date, Time].freeze
+      EMPTY_HASH = {}.freeze
+      EMPTY_SET = Set.new.freeze
+
+      attr_reader :fallbacks, :default_fallbacks, :ignore_missing, :app_chains, :app_default_fallbacks,
+                  :app_fallbacks_disabled
+
+      # @param paths [Array<String>] files, directories or globs
+      # @param fallbacks [Hash{String => Array<String>}] extra fallbacks per locale
+      # @param default_fallbacks [Array<String>] locales appended to every chain
+      # @param ignore_missing [Array<String>] key globs whose absence is not an error
+      # @param app_chains [Hash{String => Array<String>}] runtime chain per locale, used verbatim
+      # @param app_default_fallbacks [Array<String>] app defaults for locales without a chain
+      # @param app_fallbacks_disabled [Boolean] the app runs without fallbacks
+      def initialize(paths, fallbacks: {}, default_fallbacks: [], ignore_missing: [], # rubocop:disable Metrics/ParameterLists
+                     app_chains: {}, app_default_fallbacks: [], app_fallbacks_disabled: false)
+        @paths = Array(paths)
+        @fallbacks = string_lists(fallbacks)
+        @default_fallbacks = Array(default_fallbacks).map(&:to_s)
+        @ignore_missing = Array(ignore_missing).map(&:to_s)
+        @app_chains = string_lists(app_chains)
+        @app_default_fallbacks = Array(app_default_fallbacks).map(&:to_s)
+        @app_fallbacks_disabled = app_fallbacks_disabled
+        @translations = {} # locale => { key => value }
+        @origins = {}      # locale => { key => file }
+        @scopes = {}       # locale => Set of keys that are hashes or arrays
+        @problems = []
+      end
+
+      def run
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        files = expand_paths
+        files.each { |file| load_file(file) }
+        references = check_references
+        check_cycles
+        Report.new(
+          problems: @problems.sort_by { |p| [p.file.to_s, p.locale, p.key] },
+          references: references,
+          files: files.size,
+          seconds: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        )
+      end
+
+      # Fallbacks given for the locale (flags or config) win over the app; an
+      # app chain is the runtime chain itself (`I18n.fallbacks[locale]`), so it
+      # is used verbatim, without prepending the locale when the chain omits
+      # it; an app without fallbacks only keeps the user defaults; otherwise
+      # the regional parent and the defaults apply.
+      def chain(locale)
+        @chains ||= {}
+        @chains[locale] ||= build_chain(locale).uniq
+      end
+
+      private
+
+      def build_chain(locale)
+        if fallbacks.key?(locale)
+          [locale] + regional_parent(locale) + fallbacks[locale] + default_fallbacks
+        elsif app_fallbacks_disabled
+          [locale] + default_fallbacks
+        elsif app_chains.key?(locale)
+          app_chains[locale] + default_fallbacks
+        else
+          [locale] + regional_parent(locale) + default_fallbacks + app_default_fallbacks
+        end
+      end
+
+      def regional_parent(locale)
+        locale.include?('-') ? [locale.split('-').first] : []
+      end
+
+      def string_lists(hash)
+        hash.to_h { |k, v| [k.to_s, Array(v).map(&:to_s)] }
+      end
+
+      def expand_paths
+        @paths.flat_map { |path| expand_path(path) }.uniq.sort
+      end
+
+      # A path may be a file, a directory or a glob whose matches are themselves
+      # files or directories (e.g. `packs/**/config/locales`).
+      def expand_path(path)
+        if File.directory?(path)
+          Dir.glob(File.join(path, '**', '*.{yml,yaml}')).select { |f| File.file?(f) }
+        elsif File.file?(path)
+          [path]
+        else
+          Dir.glob(path).flat_map { |match| File.directory?(match) ? expand_path(match) : [match] }
+        end
+      end
+
+      def load_file(file)
+        data = YAML.safe_load(File.read(file), aliases: true, permitted_classes: YAML_CLASSES, filename: file)
+        return unless data.is_a?(Hash)
+
+        data.each do |locale, tree|
+          next unless tree.is_a?(Hash)
+
+          flatten(tree, [], locale.to_s, file)
+        end
+      rescue Psych::Exception, ArgumentError => e
+        problem(:parse, :warning, nil, nil, file, "could not parse: #{e.message.lines.first&.strip}")
+      end
+
+      def flatten(tree, path, locale, file)
+        tree.each do |k, v|
+          current = path + [k.to_s]
+          if v.is_a?(Hash)
+            scopes_of(locale) << current.join('.')
+            flatten(v, current, locale, file)
+          else
+            key = current.join('.')
+            scopes_of(locale) << key if v.is_a?(Array)
+            keys_of(locale)[key] = v
+            (@origins[locale] ||= {})[key] = file
+          end
+        end
+      end
+
+      # Read access never creates locales, so iterating @translations is safe.
+      def keys_of(locale, create: true)
+        create ? (@translations[locale] ||= {}) : @translations.fetch(locale, EMPTY_HASH)
+      end
+
+      def scopes_of(locale, create: true)
+        create ? (@scopes[locale] ||= Set.new) : @scopes.fetch(locale, EMPTY_SET)
+      end
+
+      def key_defined?(locale, key)
+        keys_of(locale, create: false).key?(key)
+      end
+
+      def scope?(locale, key)
+        scopes_of(locale, create: false).include?(key)
+      end
+
+      def check_references
+        count = 0
+        @translations.each do |locale, keys|
+          keys.each do |key, value|
+            each_string(value) do |string|
+              scan(string).each do |ref, whole|
+                count += 1
+                check_reference(locale, key, ref, whole)
+              end
+            end
+          end
+        end
+        count
+      end
+
+      def check_reference(locale, key, ref, whole)
+        file = @origins[locale][key]
+        found = chain(locale).find { |l| key_defined?(l, ref) || scope?(l, ref) }
+        if found.nil?
+          return if ignored?(ref)
+
+          problem(:broken, :error, locale, key, file,
+                  "broken reference ${#{ref}} (not found in #{chain(locale).join(', ')})")
+        elsif !whole && scope?(found, ref)
+          problem(:scope, :error, locale, key, file,
+                  "reference ${#{ref}} is embedded in text but points to a hash or array")
+        end
+      end
+
+      def check_cycles
+        @translations.each_key do |locale|
+          state = {}
+          @translations[locale].each_key do |key|
+            visit(locale, key, state, []) unless state[key]
+          end
+        end
+      end
+
+      # Iterative-friendly DFS with three states: nil (new), :active, :done.
+      def visit(locale, key, state, stack)
+        state[key] = :active
+        stack.push(key)
+        targets_of(locale, key).each do |ref|
+          case state[ref]
+          when :active
+            cycle = stack[stack.index(ref)..] + [ref]
+            problem(:cycle, :error, locale, cycle.first, @origins[locale][cycle.first],
+                    "circular reference #{cycle.map { |k| "#{locale}.#{k}" }.join(' -> ')}")
+          when nil
+            visit(locale, ref, state, stack)
+          end
+        end
+        stack.pop
+        state[key] = :done
+      end
+
+      # Keys referenced from `key` as resolved from `locale` through its chain.
+      def targets_of(locale, key)
+        source = chain(locale).find { |l| key_defined?(l, key) }
+        return [] unless source
+
+        refs = []
+        each_string(@translations[source][key]) { |s| refs.concat(scan(s).map(&:first)) }
+        refs.select { |ref| chain(locale).any? { |l| key_defined?(l, ref) } }
+      end
+
+      def each_string(value, &block)
+        case value
+        when String then yield value
+        when Array then value.each { |v| each_string(v, &block) }
+        when Hash then value.each_value { |v| each_string(v, &block) }
+        end
+      end
+
+      # Returns [[key, whole_string?], ...] skipping escaped `$${}` markers.
+      def scan(string)
+        return [] unless Syntax.markers?(string)
+
+        tokens = Syntax.tokenize(string)
+        whole = Syntax.single_reference?(tokens)
+        tokens.grep(Syntax::Reference).map { |ref| [ref.key, whole] }
+      end
+
+      def ignored?(ref)
+        ignore_missing.any? { |glob| File.fnmatch?(glob, ref, File::FNM_EXTGLOB) }
+      end
+
+      def problem(kind, severity, locale, key, file, message)
+        @problems << Problem.new(kind: kind, severity: severity, locale: locale, key: key, file: file, message: message)
+      end
+    end
+  end
+end

data/lib/i18n/embedded_references/cli.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'yaml'
+require_relative 'checker'
+
+module I18n
+  module EmbeddedReferences
+    # Command line front end for Checker.
+    #
+    #   i18n-embedded-references check [paths...] [--config FILE]
+    #     [--fallback LOCALE:PARENT[,PARENT]] [--default-fallback LOCALE]
+    #     [--ignore-missing GLOB] [--quiet]
+    #
+    # Exit status: 0 clean, 1 errors found, 2 usage error.
+    #
+    # `app_fallbacks` (`{ enabled:, chains:, default_fallbacks: }`, see
+    # AppFallbacks) has the lowest precedence: a locale given in the config
+    # file or flags ignores the app chain and the app defaults. App chains are
+    # used as is. With `enabled: false` the app has no fallbacks, so the other
+    # locales get no regional parent either.
+    class CLI
+      CONFIG_FILE = '.i18n-embedded-references.yml'
+      DEFAULT_PATHS = ['config/locales'].freeze
+
+      def initialize(out: $stdout, err: $stderr, app_fallbacks: nil)
+        @out = out
+        @err = err
+        @app_fallbacks = app_fallbacks
+      end
+
+      def run(argv)
+        argv = argv.dup
+        command = argv.shift
+        return usage(2) unless command == 'check'
+
+        options = parse(argv)
+        return options if options.is_a?(Integer)
+
+        report = Checker.new(options[:paths], **checker_options(options)).run
+        print_report(report, quiet: options[:quiet])
+        report.ok? ? 0 : 1
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        usage(2)
+      end
+
+      private
+
+      def checker_options(options)
+        app = @app_fallbacks || {}
+        {
+          fallbacks: options[:fallbacks], default_fallbacks: options[:default_fallbacks],
+          ignore_missing: options[:ignore_missing],
+          app_chains: app.fetch(:chains, {}), app_default_fallbacks: app.fetch(:default_fallbacks, []),
+          app_fallbacks_disabled: app[:enabled] == false
+        }
+      end
+
+      def parse(argv)
+        options = { fallbacks: {}, default_fallbacks: [], ignore_missing: [], quiet: false, config: nil }
+        parser = build_parser(options)
+        paths = parser.parse(argv)
+        return 0 if options[:help]
+
+        merge_config(options, paths)
+      end
+
+      def build_parser(options)
+        OptionParser.new do |o|
+          o.banner = 'Usage: i18n-embedded-references check [paths...] [options]'
+          o.on('-c', '--config FILE', "config file (default: #{CONFIG_FILE} if present)") { |f| options[:config] = f }
+          o.on('-f', '--fallback SPEC', 'LOCALE:PARENT[,PARENT] (repeatable)') do |spec|
+            locale, parents = spec.split(':', 2)
+            options[:fallbacks][locale] = parents.to_s.split(',')
+          end
+          o.on('-d', '--default-fallback LOCALE', 'fallback appended to every locale (repeatable)') do |l|
+            options[:default_fallbacks] << l
+          end
+          o.on('-i', '--ignore-missing GLOB', 'key glob whose absence is not an error (repeatable)') do |g|
+            options[:ignore_missing] << g
+          end
+          o.on('-q', '--quiet', 'only print the summary line') { options[:quiet] = true }
+          o.on('-h', '--help') do
+            @out.puts o
+            options[:help] = true
+          end
+        end
+      end
+
+      # Command line values win over the config file; lists are concatenated.
+      # The app fallbacks are not merged here: Checker applies them only to
+      # the locales that neither of them configures.
+      def merge_config(options, paths)
+        config = load_config(options[:config])
+        config.fetch('fallbacks', {}).each { |l, p| options[:fallbacks][l.to_s] ||= Array(p).map(&:to_s) }
+        %i[default_fallbacks ignore_missing].each { |k| options[k] = list(config, k.to_s) + options[k] }
+        options[:paths] = paths.empty? ? list(config, 'paths') : paths
+        options[:paths] = DEFAULT_PATHS if options[:paths].empty?
+        options
+      end
+
+      def load_config(path)
+        file = path || (File.exist?(CONFIG_FILE) ? CONFIG_FILE : nil)
+        return {} unless file
+
+        YAML.safe_load(File.read(file), filename: file) || {}
+      end
+
+      def list(config, key)
+        Array(config[key]).map(&:to_s)
+      end
+
+      def print_report(report, quiet:)
+        unless quiet
+          report.problems.group_by(&:file).each do |file, problems|
+            @out.puts file || '(no file)'
+            problems.each do |p|
+              @out.puts "  #{[p.locale, p.key].compact.join('.')}" if p.key
+              @out.puts "    #{p.severity}: #{p.message}"
+            end
+            @out.puts
+          end
+        end
+        @out.puts format('%<e>d errors, %<w>d warnings, %<r>d references checked in %<f>d files (%<s>.1fs)',
+                         e: report.errors.size, w: report.warnings.size, r: report.references,
+                         f: report.files, s: report.seconds)
+      end
+
+      def usage(status)
+        @err.puts 'Usage: i18n-embedded-references check [paths...] [options]'
+        status
+      end
+    end
+  end
+end

data/lib/i18n/embedded_references/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module I18n
+  module EmbeddedReferences
+    # Exposes `rake i18n:embedded_references:check` in Rails apps.
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load File.expand_path('tasks.rb', __dir__)
+      end
+    end
+  end
+end

data/lib/i18n/embedded_references/syntax.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module I18n
+  module EmbeddedReferences
+    # The `${key}` grammar, shared by the backend and the checker so both
+    # agree on what a reference is.
+    #
+    # - `${some.key}` is a reference to `some.key`, taken verbatim (no strip)
+    # - `$${some.key}` is the literal text `${some.key}`
+    # - `${}` is not a reference
+    #
+    # A string that is exactly one reference (no surrounding text, not even
+    # whitespace) stands for the referenced value itself, which may be a hash
+    # or an array.
+    module Syntax
+      Reference = Struct.new(:key)
+
+      TOKENIZER = /(\$\$\{[^}]+\}|\$\{[^}]+\})/.freeze
+      TOKEN = /\A(\$)?\$\{([^}]+)\}\z/.freeze
+
+      module_function
+
+      # Whether the string may contain references or escapes at all.
+      def markers?(string)
+        string.include?('${')
+      end
+
+      # Splits a string into literal Strings and References, in order.
+      # Escapes come back as literal text.
+      def tokenize(string)
+        return [string] unless markers?(string)
+
+        string.split(TOKENIZER).reject(&:empty?).map do |token|
+          match = token.match(TOKEN)
+          next token unless match
+          next token[1..] if match[1] # `$${key}` escapes to the literal `${key}`
+
+          Reference.new(match[2])
+        end
+      end
+
+      def single_reference?(tokens)
+        tokens.size == 1 && tokens.first.is_a?(Reference)
+      end
+    end
+  end
+end

data/lib/i18n/embedded_references/tasks.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'rake'
+require_relative 'cli'
+require_relative 'app_fallbacks'
+
+namespace :i18n do
+  namespace :embedded_references do
+    desc 'Check ${} references in locale files ' \
+         '(PATHS="a b", IGNORE_MISSING="glob ...", CONFIG=file, APP_FALLBACKS=false)'
+    task :check do
+      # In a Rails app, boot it and mirror I18n.fallbacks so references are
+      # resolved like at runtime. APP_FALLBACKS=false skips booting the app.
+      app_fallbacks = nil
+      if ENV['APP_FALLBACKS'] != 'false' && Rake::Task.task_defined?(:environment)
+        Rake::Task[:environment].invoke
+        app_fallbacks = I18n::EmbeddedReferences::AppFallbacks.from_i18n
+        puts I18n::EmbeddedReferences::AppFallbacks.describe(app_fallbacks)
+      end
+
+      argv = ['check']
+      argv.concat(ENV['PATHS'].to_s.split) if ENV['PATHS']
+      argv.push('--config', ENV['CONFIG']) if ENV['CONFIG']
+      ENV['IGNORE_MISSING'].to_s.split.each { |glob| argv.push('--ignore-missing', glob) }
+      status = I18n::EmbeddedReferences::CLI.new(app_fallbacks: app_fallbacks).run(argv)
+      abort if status != 0
+    end
+  end
+end

data/lib/i18n/embedded_references/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module I18n
+  module EmbeddedReferences
+    VERSION = '1.2.0'
+  end
+end

data/lib/i18n/embedded_references.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'i18n'
+require_relative 'embedded_references/version'
+require_relative 'backend/embedded_references'
+require_relative 'embedded_references/railtie' if defined?(Rails::Railtie)

data/lib/i18n-embedded-references.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `require "i18n-embedded-references"`
+# (what Bundler tries by default) works alongside `require "i18n/embedded_references"`.
+require_relative 'i18n/embedded_references'

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: i18n-embedded-references
+version: !ruby/object:Gem::Version
+  version: 1.2.0
+platform: ruby
+authors:
+- Jaime Arrieta
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: |
+  An I18n backend extension that lets a translation embed other translations
+  using the `${some.key}` marker. References are resolved lazily on lookup,
+  recursively, with cycle detection and fallback-aware locale resolution.
+  Works with strings, hashes and arrays. Successor of i18n-recursive-lookup.
+email:
+- contacto@buk.cl
+executables:
+- i18n-embedded-references
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/i18n-embedded-references
+- lib/i18n-embedded-references.rb
+- lib/i18n/backend/embedded_references.rb
+- lib/i18n/embedded_references.rb
+- lib/i18n/embedded_references/app_fallbacks.rb
+- lib/i18n/embedded_references/checker.rb
+- lib/i18n/embedded_references/cli.rb
+- lib/i18n/embedded_references/railtie.rb
+- lib/i18n/embedded_references/syntax.rb
+- lib/i18n/embedded_references/tasks.rb
+- lib/i18n/embedded_references/version.rb
+homepage: https://github.com/bukhr/i18n-embedded-references
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bukhr/i18n-embedded-references
+  source_code_uri: https://github.com/bukhr/i18n-embedded-references
+  changelog_uri: https://github.com/bukhr/i18n-embedded-references/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Reference other translations from inside a translation with ${key}.
+test_files: []