locallingo 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4296369c42c6c23ce6a15be0cc51adf0976fd6c07fd6b4514cd1a945c7ec07f9
-  data.tar.gz: b842069155d70be0a3291f67637deb719096b3654825768265cc8007e9ae27c5
+  metadata.gz: 47b5cfaffa1567e536de600f6f963538606fc386a89b61e90ad9cc4dd8327132
+  data.tar.gz: 767fa1b9c49c66a0b5b5e1bd6140edbca50edade201f415c9bfde2c6f0448206
 SHA512:
-  metadata.gz: 9f586a4ea9bd383bf58370219d99535f73f83994a2181ca7974302787a727df645f54c5e20c1465dc9f9f3e1ac586772b3bd97069b52f68c4bc0f03b99cf1422
-  data.tar.gz: bc075cce32d4602a4c0f8672340eca7cc7edee7afd779b95fb2822d1454794d3f804816c9a50d7f095c19aa2042dc916b203556813ddaff71d918b6e87f08bb7
+  metadata.gz: fad2120d8032a4a019dda5f6c82cd2f597de9dd79f9bb4eab1b9026530c859316c232314325398f51e12d61fc043c95882960969d5be325a80e6676463b55862
+  data.tar.gz: ff18516ac297ff0612111d0326552e6e771a6e0299854c598f3ea5645e9baaf722dd80e2571fc68186f3225af3eb35a69dc496107904feedd2cfc9d7356b1e8a

data/CHANGELOG.md

@@ -4,9 +4,75 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0]
+
+### Added
+- `Locallingo::Configuration.parse(text, root_path:, package:)` resolves
+  config from YAML text (ERB included) instead of `.locallingo.yml`, merged
+  over the shipped defaults the same way. (#35)
+- Concurrency conformance, development only (no new runtime dependency): CI
+  runs the suite on Ruby 4.0 too, and every pull request runs
+  conformance-kit 0.4's Conformance workflow: thread and fiber contention
+  examples, a Ractor canary of the pure core on Ruby 4.0, and a strict audit
+  of the gem's shared state. (#35)
+
+### Changed
+- Settings are frozen after boot, with nothing to call: the default settings
+  are frozen at load, and `Locallingo.configure` (a Rails initializer, or the
+  CLI's `.locallingo.rb`) publishes them frozen, in one assignment, so a
+  concurrent reader sees the old settings or the new, never half of them.
+  Concurrent `configure` calls run one at a time, so neither drops the
+  other's keys. Change them by calling `configure` again: **writing to
+  `Locallingo.settings` directly now raises `FrozenError`.** String keys are
+  stored as frozen plain String copies (a String subclass or its ivars are not
+  kept), so the settings are Ractor-shareable. A callable
+  key is kept as it is and never makes `configure` raise, even when it closes
+  over app state (a logger, a vault client); it keeps the settings readable
+  on the main Ractor only. (#35)
+- `translates_content` freezes its declaration at boot: the column and state
+  names and a String or Array `source_locale:`/`target_locales:` (as frozen
+  copies; the objects passed in are not frozen), and the drift. **Mutating them
+  through `locallingo_translatable` now raises `FrozenError`.** Callables
+  (`source_locale:`, `target_locales:`, `translatable:`, `hasher:`) are kept
+  as they are and never make the declaration raise. (#35)
+
+### Fixed
+- Without a `RubyLLM::Context`, a translation or quality-review call no
+  longer writes the resolved key into the process-global `RubyLLM.config`;
+  each call runs on a context of its own. Two translators with different keys
+  in one process could race, and one chat with the other's key. (#35)
+- `after_translate` hooks run via `system(command, chdir:)` instead of inside
+  `Dir.chdir`, which moved the working directory of the whole process while a
+  hook ran. (#35)
+- The static quality checks and `Configuration` (its ERB included) run inside
+  a non-main Ractor on Ruby 4.0: nested constants are frozen, and ERB no
+  longer evaluates on `TOPLEVEL_BINDING` (templates still resolve constants
+  from the top level, as the app sees them). (#35)
+
 ## [Unreleased]
 
 ### Added
+- `Locallingo::Translator#translate(texts, from:, to:, style:, instructions:)`
+  translates a plain `{ key => text }` hash with the configured prompt,
+  glossary, language guide, provider and model, and returns `translations` and
+  `failed`. (#33)
+- `Locallingo::Prompt.translation`: the translation prompt, public. `style:
+  :prose` keeps Markdown structure and drops the UI brevity rule;
+  `instructions:` is appended after the language guide. The CLI's `:ui`
+  prompt is unchanged. (#33)
+- `Providers::RubyLLM.new(provider:, context:)` and `Translator.new(context:)`
+  take a `RubyLLM::Context`; with one, the global `RubyLLM.config` is never
+  written. (#33)
+- `translate.max_batch_chars` limits the source characters per batch (a single
+  value over the limit is sent alone, never split); `translate.pause` sets the
+  sleep after each batch (default `1.0`). (#33)
+- `Locallingo::Drift`: missing / outdated / manual / hand-edited decisions as a
+  value over the state entry shape, for strings and nested values, with a
+  pluggable hasher. `Manager` and the validators use it; behaviour is
+  unchanged. (#33)
+- `require "locallingo/active_record"` adds `Locallingo::Translatable`
+  (`translates_content`), and `Locallingo::RecordTranslator` translates many
+  records in one batched call, writing each under its row lock. (#33)
 - `lingo quality --prefix yoga.` checks only the keys under a prefix, in both
   the static checks and the AI pass. A prefix that matches nothing exits `1`. (#10, #29)
 - `lingo quality --key a.b` (repeatable) checks exactly the named keys, and the

data/README.md

@@ -46,7 +46,12 @@ end
 Put that in a `.locallingo.rb` file next to `.locallingo.yml` and the `lingo`
 CLI loads it on start — no Rails boot required. A key set via
 `Locallingo.configure` wins over one set through `RubyLLM.configure`, which
-wins over ENV. Locallingo never stores keys itself.
+wins over ENV. Locallingo never stores keys itself. `configure` publishes the
+settings frozen: change them by calling it again, never by writing to
+`Locallingo.settings`. Nothing else needs calling at boot. With String keys
+the settings are Ractor-shareable; a callable key is kept as it is (resolved on
+every use, so it may close over a logger or a vault client), which keeps the
+settings readable on the main Ractor only.
 
 ## Configuration
 
@@ -146,6 +151,106 @@ Locallingo::Manager.new(config:).validate           # => [violations]
 Locallingo::QualityChecker.new(config:).check(locale: "en")
 ```
 
+`Locallingo::Configuration.parse(yaml, root_path:, package:)` resolves the same
+config from YAML text (ERB included) instead of reading `.locallingo.yml`. A
+configuration loaded from the file reads it when it is built, never cached.
+
+### Translating text that is not in locale files
+
+`Locallingo::Translator` runs the same prompt (rules, glossary, language guide),
+provider, model and batching over a plain `{ key => text }` hash:
+
+```ruby
+require "ruby_llm" # for RubyLLM.context (Bundler.require already loads it in Rails)
+
+translator = Locallingo::Translator.new(
+  config: Locallingo.configuration(root_path: Dir.pwd),
+  context: RubyLLM.context { |c| c.anthropic_api_key = tenant_key }, # optional, per-tenant key
+  pause: 0                                                           # no sleep between batches
+)
+
+result = translator.translate(
+  { "title" => "Hello", "intro" => "Some **markdown**." },
+  from: "en", to: "de",
+  style: :prose,                                 # :ui (default) or :prose (keeps Markdown, no brevity rule)
+  instructions: "Write in a warm, plain voice."  # appended after the language guide
+)
+result.translations # => { "title" => "Hallo", "intro" => "Etwas **Markdown**." }
+result.failed       # => keys that failed after retries
+```
+
+- Every call runs on a `RubyLLM::Context`: the `context:` given, else one
+  built for that call from the resolved key. The global `RubyLLM.config` is
+  never written, so tenants can translate concurrently.
+- `MissingCredentialsError` is raised before any call when no key is found.
+- `translate.max_batch_chars` (or `max_batch_chars:`) limits the source
+  characters per batch (a single longer value is sent alone, not split); `translate.pause` (or `pause:`) is the sleep after each
+  batch. Retries of failed or omitted keys keep their own backoff.
+- `Locallingo::Prompt.translation(config:, from:, to:, style:, instructions:)`
+  returns the prompt itself.
+
+`Locallingo::Drift` is the missing / outdated / hand-edited rule over the state
+entry shape (`source_hash`, `target_hash`, `manual`), for strings or nested
+values:
+
+```ruby
+drift = Locallingo::Drift.new  # hasher: any callable(String) -> String
+drift.status(source:, target:, entry:)  # => :missing | :outdated | :current
+drift.due?(source:, target:, entry:, force: false, include_manual: false)
+drift.hand_edited?(target:, entry:)
+drift.record(source:, target:, manual: false) # => a new entry
+```
+
+### Translating records
+
+`require "locallingo/active_record"` (ActiveRecord >= 7.1; nothing loads
+ActiveRecord otherwise) adds a concern for a JSON(B) column keyed by locale
+plus a JSON(B) state column:
+
+```ruby
+class Article < ApplicationRecord
+  include Locallingo::Translatable
+
+  translates_content :body,                  # { "en" => { … }, "de" => { … } }
+    state: :translation_state,               # { "de" => { "source_hash", "target_hash", "manual" } }
+    source_locale: -> { "en" },              # String/Symbol, or a callable run on the record
+    target_locales: -> { %w[de sv] },
+    translatable: ->(path, value) { true }   # optional filter on flattened String leaves
+end
+
+article.translation_status(:de)   # => :missing | :outdated | :current
+article.translation_manual?(:de)
+article.translation_due?(:de, force: false)
+article.record_translation(:de, manual: false)
+
+Locallingo::RecordTranslator.new(translator:)
+  .call(Article.where(id: ids), to: "de", style: :prose)
+# => { translated: 3, failed: { article_id => [paths] }, skipped: [ids] }
+```
+
+- Saving a record runs `mark_hand_edits`: a target locale a person changed is
+  flagged `manual` and never machine-overwritten (`include_manual: true`
+  overrides, keeping the flag). That includes a target locale saved for the
+  first time, e.g. a source copy used as a placeholder at `create!`: leave
+  untranslated locales out of the column instead. A cleared locale is not
+  flagged and is due again, unless it was already `manual`: the flag stays, so
+  retranslating it needs `include_manual: true`.
+- `RecordTranslator` sends one batched translation per source locale across all
+  due records, then writes each record under `record.with_lock`. A record whose
+  source changed, or whose target became manual, while the model answered is
+  skipped (`skipped:`) and left for the next run, as is a due record with no
+  translatable text.
+- Nested values keep their shape; leaves the `translatable:` filter rejects are
+  copied from the source. A record with any segment that failed after retries
+  is not written at all: its paths are reported in `failed:`, and it stays due
+  for the next run (your fallback to the source locale applies meanwhile).
+- Writes use `update_columns`; pass `write: ->(record, attributes) { … }` to
+  bump a lock version or run validations.
+- `translates_content` freezes the declaration as it is made, at boot: the
+  column and state names, a String or Array locale option (as a frozen copy)
+  and the drift. Callables are kept as they are, so they may close over app
+  state; like the model itself, a declaration is read on the main Ractor.
+
 ## License
 
 MIT © Mikael Henriksson

data/config/locallingo.default.yml

@@ -26,6 +26,12 @@ defaults:
   translate:
     model: gpt-5-mini
     batch_size: 20
+    # Optional cap on the characters of source text per batch (a batch closes at
+    # batch_size keys or max_batch_chars, whichever comes first). Useful for long
+    # prose; a single oversized value is still sent alone. null = keys only.
+    max_batch_chars: null
+    # Seconds to sleep after each batch (rate-limit courtesy). 0 disables it.
+    pause: 1.0
 
   quality:
     model: gpt-4o-mini

data/lib/locallingo/active_record.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+require_relative "../locallingo"
+require_relative "content_leaves"
+
+module Locallingo
+  # Opt-in ActiveRecord concern (`require "locallingo/active_record"`) for the
+  # common shape: a JSON(B) column keyed by locale plus a JSON(B) state column
+  # holding one Drift entry per target locale. Supports ActiveRecord >= 7.1.
+  #
+  #   class Article < ApplicationRecord
+  #     include Locallingo::Translatable
+  #
+  #     translates_content :body,                # { "en" => { … }, "de" => { … } }
+  #       state: :translation_state,             # { "de" => { "source_hash", "target_hash", "manual" } }
+  #       source_locale: -> { "en" },            # String/Symbol, or a callable run on the record
+  #       target_locales: -> { %w[de sv] },
+  #       translatable: ->(path, value) { true } # optional filter on flattened String leaves
+  #   end
+  #
+  # A `before_save` callback (#mark_hand_edits) flags target locales a person
+  # changed as manual, so Locallingo::RecordTranslator never overwrites them.
+  module Translatable
+    extend ActiveSupport::Concern
+
+    Definition = Data.define(:column, :state, :source_locale, :target_locales, :translatable, :drift)
+
+    included do
+      # The model's declaration: written once by translates_content in its class
+      # body at boot (main Ractor), and only read after that.
+      class_attribute :locallingo_translatable, instance_writer: false # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+    end
+
+    class_methods do
+      # The declaration is frozen as it is made, at boot: the column and state
+      # names and a String/Symbol/Array locale option (frozen copies; the
+      # caller's own objects are left alone), and the Drift. Callables (locale options,
+      # translatable:, hasher:) are kept as they are, so a declaration holding
+      # one is read on the main Ractor only, like the model itself.
+      def translates_content(column, state:, source_locale:, target_locales:, translatable: nil, hasher: nil)
+        self.locallingo_translatable = Definition.new(
+          column: Translatable.frozen_option(column.to_s), state: Translatable.frozen_option(state.to_s),
+          source_locale: Translatable.frozen_option(source_locale),
+          target_locales: Translatable.frozen_option(target_locales),
+          translatable: translatable || ->(_path, _value) { true },
+          drift: (hasher ? Drift.new(hasher:) : Drift.new).freeze
+        )
+        before_save :mark_hand_edits
+      end
+    end
+
+    # A frozen copy of a non-callable declaration option (a String, or an Array
+    # of them); a callable or an already frozen value comes back as it is.
+    def self.frozen_option(value)
+      case value
+      when Array then value.map { |item| frozen_option(item) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+
+    def translation_source_locale = resolve_translation_option(locallingo_translatable.source_locale).to_s
+
+    def translation_target_locales
+      Array(resolve_translation_option(locallingo_translatable.target_locales)).map(&:to_s)
+    end
+
+    def translation_source = translation_content[translation_source_locale]
+    def translation_target(locale) = translation_content[locale.to_s]
+    def translation_entry(locale) = translation_states[locale.to_s]
+    def translation_source_digest = translation_drift.digest(translation_source)
+
+    def translation_status(locale)
+      translation_drift.status(source: translation_source, target: translation_target(locale),
+                               entry: translation_entry(locale))
+    end
+
+    def translation_manual?(locale) = translation_drift.manual?(translation_entry(locale))
+
+    def translation_due?(locale, force: false, include_manual: false)
+      translation_drift.due?(source: translation_source, target: translation_target(locale),
+                             entry: translation_entry(locale), force:, include_manual:)
+    end
+
+    # Records the current source and target of +locale+ as its state entry
+    # (assigned, not saved).
+    def record_translation(locale, manual: false)
+      entry = translation_drift.record(source: translation_source, target: translation_target(locale), manual:)
+      self[locallingo_translatable.state] = translation_states.merge(locale.to_s => entry)
+    end
+
+    # Flags every target locale a person changed as manual: a recorded target
+    # that no longer matches its target_hash, or an untracked locale written in
+    # this save. A cleared target is not flagged — it is missing and due again.
+    def mark_hand_edits
+      (translation_target_locales - [translation_source_locale]).each do |locale|
+        target = translation_target(locale)
+        next if translation_drift.blank?(target)
+
+        entry = translation_entry(locale)
+        next unless translation_drift.hand_edited?(target:, entry:) || (entry.nil? && translation_written?(locale))
+
+        # A recorded source_hash is kept: a hand edit does not make an
+        # outdated translation current.
+        manual = translation_drift.record(source: translation_source, target:, manual: true)
+        manual["source_hash"] = entry["source_hash"] if entry&.key?("source_hash")
+        self[locallingo_translatable.state] = translation_states.merge(locale => manual)
+      end
+    end
+
+    # The source's translatable String leaves, flattened (`steps[1].text`,
+    # `table[0][1]`). Unlike KeyFlattener, strings in nested arrays count.
+    def translation_segments
+      translation_leaves.filter_map do |path, (_, value)|
+        next unless value.is_a?(String) && !value.strip.empty?
+
+        [path, value] if locallingo_translatable.translatable.call(path, value)
+      end.to_h
+    end
+
+    # The target for translated +segments+ (`path => text`): a deep copy of the
+    # source with each translated leaf set in place, so every other value and
+    # container (numbers, nested lists, empty ones) keeps its place.
+    def build_translation_target(segments)
+      target = JSON.parse(JSON.generate(translation_source || {}))
+      leaves = translation_leaves
+      segments.each do |path, text|
+        *parents, last = leaves.fetch(path).first
+        (parents.empty? ? target : target.dig(*parents))[last] = text
+      end
+      target
+    end
+
+    # Column attributes that write +target+ for +locale+ plus its state entry.
+    def translation_attributes(locale, target, manual: false)
+      locale = locale.to_s
+      entry = translation_drift.record(source: translation_source, target:, manual:)
+      {
+        locallingo_translatable.column => translation_content.merge(locale => target),
+        locallingo_translatable.state => translation_states.merge(locale => entry)
+      }
+    end
+
+    def translation_drift = locallingo_translatable.drift
+
+    private
+
+    def translation_leaves = ContentLeaves.call(translation_source || {}, label: "#{self.class.name}##{id}")
+
+    def translation_content = self[locallingo_translatable.column] || {}
+    def translation_states = self[locallingo_translatable.state] || {}
+
+    def translation_written?(locale)
+      column = locallingo_translatable.column
+      return false unless will_save_change_to_attribute?(column)
+
+      (attribute_in_database(column) || {})[locale] != translation_target(locale)
+    end
+
+    def resolve_translation_option(option)
+      option.respond_to?(:call) ? instance_exec(&option) : option
+    end
+  end
+end

data/lib/locallingo/batch_translator.rb

@@ -17,10 +17,16 @@ module Locallingo
     BASE_SLEEP_DURATION = 1.0
 
     # `log` is called as `log.call(message, level: :info)`.
-    def initialize(provider:, model:, batch_size:, log:)
+    #
+    # A batch closes at `batch_size` keys or `max_batch_chars` characters of
+    # source text, whichever comes first; a single oversized value goes alone.
+    # `pause` is the sleep after each batch (0 in a background job).
+    def initialize(provider:, model:, batch_size:, log:, max_batch_chars: nil, pause: BASE_SLEEP_DURATION)
       @provider = provider
       @model = model
       @batch_size = batch_size
+      @max_batch_chars = max_batch_chars
+      @pause = pause
       @log = log
     end
 
@@ -66,7 +72,7 @@ module Locallingo
       translations = {}
       failed = []
 
-      keys.each_slice(@batch_size) do |batch|
+      batches(keys).each do |batch|
         result = translate_batch(batch.to_h { |key| [key, @source[key]] })
         batch.each do |key|
           if result.key?(key) && !result[key].to_s.empty?
@@ -75,12 +81,29 @@ module Locallingo
             failed << key
           end
         end
-        sleep(BASE_SLEEP_DURATION)
+        sleep(@pause) if @pause.positive?
       end
 
       [translations, failed]
     end
 
+    def batches(keys)
+      return keys.each_slice(@batch_size).to_a unless @max_batch_chars
+
+      keys.each_with_object([[]]) do |key, groups|
+        groups << [] if full?(groups.last, key)
+        groups.last << key
+      end
+    end
+
+    def full?(batch, key)
+      return false if batch.empty?
+
+      batch.size >= @batch_size || chars(batch) + chars([key]) > @max_batch_chars
+    end
+
+    def chars(batch) = batch.sum { |key| @source[key].to_s.length }
+
     def translate_batch(payload)
       return {} if payload.empty?
 

data/lib/locallingo/configuration.rb

@@ -14,9 +14,12 @@ module Locallingo
   #
   # Typed readers expose everything the Manager/QualityChecker/CLI need, so no
   # other class parses raw config hashes.
+  #
+  # The file is read when a Configuration is built (the CLI builds one per run)
+  # and never cached in the process, so an edit applies to the next run.
   class Configuration
     CONFIG_FILENAMES = %w[.locallingo.yml .locallingo.yaml].freeze
-    DEFAULT_CONFIG_PATH = File.expand_path("../../config/locallingo.default.yml", __dir__)
+    DEFAULT_CONFIG_PATH = File.expand_path("../../config/locallingo.default.yml", __dir__).freeze
 
     attr_reader :root_path, :package, :data
 
@@ -26,10 +29,18 @@ module Locallingo
       new(root_path:, package:)
     end
 
-    def initialize(root_path: Dir.pwd, package: nil, data: nil)
+    # Resolve config from YAML +text+ (what a `.locallingo.yml` holds, ERB
+    # included) instead of the file under +root_path+, merged over the shipped
+    # defaults the same way.
+    def self.parse(text, root_path: Dir.pwd, package: nil)
+      new(root_path:, package:, source: text)
+    end
+
+    # +source+ is YAML text read in place of the config file (see .parse).
+    def initialize(root_path: Dir.pwd, package: nil, data: nil, source: nil)
       @root_path = File.expand_path(root_path)
       @package = package
-      @data = data || resolve
+      @data = data || resolve(source)
     end
 
     # --- locations -----------------------------------------------------------
@@ -54,6 +65,8 @@ module Locallingo
     def provider = data.fetch("provider").to_sym
     def translate_model = dig("translate", "model")
     def batch_size = dig("translate", "batch_size")
+    def max_batch_chars = dig("translate", "max_batch_chars")
+    def pause = dig("translate", "pause") || 1.0
     def quality_model = dig("quality", "model")
     def quality_sample_size = dig("quality", "sample_size")
     def british_spellings? = !!dig("quality", "british_spellings")
@@ -111,9 +124,10 @@ module Locallingo
     def dig(*keys) = data.dig(*keys)
 
     # Merge: shipped defaults <- user `defaults:` <- selected `packages:` entry.
-    def resolve
-      merged = deep_merge(shipped_defaults, user_defaults)
-      merged = deep_merge(merged, package_overrides) if package
+    def resolve(source)
+      document, origin = user_config(source)
+      merged = deep_merge(shipped_defaults, document.fetch("defaults", {}) || {})
+      merged = deep_merge(merged, package_overrides(document, origin)) if package && origin
       merged
     end
 
@@ -121,20 +135,19 @@ module Locallingo
       load_yaml(DEFAULT_CONFIG_PATH).fetch("defaults", {})
     end
 
-    def user_defaults
-      file = config_file
-      return {} unless file
+    # The user's config and where it came from: the +source+ text, else the
+    # config file under root_path, else nothing.
+    def user_config(source)
+      return [parse_yaml(source), "the given YAML"] if source
 
-      load_yaml(file).fetch("defaults", {}) || {}
-    end
-
-    def package_overrides
       file = config_file
-      return {} unless file
+      file ? [load_yaml(file), file] : [{}, nil]
+    end
 
-      packages = load_yaml(file).fetch("packages", []) || []
+    def package_overrides(document, origin)
+      packages = document.fetch("packages", []) || []
       entry = packages.find { |p| p["path"] == package }
-      raise Error, "No package #{package.inspect} in #{file}" unless entry
+      raise Error, "No package #{package.inspect} in #{origin}" unless entry
 
       entry.except("path")
     end
@@ -145,10 +158,19 @@ module Locallingo
         .find { |path| File.exist?(path) }
     end
 
-    def load_yaml(path)
-      YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}
+    def load_yaml(path) = parse_yaml(File.read(path))
+
+    def parse_yaml(text)
+      YAML.safe_load(ERB.new(text).result(erb_binding), aliases: true) || {}
     end
 
+    # ERB's default binding is TOPLEVEL_BINDING, which a non-main Ractor cannot
+    # reach; a blank object's binding evaluates the same templates. The string
+    # form, not a block: a block would resolve constants from inside
+    # Locallingo::Configuration (`Settings` would be Locallingo::Settings), the
+    # string resolves them from the top level, as TOPLEVEL_BINDING did.
+    def erb_binding = Object.new.instance_eval("binding", __FILE__, __LINE__)
+
     def deep_merge(base, override)
       base.merge(override) do |_key, base_val, override_val|
         if base_val.is_a?(Hash) && override_val.is_a?(Hash)

data/lib/locallingo/content_leaves.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Locallingo
+  # Walks a nested Hash/Array value to its leaves, keyed by a KeyFlattener-style
+  # path (`steps[1].text`, `table[0][1]`). Unlike KeyFlattener, strings inside
+  # nested arrays count, and each leaf carries the Hash keys and Array indices
+  # leading to it, so a value can be set back in place without parsing paths.
+  module ContentLeaves
+    module_function
+
+    # `path => [parts, value]`. Two leaves with the same path (a literal "a.b"
+    # key next to a → b) raise: one would be silently dropped from translation.
+    def call(value, label: "content")
+      collect(value, [], {}, label)
+    end
+
+    def collect(value, parts, leaves, label)
+      case value
+      when Hash then value.each { |key, item| collect(item, parts + [key.to_s], leaves, label) }
+      when Array then value.each_with_index { |item, index| collect(item, parts + [index], leaves, label) }
+      else
+        path = path(parts)
+        raise Error, "Ambiguous translation path #{path.inspect} in #{label}" if leaves.key?(path)
+
+        leaves[path] = [parts, value]
+      end
+      leaves
+    end
+
+    def path(parts)
+      parts.each_with_index.map do |part, index|
+        next "[#{part}]" if part.is_a?(Integer)
+
+        index.zero? ? part : ".#{part}"
+      end.join
+    end
+
+    private_class_method :collect, :path
+  end
+end