locallingo 0.5.0 → 0.6.0

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
@@ -164,11 +163,12 @@ module Locallingo
       combined
     end
 
-    # Run the configured after_translate hook commands (from the app root).
+    # Run the configured after_translate hook commands (from the app root, in
+    # the child process only: the process-wide cwd is never changed).
     def run_after_translate_hooks
       config.after_translate.each do |command|
         log("Running: #{command}")
-        Dir.chdir(config.root_path) { system(command) }
+        system(command, chdir: config.root_path)
       end
     end
 
@@ -179,7 +179,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 +209,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 +259,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 +275,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 +296,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,12 @@ 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.
+    #
+    # Every chat runs on a `RubyLLM::Context`: the one given
+    # (`RubyLLM.context { |c| c.anthropic_api_key = … }`), else a fresh one built
+    # for that chat from the resolved key. 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 +36,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 +57,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,46 +74,50 @@ 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
 
-      # 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
-      # key into RubyLLM's config: an explicit `Locallingo.configure` key wins
-      # (re-resolved every chat so callables stay live), then a key the host
-      # app already set, then the ENV fallback.
-      def configure_credentials!
-        return unless CREDENTIAL_ENV.key?(provider)
-
-        config = ::RubyLLM.config
-        setting = key_setting
-        return unless config.respond_to?(setting) && config.respond_to?("#{setting}=")
-
-        key = settings_api_key
-        return if key.nil? && !presence(config.public_send(setting)).nil?
+      def new_chat(model)
+        (context || chat_context).chat(model:, provider:, assume_model_exists: true)
+      end
 
-        key ||= env_api_key
-        config.public_send("#{setting}=", key) unless key.nil?
+      # A context of its own for one chat. `RubyLLM.context` copies the global
+      # config, so a key the host app set via RubyLLM.configure carries over;
+      # an explicit `Locallingo.configure` key wins over it (re-resolved every
+      # chat so callables stay live), and ENV fills in when neither is set
+      # (RubyLLM does not read provider keys from ENV on its own, so a
+      # standalone CLI run would otherwise raise "Missing configuration").
+      def chat_context
+        ::RubyLLM.context do |config|
+          setting = key_setting
+          next unless CREDENTIAL_ENV.key?(provider) && config.respond_to?("#{setting}=")
+
+          key = settings_api_key
+          key ||= env_api_key if presence(config.public_send(setting)).nil?
+          config.public_send("#{setting}=", key) unless key.nil?
+        end
       end
 
       # 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/quality/static_rules.rb

@@ -11,6 +11,7 @@ module Locallingo
         "Can not" => "Cannot"
       }.freeze
 
+      # Every level frozen, so any Ractor can read the rules.
       RULES = {
         terminology: {
           /\bcan not\b/i => "Use 'cannot' (one word)",
@@ -18,11 +19,11 @@ module Locallingo
             "Use 'log in' (verb) not 'login' here",
           /\bclick\s+here\b/i => "Avoid 'click here' - use descriptive link text",
           /\bplease\b.*\bplease\b/i => "Multiple 'please' in same text - remove redundancy"
-        },
+        }.freeze,
         placeholders: {
           /%\{[^}]*\s[^}]*\}/ => "Placeholder contains spaces - may cause issues",
           /%\{[A-Z]/ => "Placeholder starts with uppercase - convention is lowercase"
-        },
+        }.freeze,
         clarity: {
           /\betc\.?\b/i => "Avoid 'etc.' - be specific or use 'and more'",
           /\bstuff\b/i => "Vague word 'stuff' - be more specific",
@@ -30,19 +31,19 @@ module Locallingo
           /\basap\b/i => "Avoid abbreviation 'ASAP' - use 'as soon as possible'",
           /\bfyi\b/i => "Avoid abbreviation 'FYI' - rephrase",
           /\s{2,}/ => "Multiple consecutive spaces"
-        },
+        }.freeze,
         business: {
           /\bsorry\b/i => "Consider 'We apologize' for formal business tone",
           /\boops\b/i => "Informal - use professional error messaging",
           /\buh\s*oh\b/i => "Informal - use professional error messaging",
           /\bawesome\b/i => "Consider more professional alternatives",
           /\bcool\b(?!\s*down)/i => "Informal - consider 'great' or 'excellent'"
-        },
+        }.freeze,
         accessibility: {
           /\bsee\s+below\b/i => "Screen reader unfriendly - describe the content",
           /\babove\b/i => "Positional reference - may not work for all users",
           /\bred\b.*\berror\b|\berror\b.*\bred\b/i => "Don't rely on color alone for meaning"
-        }
+        }.freeze
       }.freeze
 
       module_function

data/lib/locallingo/quality/terminology.rb

@@ -36,7 +36,7 @@ module Locallingo
         "cdd" => nil
       ).freeze
 
-      BUILTINS = { "business" => BUSINESS, "banking" => BANKING, "none" => {} }.freeze
+      BUILTINS = { "business" => BUSINESS, "banking" => BANKING, "none" => {}.freeze }.freeze
 
       attr_reader :terms
 

data/lib/locallingo/record_translator.rb

@@ -0,0 +1,94 @@
+# 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
+    # A capture-free lambda, made shareable where the engine has Ractors, so
+    # the constant is readable from any Ractor.
+    DEFAULT_WRITE = ->(record, attributes) { record.update_columns(attributes) }
+                    .then { |write| defined?(::Ractor) ? ::Ractor.make_shareable(write) : write }
+
+    # +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/rubocop.rb

@@ -16,6 +16,6 @@ require_relative "../rubocop/cop/locallingo/strftime_in_view"
 module Locallingo
   # Absolute path to the cop defaults, for `inherit_gem: locallingo: <path>`.
   module RuboCop
-    CONFIG_DEFAULT = File.expand_path("../../config/default.yml", __dir__)
+    CONFIG_DEFAULT = File.expand_path("../../config/default.yml", __dir__).freeze
   end
 end

data/lib/locallingo/settings.rb

@@ -12,10 +12,21 @@ module Locallingo
   #
   # Callables are resolved lazily on every use (never memoized), so keys can
   # come from sources that aren't ready at configure time or that rotate.
+  #
+  # A String key is stored as a frozen plain String copy, so settings frozen by
+  # `Locallingo.configure` are Ractor-shareable; a callable is kept as is.
   class Settings
     PROVIDERS = %i[openai anthropic gemini deepseek openrouter].freeze
 
-    attr_accessor(*PROVIDERS.map { |name| :"#{name}_api_key" })
+    attr_reader(*PROVIDERS.map { |name| :"#{name}_api_key" })
+
+    PROVIDERS.each do |name|
+      define_method(:"#{name}_api_key=") do |value|
+        # A plain String copy: a subclass or its ivars could carry mutable state.
+        value = String.new(value).freeze if value.is_a?(String)
+        instance_variable_set(:"@#{name}_api_key", value)
+      end
+    end
 
     # The usable key for +provider+: callables are called, results stripped,
     # and blank or unknown-provider values come back as nil.

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