locallingo 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4296369c42c6c23ce6a15be0cc51adf0976fd6c07fd6b4514cd1a945c7ec07f9
-  data.tar.gz: b842069155d70be0a3291f67637deb719096b3654825768265cc8007e9ae27c5
+  metadata.gz: b218e7422188db797e061b9cf1133b1b25a630e9e4c6237c04f0f7fa94dd2b4f
+  data.tar.gz: 742d0794ade8f32f9346d4a02b61554b7cb81321569c5297f9d93c3f1639f4e3
 SHA512:
-  metadata.gz: 9f586a4ea9bd383bf58370219d99535f73f83994a2181ca7974302787a727df645f54c5e20c1465dc9f9f3e1ac586772b3bd97069b52f68c4bc0f03b99cf1422
-  data.tar.gz: bc075cce32d4602a4c0f8672340eca7cc7edee7afd779b95fb2822d1454794d3f804816c9a50d7f095c19aa2042dc916b203556813ddaff71d918b6e87f08bb7
+  metadata.gz: 48e0a2e2625a03fc0d78e9b5a9884efc4ec0ee7525533f150865d7bb391c473edd96f44bbca6974a24a6e564d4d08e644a0b36403a5c8a51b28a0943d54c1d1c
+  data.tar.gz: 4f08c9b89ab57351c5099ff6e31c4c24fa6b33a16df8ec0b70cb0ba365e292d90ef0fbe047d4b5494b9c2c7abe0627657c6ce4b545fd4a4552150f7338fd159d

data/CHANGELOG.md

@@ -7,6 +7,27 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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

@@ -146,6 +146,98 @@ Locallingo::Manager.new(config:).validate           # => [violations]
 Locallingo::QualityChecker.new(config:).check(locale: "en")
 ```
 
+### 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
+```
+
+- With a `context:`, every call uses that `RubyLLM::Context`'s config; 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.
+
 ## 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,148 @@
+# 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
+      class_attribute :locallingo_translatable, instance_writer: false
+    end
+
+    class_methods do
+      def translates_content(column, state:, source_locale:, target_locales:, translatable: nil, hasher: nil)
+        self.locallingo_translatable = Definition.new(
+          column: column.to_s, state: state.to_s, source_locale:, target_locales:,
+          translatable: translatable || ->(_path, _value) { true },
+          drift: hasher ? Drift.new(hasher:) : Drift.new
+        )
+        before_save :mark_hand_edits
+      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

@@ -54,6 +54,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")

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

data/lib/locallingo/drift.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "state_store"
+
+module Locallingo
+  # Missing / outdated / hand-edited decisions over one value and its state
+  # entry — the rule locale files and database records share.
+  #
+  # An entry is the shape StateStore writes:
+  #   { "source_hash" => …, "target_hash" => …, "manual" => true }
+  #
+  # Values may be a String or a nested Hash/Array of strings. A String hashes
+  # raw (exactly like StateStore, so existing state files stay valid); nested
+  # values hash over a canonical JSON form with sorted keys, so a record can
+  # track one entry per field or one per whole value.
+  class Drift
+    def initialize(hasher: StateStore.method(:hash))
+      @hasher = hasher
+    end
+
+    def digest(value)
+      case value
+      when Hash, Array then @hasher.call(JSON.generate(canonical(value)))
+      else @hasher.call(value.to_s)
+      end
+    end
+
+    # A new entry for a target translated (or written by hand) from +source+.
+    def record(source:, target:, manual: false)
+      entry = { "source_hash" => digest(source), "target_hash" => digest(target) }
+      entry["manual"] = true if manual
+      entry
+    end
+
+    # :missing (blank target), :outdated (source changed since the entry was
+    # recorded) or :current. The manual flag is not considered here; #due?
+    # applies it.
+    def status(source:, target:, entry:)
+      return :missing if blank?(target)
+      return :outdated if outdated?(source:, entry:)
+
+      :current
+    end
+
+    # The source changed since +entry+ recorded it. An untracked value (no
+    # entry or no source_hash) is not outdated.
+    def outdated?(source:, entry:)
+      stored = entry.is_a?(Hash) ? entry["source_hash"] : nil
+      !stored.nil? && stored != digest(source)
+    end
+
+    # A person wrote the target: it must not be machine-overwritten.
+    def manual?(entry) = entry.is_a?(Hash) && entry["manual"] ? true : false
+
+    # The target changed since it was recorded and is not yet flagged manual.
+    def hand_edited?(target:, entry:)
+      return false unless entry.is_a?(Hash) && !manual?(entry)
+
+      stored = entry["target_hash"]
+      !stored.nil? && stored != digest(target)
+    end
+
+    # Whether the target should be (re)translated: missing or outdated, every
+    # value with +force+, and never a manual one unless +include_manual+.
+    def due?(source:, target:, entry:, force: false, include_manual: false)
+      return false if blank?(source)
+      return false if manual?(entry) && !include_manual
+      return true if force
+
+      status(source:, target:, entry:) != :current
+    end
+
+    # Empty, whitespace-only, or a Hash/Array with only blank leaves.
+    def blank?(value)
+      case value
+      when Hash then value.values.all? { |item| blank?(item) }
+      when Array then value.all? { |item| blank?(item) }
+      else value.to_s.strip.empty?
+      end
+    end
+
+    private
+
+    def canonical(value)
+      case value
+      when Hash then value.map { |key, item| [key.to_s, canonical(item)] }.sort_by(&:first).to_h
+      when Array then value.map { |item| canonical(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/locallingo/manager.rb

@@ -8,8 +8,10 @@ require "fileutils"
 require_relative "configuration"
 require_relative "key_flattener"
 require_relative "state_store"
+require_relative "drift"
 require_relative "providers/ruby_llm"
 require_relative "batch_translator"
+require_relative "prompt"
 require_relative "validators/missing"
 require_relative "validators/outdated"
 require_relative "validators/duplicate_values"
@@ -39,6 +41,7 @@ module Locallingo
       @verbose = verbose
       @cli_name = cli_name
       @state = StateStore.new(@config.state_dir)
+      @drift = Drift.new
       @provider = Providers::RubyLLM.new(provider: @config.provider)
       @logger = logger || build_logger
     end
@@ -127,11 +130,7 @@ module Locallingo
 
       plans.each_with_object({}) do |(target_locale, target, locale_state, accepted), results|
         accepted.each do |key|
-          locale_state[key] = {
-            "source_hash" => @state.hash(source[key]),
-            "target_hash" => @state.hash(target[key]),
-            "manual" => true
-          }
+          locale_state[key] = @drift.record(source: source[key], target: target[key], manual: true)
         end
         @state.save(target_locale, locale_state) unless dry_run
         results[target_locale] = accepted
@@ -179,7 +178,8 @@ module Locallingo
 
     def batch_translator
       @batch_translator ||= BatchTranslator.new(
-        provider: @provider, model: config.translate_model, batch_size: config.batch_size, log: method(:log)
+        provider: @provider, model: config.translate_model, batch_size: config.batch_size,
+        max_batch_chars: config.max_batch_chars, pause: config.pause, log: method(:log)
       )
     end
 
@@ -208,10 +208,7 @@ module Locallingo
       return target.keys.select { |key| source.key?(key) } if all
 
       target.keys.select do |key|
-        entry = locale_state[key]
-        next false unless source.key?(key) && entry.is_a?(Hash) && !entry["manual"]
-
-        entry["target_hash"] && entry["target_hash"] != @state.hash(target[key])
+        source.key?(key) && @drift.hand_edited?(target: target[key], entry: locale_state[key])
       end
     end
 
@@ -261,47 +258,10 @@ module Locallingo
       failed
     end
 
-    def translation_prompt(locale)
-      language = config.language_name(locale)
-      <<~PROMPT
-        Translate the following texts from #{config.language_name(config.source_locale)} into natural, idiomatic #{language}.
-        This is for #{config.context}.
-
-        ## Idiomatic Translation
-        - Translate the meaning, not word for word: write what a native #{language} speaker would actually say in this situation
-        - Use the phrasing, word order and UI conventions that are standard in #{language} software, even when they differ from the source
-        - Replace source-language idioms and set phrases with their natural #{language} equivalent instead of translating them literally
-        - Avoid calques and anglicisms when an established #{language} expression exists
-        - Never add, drop or change information to make a sentence sound natural
-        - Terminology and any language guide below take precedence over these style rules
-
-        ## General Rules
-        - Preserve placeholders like #{config.placeholder_style} exactly as they appear
-        - Preserve HTML tags if present
-        - Keep translations concise - UI space is limited
-        - 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}#{language_guide_section(locale)}
-        Return ONLY a raw JSON object mapping each input key to its translation,
-        with no surrounding prose and no markdown code fences:
-        {"key1": "translated1", "key2": "translated2"}
-      PROMPT
-    end
-
-    def glossary_section
-      return "" if config.glossary.empty?
-
-      lines = config.glossary.map { |term, meaning| "        - \"#{term}\" = #{meaning}" }
-      "\n## Terminology\n#{lines.join("\n")}\n"
-    end
-
-    def language_guide_section(locale)
-      guide = config.language_guide(locale)
-      guide.empty? ? "" : "\n#{guide}\n"
-    end
+    def translation_prompt(locale) = Prompt.translation(config:, from: config.source_locale, to: locale)
 
     def determine_keys_to_translate(source, target, locale_state, force:, force_keys:, exceptions:)
-      manual_keys = locale_state.select { |_k, v| v.is_a?(Hash) && v["manual"] }.keys.to_set
+      manual_keys = locale_state.select { |_key, entry| @drift.manual?(entry) }.keys.to_set
       return source.keys - manual_keys.to_a if force
       return force_keys & source.keys if force_keys.any?
 
@@ -314,7 +274,7 @@ module Locallingo
     # Drops manual keys from the named force_keys (with a loud warning) unless
     # the caller opted in to overwriting them.
     def resolve_force_keys(source, force_keys, locale_state, include_manual:, locale:)
-      manual = (force_keys & source.keys).select { |key| locale_state[key].is_a?(Hash) && locale_state[key]["manual"] }
+      manual = (force_keys & source.keys).select { |key| @drift.manual?(locale_state[key]) }
       return force_keys if manual.empty?
 
       if include_manual
@@ -335,15 +295,11 @@ module Locallingo
       translations.each_key do |key|
         next unless source[key]
 
-        existing = locale_state[key]
-        entry = {
-          "source_hash" => @state.hash(source[key]),
-          "target_hash" => @state.hash(translations[key])
-        }
         # A force-keyed retranslation overwrites a manual value only with
         # include_manual, and even then the protection flag must survive.
-        entry["manual"] = true if existing.is_a?(Hash) && existing["manual"]
-        locale_state[key] = entry
+        locale_state[key] = @drift.record(
+          source: source[key], target: translations[key], manual: @drift.manual?(locale_state[key])
+        )
       end
     end
 

data/lib/locallingo/prompt.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Locallingo
+  # Builds the translation system prompt: idiomatic-translation and formatting
+  # rules, the configured glossary and per-language guide, plus optional caller
+  # instructions.
+  #
+  # Styles:
+  # - `:ui`    — short interface strings (the CLI's prompt, pinned by a spec)
+  # - `:prose` — long-form content: Markdown structure is kept and there is no
+  #   brevity rule
+  module Prompt
+    STYLES = %i[ui prose].freeze
+
+    BREVITY_RULE = "- Keep translations concise - UI space is limited\n"
+
+    MARKDOWN_RULES = <<~RULES
+      - Keep the Markdown structure: headings, lists, emphasis, links and line breaks stay where they are
+      - Translate link text, never the link target (URL)
+      - Never merge or split values: every key gets exactly one translated value
+    RULES
+
+    module_function
+
+    def translation(config:, from:, to:, style: :ui, instructions: nil)
+      raise Error, "Unknown prompt style #{style.inspect} (expected one of #{STYLES.join(", ")})" unless
+        STYLES.include?(style.to_s.to_sym)
+
+      language = config.language_name(to)
+      <<~PROMPT
+        Translate the following texts from #{config.language_name(from)} into natural, idiomatic #{language}.
+        This is for #{config.context}.
+
+        ## Idiomatic Translation
+        - Translate the meaning, not word for word: write what a native #{language} speaker would actually say in this situation
+        - Use the phrasing, word order and UI conventions that are standard in #{language} software, even when they differ from the source
+        - Replace source-language idioms and set phrases with their natural #{language} equivalent instead of translating them literally
+        - Avoid calques and anglicisms when an established #{language} expression exists
+        - Never add, drop or change information to make a sentence sound natural
+        - Terminology and any language guide below take precedence over these style rules
+
+        ## General Rules
+        - Preserve placeholders like #{config.placeholder_style} exactly as they appear
+        - 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)}
+        Return ONLY a raw JSON object mapping each input key to its translation,
+        with no surrounding prose and no markdown code fences:
+        {"key1": "translated1", "key2": "translated2"}
+      PROMPT
+    end
+
+    def glossary_section(config)
+      return "" if config.glossary.empty?
+
+      lines = config.glossary.map { |term, meaning| "        - \"#{term}\" = #{meaning}" }
+      "\n## Terminology\n#{lines.join("\n")}\n"
+    end
+
+    def language_guide_section(config, locale)
+      guide = config.language_guide(locale)
+      guide.empty? ? "" : "\n#{guide}\n"
+    end
+
+    def instructions_section(instructions)
+      text = instructions.to_s.strip
+      text.empty? ? "" : "\n## Additional Instructions\n#{text}\n"
+    end
+
+    private_class_method :glossary_section, :language_guide_section, :instructions_section
+  end
+end

data/lib/locallingo/providers/ruby_llm.rb

@@ -18,6 +18,11 @@ module Locallingo
     # prompt is built once per locale and reused by every batch, so providers
     # that support caching (Anthropic, OpenAI-compatible) bill the repeated
     # prefix at the cached rate.
+    #
+    # Given a `RubyLLM::Context` (`RubyLLM.context { |c| c.anthropic_api_key = … }`),
+    # every chat runs on that context's own configuration: the global
+    # `RubyLLM.config` is never written, so translators with different keys
+    # (one per tenant) can run concurrently.
     class RubyLLM
       # Maps a RubyLLM provider symbol to the ENV var whose presence indicates
       # credentials are available, so we can fail fast with a clear message
@@ -30,10 +35,11 @@ module Locallingo
         openrouter: "OPENROUTER_API_KEY"
       }.freeze
 
-      attr_reader :provider
+      attr_reader :provider, :context
 
-      def initialize(provider:)
+      def initialize(provider:, context: nil)
         @provider = provider.to_sym
+        @context = context
       end
 
       # True when a key for the configured provider is found in any source
@@ -50,6 +56,12 @@ module Locallingo
       def ensure_credentials!
         return if credentials?
 
+        if context
+          raise MissingCredentialsError,
+                "No credentials for provider #{provider.inspect}: the given RubyLLM context " \
+                "has no #{key_setting}."
+        end
+
         raise MissingCredentialsError,
               "No credentials for provider #{provider.inspect}. " \
               "Set #{CREDENTIAL_ENV[provider]} in ENV, call " \
@@ -61,20 +73,21 @@ module Locallingo
       # the model and return the parsed JSON object as a Hash.
       def chat(model:, instructions:, payload:)
         require "ruby_llm"
-        configure_credentials!
-
-        conversation = ::RubyLLM.chat(
-          model:,
-          provider:,
-          assume_model_exists: true
-        ).with_instructions(instructions, cache_until_here: true)
 
+        conversation = new_chat(model).with_instructions(instructions, cache_until_here: true)
         response = conversation.ask(JSON.pretty_generate(payload))
         JsonExtraction.extract_object(response.content)
       end
 
       private
 
+      def new_chat(model)
+        return context.chat(model:, provider:, assume_model_exists: true) if context
+
+        configure_credentials!
+        ::RubyLLM.chat(model:, provider:, assume_model_exists: true)
+      end
+
       # RubyLLM does not read provider API keys from ENV on its own, so a
       # standalone CLI run (no Rails initializer to call RubyLLM.configure)
       # would raise "Missing configuration for <provider>". Push the resolved
@@ -98,9 +111,18 @@ module Locallingo
       # Key resolution across sources, in precedence order. Used by
       # #credentials? as a fail-fast check before any network call.
       def resolved_api_key
+        return context_api_key if context
+
         settings_api_key || host_configured_api_key || env_api_key
       end
 
+      # With a context, its own config is the only source: the chat never
+      # reads the settings, the global config or ENV.
+      def context_api_key
+        config = context.config
+        config.respond_to?(key_setting) ? presence(config.public_send(key_setting)) : nil
+      end
+
       def settings_api_key
         Locallingo.settings.api_key_for(provider)
       end

data/lib/locallingo/record_translator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Locallingo
+  # Translates records that include Locallingo::Translatable (see
+  # `locallingo/active_record`) into one target locale.
+  #
+  #   Locallingo::RecordTranslator.new(translator:)
+  #     .call(Article.where(id: ids), to: "de", style: :prose)
+  #   # => { translated: 3, failed: { article_id => [paths] }, skipped: [ids] }
+  #
+  # The due records' segments (keys prefixed by record id) go out as one
+  # batched translation per source locale. Each record is then written under
+  # 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.
+  #
+  # Records must be persisted and of one model (ids are the key prefix). This
+  # class never loads ActiveRecord itself; records only need the concern.
+  class RecordTranslator
+    DEFAULT_WRITE = ->(record, attributes) { record.update_columns(attributes) }
+
+    # +write+ is called as `write.call(record, attributes)` inside the lock,
+    # e.g. to bump a lock version or run validations (`record.update!(attributes)`).
+    def initialize(translator:, write: DEFAULT_WRITE)
+      @translator = translator
+      @write = write
+    end
+
+    def call(records, to:, style: :ui, instructions: nil, force: false, include_manual: false)
+      @locale = to.to_s
+      @force = force
+      @include_manual = include_manual
+      @result = { translated: 0, failed: {}, skipped: [] }
+
+      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:)
+      end
+      @result
+    end
+
+    private
+
+    def due?(record) = record.translation_due?(@locale, force: @force, include_manual: @include_manual)
+
+    def translate_group(records, from:, style:, instructions:)
+      digests = records.to_h { |record| [record, record.translation_source_digest] }
+      owners = {}
+      segments = records.each_with_object({}) do |record, all|
+        record.translation_segments.each do |path, text|
+          key = "#{record.id}.#{path}"
+          raise Error, "Segment key #{key} is ambiguous across records (an id containing \".\"?)" if owners.key?(key)
+
+          owners[key] = [record, path]
+          all[key] = text
+        end
+      end
+
+      result = @translator.translate(segments, from:, to: @locale, style:, instructions:)
+      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)
+        @result[:failed][record.id] = failed if failed.any?
+        # All or nothing per record: one state entry covers the whole locale,
+        # so a partial write would read as current with values missing.
+        write(record, translations, digests[record]) if failed.empty? && translations.any?
+      end
+    end
+
+    # The +record+'s pairs from +pairs+, keyed by its own segment path.
+    def own(pairs, owners, record)
+      pairs.filter_map do |key, value|
+        owner, path = owners[key]
+        [path, value] if owner.equal?(record)
+      end
+    end
+
+    def write(record, translations, digest)
+      record.with_lock do
+        next @result[:skipped] << record.id unless record.translation_source_digest == digest && due?(record)
+
+        manual = record.translation_manual?(@locale)
+        target = record.build_translation_target(translations)
+        @write.call(record, record.translation_attributes(@locale, target, manual:))
+        @result[:translated] += 1
+      end
+    end
+  end
+end

data/lib/locallingo/translator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "configuration"
+require_relative "prompt"
+require_relative "providers/ruby_llm"
+require_relative "batch_translator"
+
+module Locallingo
+  # The public, file-agnostic entry point: translates a plain `{ key => text }`
+  # hash between two locales with the configured rules, glossary, language
+  # guide, provider and model.
+  #
+  #   translator = Locallingo::Translator.new(
+  #     config: Locallingo.configuration,
+  #     context: RubyLLM.context { |c| c.anthropic_api_key = tenant_key } # optional
+  #   )
+  #   result = translator.translate({ "title" => "Hello" }, from: "en", to: "de", style: :prose)
+  #   result.translations # => { "title" => "Hallo" }
+  #   result.failed       # => []
+  #
+  # Batching, retries, batch halving and omitted-key rounds come from
+  # BatchTranslator. Blank texts are not sent.
+  class Translator
+    Result = Data.define(:translations, :failed)
+
+    attr_reader :config
+
+    def initialize(config: Locallingo.configuration, context: nil, model: nil, logger: nil,
+                   max_batch_chars: nil, pause: nil)
+      @config = config
+      @provider = Providers::RubyLLM.new(provider: config.provider, context:)
+      @model = model || config.translate_model
+      @logger = logger || Logger.new($stderr, level: Logger::WARN)
+      @max_batch_chars = max_batch_chars || config.max_batch_chars
+      @pause = pause || config.pause
+    end
+
+    # Raises MissingCredentialsError before any call when no key is available.
+    def translate(texts, from:, to:, style: :ui, instructions: nil)
+      @provider.ensure_credentials!
+
+      source = stringify_keys(texts).reject { |_key, text| text.to_s.strip.empty? }
+      return Result.new(translations: {}, failed: []) 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:)
+    end
+
+    private
+
+    def stringify_keys(texts)
+      texts.each_with_object({}) do |(key, text), source|
+        raise Error, "Duplicate key #{key.to_s.inspect} (e.g. :#{key} and \"#{key}\")" if source.key?(key.to_s)
+
+        source[key.to_s] = text
+      end
+    end
+
+    def batch_translator
+      @batch_translator ||= 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) }
+      )
+    end
+  end
+end

data/lib/locallingo/validators/manual_edits.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../state_store"
+require_relative "../drift"
 
 module Locallingo
   module Validators
@@ -12,19 +12,15 @@ module Locallingo
     # it was edited by a human — surface it so the operator can protect it with
     # `accept-edits` before the next translate run overwrites it.
     class ManualEdits
-      def initialize(cli_name: "lingo")
+      def initialize(cli_name: "lingo", drift: Drift.new)
         @cli_name = cli_name
+        @drift = drift
       end
 
       # +target+ is the flat target hash; +locale_state+ its loaded state.
       def call(target:, locale_state:, locale:)
         target.filter_map do |key, value|
-          entry = locale_state[key]
-          next unless entry.is_a?(Hash)
-          next if entry["manual"]
-
-          stored = entry["target_hash"]
-          next unless stored && stored != StateStore.hash(value)
+          next unless @drift.hand_edited?(target: value, entry: locale_state[key])
 
           {
             type: :manual_edit,

data/lib/locallingo/validators/outdated.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "../state_store"
+require_relative "../drift"
 
 module Locallingo
   module Validators
     # Reports target keys whose recorded source hash no longer matches the
     # current source value — i.e. the English text changed after translation.
     class Outdated
-      def initialize(cli_name: "lingo")
+      def initialize(cli_name: "lingo", drift: Drift.new)
         @cli_name = cli_name
+        @drift = drift
       end
 
       # +source+ is the flat source hash; +locale_state+ is the target locale's
@@ -27,8 +28,7 @@ module Locallingo
       # Keys whose stored source_hash differs from the current source hash.
       def outdated_keys(source, locale_state)
         source.filter_map do |key, value|
-          stored = locale_state.dig(key, "source_hash")
-          key if stored && stored != StateStore.hash(value)
+          key if @drift.outdated?(source: value, entry: locale_state[key])
         end
       end
 
@@ -37,7 +37,7 @@ module Locallingo
       # Manual keys must not be pushed toward machine retranslation — the value
       # is hand-curated, so the human updates it and re-accepts.
       def suggestion_for(key, locale, locale_state)
-        if locale_state.dig(key, "manual")
+        if @drift.manual?(locale_state[key])
           "Source changed for a manually-curated key. Update the #{locale} value by hand, " \
             "then run: #{@cli_name} accept-edits --locale #{locale} --key #{key}"
         else

data/lib/locallingo/version.rb

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

data/lib/locallingo.rb

@@ -6,8 +6,12 @@ require_relative "locallingo/configuration"
 require_relative "locallingo/json_extraction"
 require_relative "locallingo/key_flattener"
 require_relative "locallingo/state_store"
+require_relative "locallingo/drift"
 require_relative "locallingo/providers/ruby_llm"
 require_relative "locallingo/batch_translator"
+require_relative "locallingo/prompt"
+require_relative "locallingo/translator"
+require_relative "locallingo/record_translator"
 require_relative "locallingo/validators/missing"
 require_relative "locallingo/validators/outdated"
 require_relative "locallingo/validators/duplicate_values"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: locallingo
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -69,21 +69,27 @@ files:
 - config/locallingo.default.yml
 - exe/lingo
 - lib/locallingo.rb
+- lib/locallingo/active_record.rb
 - lib/locallingo/batch_translator.rb
 - lib/locallingo/cli.rb
 - lib/locallingo/configuration.rb
+- lib/locallingo/content_leaves.rb
+- lib/locallingo/drift.rb
 - lib/locallingo/json_extraction.rb
 - lib/locallingo/key_flattener.rb
 - lib/locallingo/manager.rb
+- lib/locallingo/prompt.rb
 - lib/locallingo/providers/ruby_llm.rb
 - lib/locallingo/quality/british_spellings.rb
 - lib/locallingo/quality/static_rules.rb
 - lib/locallingo/quality/terminology.rb
 - lib/locallingo/quality_checker.rb
+- lib/locallingo/record_translator.rb
 - lib/locallingo/reporter.rb
 - lib/locallingo/rubocop.rb
 - lib/locallingo/settings.rb
 - lib/locallingo/state_store.rb
+- lib/locallingo/translator.rb
 - lib/locallingo/validators/duplicate_values.rb
 - lib/locallingo/validators/manual_edits.rb
 - lib/locallingo/validators/missing.rb