locallingo 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47b5cfaffa1567e536de600f6f963538606fc386a89b61e90ad9cc4dd8327132
-  data.tar.gz: 767fa1b9c49c66a0b5b5e1bd6140edbca50edade201f415c9bfde2c6f0448206
+  metadata.gz: '08b89ac361ed67239fe3e8574396cf5ffb1b0fb20a04385cea02d350b608d503'
+  data.tar.gz: 2de02e7a1ca34d339bff982427a411bb299c02907d3d8545e8dcb1092a747031
 SHA512:
-  metadata.gz: fad2120d8032a4a019dda5f6c82cd2f597de9dd79f9bb4eab1b9026530c859316c232314325398f51e12d61fc043c95882960969d5be325a80e6676463b55862
-  data.tar.gz: ff18516ac297ff0612111d0326552e6e771a6e0299854c598f3ea5645e9baaf722dd80e2571fc68186f3225af3eb35a69dc496107904feedd2cfc9d7356b1e8a
+  metadata.gz: b488c4209a18715d8772e2616b2bf80eeafe0973d0a97be9fc5da8b01417308550aac86fc3b512fec3cd480964aac0281e02a126319a882aaf4fb49776748bae
+  data.tar.gz: b4c13e6f0ca99cb0a0a54b1d56be91dad3b5810cf40f771ac653e63ec2f2ab3bf24fa460e1ecb661c7ac280f0ef4961df1a9b97070a991f8fce6c39244b14666

data/CHANGELOG.md

@@ -4,7 +4,25 @@ 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]
+## [Unreleased]
+
+### Added
+- `Translator#translate(…, placeholders:)` takes a list of Regexps (default:
+  the new `translate.placeholders` config key, regex strings, `[]`) for the
+  tokens the texts use. The prompt names the patterns, and a value whose
+  tokens differ from its source's (exact text, by count) is re-requested in
+  the omitted-key rounds, then reported in `failed` instead of returned.
+  `Locallingo::Placeholders` is the check. (#43)
+- `Translator::Result#rejections` (`{ key => { "missing" => [...], "extra" =>
+  [...] } }`) and `BatchTranslator.new(…, accept:)`, whose `call` now returns
+  `[translations, failed, rejections]`. `RecordTranslator#call` passes
+  `placeholders:` through. The `lingo` CLI is unchanged. (#43)
+- `QualityChecker#check_texts(texts, locale:, use_ai: false)` runs the static
+  checks, terminology, British spellings and the optional AI review over a
+  `{ key => text }` hash instead of the locale files; `QualityChecker.new`
+  takes `context:` (a `RubyLLM::Context`) for the AI pass. (#43)
+
+## [0.6.0] - 2026-10-15
 
 ### Added
 - `Locallingo::Configuration.parse(text, root_path:, package:)` resolves
@@ -49,7 +67,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   longer evaluates on `TOPLEVEL_BINDING` (templates still resolve constants
   from the top level, as the app sees them). (#35)
 
-## [Unreleased]
+## [0.5.1] - 2026-10-13
 
 ### Added
 - `Locallingo::Translator#translate(texts, from:, to:, style:, instructions:)`
@@ -73,6 +91,10 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `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)
+
+## [0.5.0] - 2026-10-09
+
+### Added
 - `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
@@ -126,19 +148,46 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   and column inside the fence instead of the fence at line 1. (#25)
 - The translation prompt asks the model to escape `"` inside values as `\"`
   and keep typographic quotes (“ ” „ ‚ « ») as they appear in the source. (#25)
+- The `duplicate_values` validator reports findings under the configured
+  `source_locale` instead of a hard-coded `en`. (#15)
+
+## [0.4.3] - 2026-08-23
+
+### Changed
+- Allow `ruby_llm` 2.x (dependency constraint widened from `< 2` to `< 3`). The
+  gem only uses RubyLLM's stable chat API and guarded config accessors, so a
+  host app can take the RubyLLM 2.0 bump without waiting on Locallingo.
+
+## [0.4.2] - 2026-08-18
+
+### Fixed
 - State files are written with a trailing final newline, so the output is
   POSIX-conformant and files that already end with a newline are no longer
   rewritten with newline-only diffs. One-time effect after upgrading: each
   state file gets a single newline-adding rewrite, then stabilizes. (#7)
+
+## [0.4.1] - 2026-07-16
+
+### Fixed
 - `lingo sync` backfills a missing `target_hash` from the current target value,
   so hand-added translations (written straight into the YAML, never passing
   through `translate` or `accept-edits`) get a baseline and the `manual_edits`
   validator can watch them. An existing `target_hash` is still never
   recomputed — that would silently absorb hand-edit drift.
-- The `duplicate_values` validator reports findings under the configured
-  `source_locale` instead of a hard-coded `en`. (#15)
 
-### Fixed (0.4.0)
+## [0.4.0] - 2026-07-16
+
+### Changed
+- Unscoped `lingo accept-edits` now accepts only the keys the `manual_edits`
+  validator flags (actually hand-edited), instead of stamping `manual: true` on
+  every key of the locale. Use the new `--key KEY` (repeatable) for surgical
+  accepts, or `--all` for the old blanket behavior (initial adoption).
+- Validator suggestions are scoped and safe to follow verbatim: `manual_edit`
+  violations suggest `accept-edits --locale <l> --key <key>`, and `outdated`
+  violations on manual keys tell you to update the value by hand and re-accept
+  it rather than force-translating over curated text.
+
+### Fixed
 - `lingo sync` no longer destroys hand-edit protection: it now only refreshes
   each entry's `source_hash` and preserves `target_hash` and `manual: true`
   (the pre-extraction `bin/translate` behavior). Previously a single sync wiped
@@ -150,15 +199,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - State files whose content is unchanged are no longer rewritten, so operations
   never touch `.i18n-state/` files for unrelated namespaces.
 
-### Changed
-- Unscoped `lingo accept-edits` now accepts only the keys the `manual_edits`
-  validator flags (actually hand-edited), instead of stamping `manual: true` on
-  every key of the locale. Use the new `--key KEY` (repeatable) for surgical
-  accepts, or `--all` for the old blanket behavior (initial adoption).
-- Validator suggestions are scoped and safe to follow verbatim: `manual_edit`
-  violations suggest `accept-edits --locale <l> --key <key>`, and `outdated`
-  violations on manual keys tell you to update the value by hand and re-accept
-  it rather than force-translating over curated text.
+## [0.3.0] - 2026-07-15
 
 ### Added
 - `Locallingo.configure { |c| c.anthropic_api_key = ... }` — gem-level provider
@@ -168,6 +209,21 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `.locallingo.rb` setup file: the CLI loads it from the project root before
   dispatch, so standalone `lingo` runs can configure credentials without
   booting Rails.
+
+## [0.2.2] - 2026-07-13
+
+### Fixed
+- `lingo translate` and `lingo quality --ai` read the provider API key from
+  ENV (e.g. `ANTHROPIC_API_KEY`) when RubyLLM has none configured; a key
+  configured by the host app still wins. (#2)
+
+## [0.2.1] - 2026-07-07
+
+No gem changes (documentation site only).
+
+## [0.2.0] - 2026-07-07
+
+### Added
 - Initial extraction from the `bin/translate` toolchain into a standalone gem.
 - `lingo` CLI with subcommands: `status`, `translate`, `validate`, `quality`,
   `fix-quality`, `accept-edits`, `hash`, `sync`. Legacy `--flag` forms still work

data/README.md

@@ -151,6 +151,19 @@ Locallingo::Manager.new(config:).validate           # => [violations]
 Locallingo::QualityChecker.new(config:).check(locale: "en")
 ```
 
+`QualityChecker#check_texts(texts, locale:, use_ai: false)` runs the same
+static checks, terminology, British spellings and optional AI review over a
+`{ key => text }` hash instead of the locale files, and returns the same
+suggestion hashes. With `use_ai: true` every given key is reviewed (no
+sampling). `QualityChecker.new(…, context:)` takes a `RubyLLM::Context` for
+the AI pass, as `Translator.new` does:
+
+```ruby
+checker = Locallingo::QualityChecker.new(config:, context: RubyLLM.context { |c| c.anthropic_api_key = key })
+checker.check_texts(result.translations, locale: "de", use_ai: true)
+# => [{ key:, text:, locale:, category:, issue:, match:, severity:, source: :static | :ai }, …]
+```
+
 `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.
@@ -186,9 +199,32 @@ result.failed       # => keys that failed after retries
 - `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:)`
+- `Locallingo::Prompt.translation(config:, from:, to:, style:, instructions:, placeholders:)`
   returns the prompt itself.
 
+Texts with their own token syntax (a template language, an interpolation
+format other than `placeholder_style`) pass `placeholders:`, a list of Regexps
+(default: `translate.placeholders`, regex strings compiled with `Regexp::MULTILINE`, `[]`). The prompt names the
+patterns, and each reply is checked: the tokens every pattern matches in a
+value must equal its source's, compared on the exact text and by count (order
+may change). A value that differs is re-requested in the omitted-key rounds;
+one that still differs is never returned, but listed in `failed` and in
+`rejections`:
+
+```ruby
+LIQUID = [/\{\{.*?\}\}/m, /\{%.*?%\}/m]
+
+result = translator.translate(texts, from: "en", to: "de", style: :prose, placeholders: LIQUID)
+result.translations # only values whose tokens match their source
+result.failed       # => ["body"]
+result.rejections   # => { "body" => { "missing" => ["{% paragraph %}"], "extra" => [] } }
+```
+
+`Locallingo::Placeholders.compare(source, translated, patterns)` is the check
+itself (`nil` when the tokens match). `RecordTranslator#call` takes
+`placeholders:` too; a record with a rejected segment is not written. The
+`lingo` CLI does not use `translate.placeholders`.
+
 `Locallingo::Drift` is the missing / outdated / hand-edited rule over the state
 entry shape (`source_hash`, `target_hash`, `manual`), for strings or nested
 values:

data/config/locallingo.default.yml

@@ -32,6 +32,11 @@ defaults:
     max_batch_chars: null
     # Seconds to sleep after each batch (rate-limit courtesy). 0 disables it.
     pause: 1.0
+    # Regex patterns (strings) for tokens the Translator API must keep exactly,
+    # e.g. ['\{\{.*?\}\}', '\{%.*?%\}'] for Liquid (`.` spans lines). A reply whose tokens differ
+    # from its source (by count) is retried, then reported as failed. The
+    # `lingo` CLI does not use it. [] = no check.
+    placeholders: []
 
   quality:
     model: gpt-4o-mini

data/lib/locallingo/batch_translator.rb

@@ -11,6 +11,8 @@ module Locallingo
   #   down to single keys, so a bad value costs only its own key.
   # - Keys the model omitted are re-batched for a few rounds; keys whose own
   #   one-key reply could not be parsed are not.
+  # - A value the `accept` callable rejects is treated like an omitted key: it
+  #   joins those rounds, and is reported with its reason if still rejected.
   class BatchTranslator
     MAX_RETRIES = 3
     MAX_MISSING_RETRIES = 2
@@ -21,28 +23,34 @@ module Locallingo
     # 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)
+    # `accept` is called as `accept.call(key, source_text, translated_text)`
+    # and returns true to keep the value, or a Hash: the rejection reason.
+    def initialize(provider:, model:, batch_size:, log:, max_batch_chars: nil, pause: BASE_SLEEP_DURATION,
+                   accept: nil)
       @provider = provider
       @model = model
       @batch_size = batch_size
       @max_batch_chars = max_batch_chars
       @pause = pause
       @log = log
+      @accept = accept
     end
 
     # Translates `keys` (looked up in `source`) and returns
-    # `[translations, failed_keys]`.
+    # `[translations, failed_keys, rejections]`; `rejections` maps each failed
+    # key whose reply in its last round `accept` rejected to the reason.
     def call(source, keys, instructions:)
       @source = source
       @instructions = instructions
       @unparseable = []
+      @rejections = {}
 
       translated, missing = translate_keys(keys)
       missing = retry_missing(translated, missing)
 
       failed = missing + @unparseable
       report_failed(failed)
-      [translated, failed]
+      [translated, failed, @rejections]
     end
 
     private
@@ -75,7 +83,8 @@ module Locallingo
       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?
+          @rejections.delete(key)
+          if result.key?(key) && !result[key].to_s.empty? && accepted?(key, result[key])
             translations[key] = result[key]
           else
             failed << key
@@ -87,6 +96,17 @@ module Locallingo
       [translations, failed]
     end
 
+    def accepted?(key, value)
+      return true unless @accept
+
+      verdict = @accept.call(key, @source[key], value)
+      return true if verdict == true
+
+      @rejections[key] = verdict.is_a?(Hash) ? verdict : {}
+      log("  Rejected #{key}: #{@rejections[key]}", level: :warn)
+      false
+    end
+
     def batches(keys)
       return keys.each_slice(@batch_size).to_a unless @max_batch_chars
 

data/lib/locallingo/configuration.rb

@@ -72,6 +72,13 @@ module Locallingo
     def british_spellings? = !!dig("quality", "british_spellings")
     def terminology_setting = dig("quality", "terminology")
 
+    # Token patterns (`translate.placeholders`, regex strings compiled with
+    # Regexp::MULTILINE, so `.` spans lines) whose matches a Translator must
+    # keep unchanged; [] by default.
+    def placeholders
+      Array(dig("translate", "placeholders")).map { |pattern| compile_placeholder(pattern) }.freeze
+    end
+
     # --- prompt scaffolding --------------------------------------------------
 
     def context = data.fetch("context", "a business application")
@@ -123,6 +130,17 @@ module Locallingo
 
     def dig(*keys) = data.dig(*keys)
 
+    def compile_placeholder(pattern)
+      return pattern.dup.freeze if pattern.is_a?(Regexp)
+      unless pattern.is_a?(String)
+        raise Error, "translate.placeholders: expected a regex string, got #{pattern.inspect}"
+      end
+
+      Regexp.new(pattern, Regexp::MULTILINE).freeze
+    rescue RegexpError => e
+      raise Error, "translate.placeholders: #{pattern.to_s.inspect} is not a valid regular expression (#{e.message})"
+    end
+
     # Merge: shipped defaults <- user `defaults:` <- selected `packages:` entry.
     def resolve(source)
       document, origin = user_config(source)

data/lib/locallingo/placeholders.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Locallingo
+  # Token checks for translated text: the tokens a list of patterns matches
+  # (`{{ item.name }}`, `%{count}`, …) must survive translation unchanged, in
+  # the same count. Order may change, since word order does. Pure functions
+  # over their arguments.
+  module Placeholders
+    module_function
+
+    # Every whole match of every pattern in +text+, pattern by pattern.
+    def tokens(text, patterns)
+      patterns.flat_map { |pattern| text.to_s.gsub(pattern).to_a }
+    end
+
+    # nil when +translated+ holds exactly the tokens of +source+, else
+    # `{ "missing" => [...], "extra" => [...] }` (multiset difference on the
+    # exact matched text).
+    def compare(source, translated, patterns)
+      before = tokens(source, patterns).tally
+      after = tokens(translated, patterns).tally
+      missing = difference(before, after)
+      extra = difference(after, before)
+      return nil if missing.empty? && extra.empty?
+
+      { "missing" => missing, "extra" => extra }
+    end
+
+    def difference(counts, other)
+      counts.flat_map { |token, count| [token] * [count - other.fetch(token, 0), 0].max }
+    end
+
+    private_class_method :difference
+  end
+end

data/lib/locallingo/prompt.rb

@@ -22,7 +22,7 @@ module Locallingo
 
     module_function
 
-    def translation(config:, from:, to:, style: :ui, instructions: nil)
+    def translation(config:, from:, to:, style: :ui, instructions: nil, placeholders: [])
       raise Error, "Unknown prompt style #{style.inspect} (expected one of #{STYLES.join(", ")})" unless
         STYLES.include?(style.to_s.to_sym)
 
@@ -41,7 +41,7 @@ module Locallingo
 
         ## General Rules
         - Preserve placeholders like #{config.placeholder_style} exactly as they appear
-        - Preserve HTML tags if present
+        #{placeholders_rule(placeholders)}- Preserve HTML tags if present
         #{style.to_sym == :prose ? MARKDOWN_RULES : BREVITY_RULE}- Escape every double quote (") inside a translated value as \\" so the reply stays valid JSON
         - Keep typographic quotes (“ ” „ ‚ « ») exactly as they appear in the source
         #{glossary_section(config)}#{language_guide_section(config, to)}#{instructions_section(instructions)}
@@ -51,6 +51,14 @@ module Locallingo
       PROMPT
     end
 
+    def placeholders_rule(patterns)
+      patterns = Array(patterns)
+      return "" if patterns.empty?
+
+      sources = patterns.map { |pattern| "`#{pattern.source}`" }.join(", ")
+      "- Preserve every token matching these patterns exactly as it appears, with the same count: #{sources}\n"
+    end
+
     def glossary_section(config)
       return "" if config.glossary.empty?
 
@@ -68,6 +76,6 @@ module Locallingo
       text.empty? ? "" : "\n## Additional Instructions\n#{text}\n"
     end
 
-    private_class_method :glossary_section, :language_guide_section, :instructions_section
+    private_class_method :placeholders_rule, :glossary_section, :language_guide_section, :instructions_section
   end
 end

data/lib/locallingo/quality_checker.rb

@@ -16,6 +16,9 @@ module Locallingo
   # optional British-spelling drift, and a very-long-text heuristic. An optional
   # AI pass (RubyLLM) reviews a sample for clarity/professionalism.
   #
+  # `check` and `check_key` read the locale files; `check_texts` runs the same
+  # checks over a `{ key => text }` hash held anywhere else.
+  #
   # `fix!` rewrites the auto-fixable suggestions (universal fixes + British
   # spellings) back into the locale files, preserving case.
   class QualityChecker
@@ -23,11 +26,13 @@ module Locallingo
 
     attr_reader :config, :verbose, :logger
 
-    def initialize(config: nil, root_path: nil, package: nil, verbose: false, logger: nil)
+    # +context+ is an optional RubyLLM::Context the AI pass runs on (e.g. a
+    # per-call key), as for Translator.
+    def initialize(config: nil, root_path: nil, package: nil, verbose: false, logger: nil, context: nil)
       @config = config || Configuration.load(root_path: root_path || Dir.pwd, package:)
       @verbose = verbose
       @logger = logger
-      @provider = Providers::RubyLLM.new(provider: @config.provider)
+      @provider = Providers::RubyLLM.new(provider: @config.provider, context:)
       @terminology = Quality::Terminology.new(@config.terminology_setting, base_path: @config.base_path)
     end
 
@@ -37,20 +42,26 @@ module Locallingo
     def check(locale: nil, use_ai: false, prefix: nil, keys: nil)
       locale ||= config.source_locale
       translations = scoped_translations(locale, prefix:, keys:)
+      return check_texts(translations, locale:, use_ai:) if keys || !use_ai
 
-      suggestions = translations.flat_map { |key, text| check_text(key, text, locale) }
-      suggestions.concat(keys ? suggest_improvements(translations, locale) : ai_sample(translations, locale)) if use_ai
-      suggestions
+      check_texts(translations, locale:).concat(ai_sample(translations, locale))
     end
 
     # Check a single key.
     def check_key(key, locale, use_ai: false)
-      translations = load_locale_translations(locale)
-      text = translations[key]
+      text = load_locale_translations(locale)[key]
       return [{ key:, error: "Key not found" }] unless text
 
-      suggestions = check_text(key, text, locale)
-      suggestions.concat(suggest_improvements({ key => text }, locale)) if use_ai
+      check_texts({ key => text }, locale:, use_ai:)
+    end
+
+    # Check a `{ key => text }` hash without reading any file: the static
+    # checks on every pair, then, with +use_ai+, the AI pass over every given
+    # key (unsampled). Returns the suggestion hashes `check` returns.
+    def check_texts(texts, locale:, use_ai: false)
+      texts = stringify_keys(texts).select { |_key, text| text.is_a?(String) }
+      suggestions = texts.flat_map { |key, text| check_text(key, text, locale) }
+      suggestions.concat(suggest_improvements(texts, locale)) if use_ai && texts.any?
       suggestions
     end
 
@@ -105,6 +116,14 @@ module Locallingo
       suggestions.compact
     end
 
+    def stringify_keys(texts)
+      texts.each_with_object({}) do |(key, text), all|
+        raise Error, "Duplicate key #{key.to_s.inspect} (e.g. :#{key} and \"#{key}\")" if all.key?(key.to_s)
+
+        all[key.to_s] = text
+      end
+    end
+
     def british_spellings_for?(locale)
       config.british_spellings? && locale.to_s == config.source_locale.to_s
     end

data/lib/locallingo/record_translator.rb

@@ -13,7 +13,8 @@ module Locallingo
   # its row lock, after re-checking that its source is unchanged and the
   # target is still due: a source edited or a target hand-written while the
   # model answered is skipped and left for the next run. A record with any
-  # failed segment is not written; it stays due and its paths are reported.
+  # failed segment (including one whose tokens did not survive, with
+  # `placeholders:`) is not written; it stays due and its paths are reported.
   #
   # Records must be persisted and of one model (ids are the key prefix). This
   # class never loads ActiveRecord itself; records only need the concern.
@@ -30,7 +31,8 @@ module Locallingo
       @write = write
     end
 
-    def call(records, to:, style: :ui, instructions: nil, force: false, include_manual: false)
+    # +placeholders+ is passed to Translator#translate (nil: its default).
+    def call(records, to:, style: :ui, instructions: nil, force: false, include_manual: false, placeholders: nil)
       @locale = to.to_s
       @force = force
       @include_manual = include_manual
@@ -39,7 +41,7 @@ module Locallingo
       due, empty = records.select { |record| due?(record) }.partition { |record| record.translation_segments.any? }
       @result[:skipped].concat(empty.map(&:id))
       due.group_by(&:translation_source_locale).each do |from, group|
-        translate_group(group, from:, style:, instructions:)
+        translate_group(group, from:, style:, instructions:, placeholders:)
       end
       @result
     end
@@ -48,7 +50,7 @@ module Locallingo
 
     def due?(record) = record.translation_due?(@locale, force: @force, include_manual: @include_manual)
 
-    def translate_group(records, from:, style:, instructions:)
+    def translate_group(records, from:, style:, instructions:, placeholders:)
       digests = records.to_h { |record| [record, record.translation_source_digest] }
       owners = {}
       segments = records.each_with_object({}) do |record, all|
@@ -61,7 +63,7 @@ module Locallingo
         end
       end
 
-      result = @translator.translate(segments, from:, to: @locale, style:, instructions:)
+      result = @translator.translate(segments, from:, to: @locale, style:, instructions:, placeholders:)
       records.each do |record|
         translations = own(result.translations, owners, record).to_h
         failed = own(result.failed.to_h { |key| [key, nil] }, owners, record).map(&:first)

data/lib/locallingo/translator.rb

@@ -6,6 +6,7 @@ require_relative "configuration"
 require_relative "prompt"
 require_relative "providers/ruby_llm"
 require_relative "batch_translator"
+require_relative "placeholders"
 
 module Locallingo
   # The public, file-agnostic entry point: translates a plain `{ key => text }`
@@ -19,11 +20,19 @@ module Locallingo
   #   result = translator.translate({ "title" => "Hello" }, from: "en", to: "de", style: :prose)
   #   result.translations # => { "title" => "Hallo" }
   #   result.failed       # => []
+  #   result.rejections   # => {}
   #
   # Batching, retries, batch halving and omitted-key rounds come from
   # BatchTranslator. Blank texts are not sent.
+  #
+  # With `placeholders:` (Regexps; default `translate.placeholders`), a value
+  # whose tokens differ from its source's is re-requested in those rounds and,
+  # if it still differs, reported in `failed` and `rejections` instead of
+  # returned.
   class Translator
-    Result = Data.define(:translations, :failed)
+    Result = Data.define(:translations, :failed, :rejections) do
+      def initialize(translations:, failed:, rejections: {}) = super
+    end
 
     attr_reader :config
 
@@ -38,15 +47,16 @@ module Locallingo
     end
 
     # Raises MissingCredentialsError before any call when no key is available.
-    def translate(texts, from:, to:, style: :ui, instructions: nil)
+    def translate(texts, from:, to:, style: :ui, instructions: nil, placeholders: nil)
+      patterns = placeholder_patterns(placeholders)
       @provider.ensure_credentials!
 
       source = stringify_keys(texts).reject { |_key, text| text.to_s.strip.empty? }
-      return Result.new(translations: {}, failed: []) if source.empty?
+      return Result.new(translations: {}, failed: [], rejections: {}) if source.empty?
 
-      prompt = Prompt.translation(config:, from:, to:, style:, instructions:)
-      translated, failed = batch_translator.call(source, source.keys, instructions: prompt)
-      Result.new(translations: translated.slice(*source.keys).except(*failed), failed:)
+      prompt = Prompt.translation(config:, from:, to:, style:, instructions:, placeholders: patterns)
+      translated, failed, rejections = batch_translator(patterns).call(source, source.keys, instructions: prompt)
+      Result.new(translations: translated.slice(*source.keys).except(*failed), failed:, rejections:)
     end
 
     private
@@ -59,12 +69,28 @@ module Locallingo
       end
     end
 
-    def batch_translator
-      @batch_translator ||= BatchTranslator.new(
+    def placeholder_patterns(placeholders)
+      patterns = placeholders.nil? ? config.placeholders : Array(placeholders)
+      invalid = patterns.grep_v(Regexp)
+      raise Error, "placeholders: expected Regexps, got #{invalid.map(&:inspect).join(", ")}" if invalid.any?
+
+      patterns
+    end
+
+    # One per call: `accept` closes over that call's patterns.
+    def batch_translator(patterns)
+      BatchTranslator.new(
         provider: @provider, model: @model, batch_size: config.batch_size,
         max_batch_chars: @max_batch_chars, pause: @pause,
-        log: ->(message, level: :info) { @logger.public_send(level, message) }
+        log: ->(message, level: :info) { @logger.public_send(level, message) },
+        accept: accept_for(patterns)
       )
     end
+
+    def accept_for(patterns)
+      return nil if patterns.empty?
+
+      ->(_key, source_text, translated) { Placeholders.compare(source_text, translated, patterns) || true }
+    end
   end
 end

data/lib/locallingo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Locallingo
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/lib/locallingo.rb

@@ -9,6 +9,7 @@ require_relative "locallingo/key_flattener"
 require_relative "locallingo/state_store"
 require_relative "locallingo/drift"
 require_relative "locallingo/providers/ruby_llm"
+require_relative "locallingo/placeholders"
 require_relative "locallingo/batch_translator"
 require_relative "locallingo/prompt"
 require_relative "locallingo/translator"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: locallingo
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -78,6 +78,7 @@ files:
 - lib/locallingo/json_extraction.rb
 - lib/locallingo/key_flattener.rb
 - lib/locallingo/manager.rb
+- lib/locallingo/placeholders.rb
 - lib/locallingo/prompt.rb
 - lib/locallingo/providers/ruby_llm.rb
 - lib/locallingo/quality/british_spellings.rb