locallingo 0.4.3 → 0.5.1

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/duplicate_values.rb

@@ -12,9 +12,9 @@ module Locallingo
       AR_ATTRIBUTES_PREFIX = "activerecord.attributes."
       AR_PREFIX = "activerecord."
 
-      # +source+ is the flat source (en) hash. Returns :duplicate_value
-      # violations naming both keys.
-      def call(source:)
+      # +source+ is the flat source-locale hash; +locale+ is the configured source
+      # locale. Returns :duplicate_value violations naming both keys.
+      def call(source:, locale:)
         ar_keys_by_value = source
                            .select { |key, _| key.start_with?(AR_ATTRIBUTES_PREFIX) }
                            .group_by { |_key, value| value }
@@ -30,7 +30,7 @@ module Locallingo
           ar_dupes = ar_keys_by_value[value]
           {
             type: :duplicate_value,
-            locale: "en",
+            locale:,
             key:,
             suggestion: "Value '#{value}' duplicates #{ar_dupes.join(", ")}. " \
                         "Use #{ar_dupes.first} instead."

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.4.3"
+  VERSION = "0.5.1"
 end

data/lib/locallingo.rb

@@ -6,7 +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.4.3
+  version: 0.5.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -69,20 +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