locallingo 0.4.3 → 0.5.1

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

@@ -24,10 +24,11 @@ module Locallingo
     def extract_object(content)
       text = content.to_s.strip
 
+      fenced = fenced_block(text)
       parsed = try_parse(text) ||
-               try_parse(fenced_block(text)) ||
+               try_parse(fenced) ||
                first_balanced_object(text) ||
-               JSON.parse(text) # final attempt; raises with a useful message
+               raise_parse_error(text, fenced)
 
       # Both callers treat the result as a key->value Hash, so reject a
       # top-level array (or any non-object) here with a clear contract error
@@ -46,6 +47,17 @@ module Locallingo
       nil
     end
 
+    # Raise the most useful parse error. A complete fence that fails to parse
+    # holds the real fault (e.g. an unescaped quote inside a value); parsing the
+    # raw text would only report the fence itself at line 1.
+    def raise_parse_error(text, fenced)
+      JSON.parse(fenced || text)
+    rescue JSON::ParserError => e
+      raise e unless fenced
+
+      raise JSON::ParserError, "#{e.message} (inside the fenced block)"
+    end
+
     def fenced_block(text)
       text[/```(?:json)?\s*(\{.*?\}|\[.*?\])\s*```/m, 1]
     end

data/lib/locallingo/manager.rb

@@ -8,7 +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"
@@ -25,9 +28,9 @@ module Locallingo
   # Everything app-specific (locales, provider/model, prompt context/glossary,
   # per-language guides, which validators run) comes from the Configuration.
   class Manager
-    MAX_RETRIES = 3
-    MAX_MISSING_RETRIES = 2
-    BASE_SLEEP_DURATION = 1.0
+    MAX_RETRIES = BatchTranslator::MAX_RETRIES
+    MAX_MISSING_RETRIES = BatchTranslator::MAX_MISSING_RETRIES
+    BASE_SLEEP_DURATION = BatchTranslator::BASE_SLEEP_DURATION
 
     attr_reader :config, :dry_run, :verbose, :logger, :cli_name
 
@@ -38,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
@@ -69,7 +73,9 @@ module Locallingo
       violations = []
       source = load_source_translations
 
-      violations.concat(Validators::DuplicateValues.new.call(source:)) if config.validator_enabled?(:duplicate_values)
+      if config.validator_enabled?(:duplicate_values)
+        violations.concat(Validators::DuplicateValues.new.call(source:, locale: config.source_locale))
+      end
 
       config.target_locales.each do |locale|
         target = load_locale_translations(locale)
@@ -87,14 +93,20 @@ module Locallingo
       violations
     end
 
-    # Translate missing/changed keys for one or all target locales.
-    def translate!(locale: nil, force: false, force_keys: [])
+    # Translate missing/changed keys for one or all target locales. Returns
+    # `{ locale => failed_keys }`; keys that failed are not written.
+    #
+    # Manual (hand-edited) keys are skipped by `force` and `force_keys`;
+    # `include_manual` lets the named `force_keys` overwrite them anyway.
+    def translate!(locale: nil, force: false, force_keys: [], include_manual: false)
       @provider.ensure_credentials!
 
       locales_to_process = locale ? [locale] : config.target_locales
       source = load_source_translations
 
-      locales_to_process.each { |target_locale| translate_locale(source, target_locale, force:, force_keys:) }
+      locales_to_process.to_h do |target_locale|
+        [target_locale, translate_locale(source, target_locale, force:, force_keys:, include_manual:)]
+      end
     end
 
     # Mark hand-edited target values as intentional (source_hash + target_hash +
@@ -118,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
@@ -168,6 +176,13 @@ module Locallingo
     def missing_validator = @missing_validator ||= Validators::Missing.new(cli_name:)
     def outdated_validator = @outdated_validator ||= Validators::Outdated.new(cli_name:)
 
+    def batch_translator
+      @batch_translator ||= BatchTranslator.new(
+        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
+
     def sync_locale_state(source, locale)
       target = load_locale_translations(locale)
       locale_state = @state.load(locale)
@@ -193,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
 
@@ -210,21 +222,30 @@ module Locallingo
       raise Error, "accept-edits: key(s) not found in any target locale: #{missing.join(", ")}"
     end
 
-    def translate_locale(source, target_locale, force:, force_keys:)
+    def translate_locale(source, target_locale, force:, force_keys:, include_manual:)
       log("Processing #{target_locale}...")
 
       target = load_locale_translations(target_locale)
       locale_state = @state.load(target_locale)
       exceptions = load_exceptions(target_locale)
 
+      if force_keys.any? && !force
+        force_keys = resolve_force_keys(source, force_keys, locale_state, include_manual:, locale: target_locale)
+        # Every named key was manual: translate nothing rather than falling
+        # back to the missing/outdated keys nobody asked for.
+        if force_keys.empty?
+          log("  No keys to translate for #{target_locale} (every --force-key is manual)")
+          return []
+        end
+      end
       keys = determine_keys_to_translate(source, target, locale_state, force:, force_keys:, exceptions:)
       if keys.empty?
         log("  No keys to translate for #{target_locale}")
-        return
+        return []
       end
 
       log("  Translating #{keys.size} keys...")
-      translated, failed = translate_with_missing_retries(source, keys, target_locale)
+      translated, failed = batch_translator.call(source, keys, instructions: translation_prompt(target_locale))
 
       successful = translated.except(*failed)
       unless dry_run
@@ -234,103 +255,13 @@ module Locallingo
       end
 
       log("  Completed #{target_locale}: #{successful.size} translated, #{failed.size} failed")
+      failed
     end
 
-    def translate_with_missing_retries(source, keys, target_locale)
-      translated, failed = translate_keys(source, keys, target_locale)
-
-      round = 0
-      while failed.any? && round < MAX_MISSING_RETRIES
-        round += 1
-        log("  Retry round #{round}: #{failed.size} keys remaining...")
-        sleep(BASE_SLEEP_DURATION * (2**round))
-        retried, failed = translate_keys(source, failed, target_locale)
-        translated.merge!(retried)
-      end
-
-      if failed.any?
-        log("  WARNING: #{failed.size} keys failed after all retries:", level: :warn)
-        failed.each { |key| log("    - #{key}", level: :warn) }
-      end
-
-      [translated, failed]
-    end
-
-    def translate_keys(source, keys, target_locale)
-      translations = {}
-      failed = []
-
-      keys.each_slice(config.batch_size) do |batch|
-        result = translate_batch(batch.to_h { |key| [key, source[key]] }, target_locale)
-        batch.each do |key|
-          if result.key?(key) && !result[key].to_s.empty?
-            translations[key] = result[key]
-          else
-            failed << key
-          end
-        end
-        sleep(BASE_SLEEP_DURATION)
-      end
-
-      [translations, failed]
-    end
-
-    def translate_batch(payload, target_locale)
-      return {} if payload.empty?
-
-      retries = 0
-      begin
-        result = @provider.chat(
-          model: config.translate_model,
-          instructions: translation_prompt(target_locale),
-          payload:
-        )
-        log("  Batch translated: #{result.keys.size}/#{payload.keys.size} keys")
-        result
-      rescue StandardError => e
-        retries += 1
-        if retries < MAX_RETRIES
-          sleep_duration = BASE_SLEEP_DURATION * (2**retries)
-          log("  Batch failed (attempt #{retries}), retrying in #{sleep_duration}s: #{e.message}", level: :warn)
-          sleep(sleep_duration)
-          retry
-        end
-        log("  Translation batch failed after #{MAX_RETRIES} retries: #{e.message}", level: :error)
-        {}
-      end
-    end
-
-    def translation_prompt(locale)
-      <<~PROMPT
-        Translate the following texts from #{config.language_name(config.source_locale)} to #{config.language_name(locale)}.
-        This is for #{config.context}.
-
-        ## General Rules
-        - Preserve placeholders like #{config.placeholder_style} exactly as they appear
-        - Preserve HTML tags if present
-        - Use formal business language
-        - Keep translations concise - UI space is limited
-        #{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?
 
@@ -340,19 +271,35 @@ module Locallingo
       (missing + outdated).uniq
     end
 
+    # 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| @drift.manual?(locale_state[key]) }
+      return force_keys if manual.empty?
+
+      if include_manual
+        warn_manual_keys(manual, locale, dry_run ? "would overwrite" : "overwriting")
+        force_keys
+      else
+        warn_manual_keys(manual, locale, dry_run ? "would skip" : "skipping", hint: true)
+        force_keys - manual
+      end
+    end
+
+    def warn_manual_keys(keys, locale, verb, hint: false)
+      keys.each { |key| warn("#{verb} manual (hand-edited) key #{key} for #{locale}") }
+      warn("Pass --include-manual to overwrite manual keys named via --force-key.") if hint
+    end
+
     def update_locale_state(source, locale_state, translations)
       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 may overwrite a manual value on explicit
-        # request, but the protection flag itself must survive.
-        entry["manual"] = true if existing.is_a?(Hash) && existing["manual"]
-        locale_state[key] = entry
+        # A force-keyed retranslation overwrites a manual value only with
+        # include_manual, and even then the protection flag must survive.
+        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

@@ -13,6 +13,16 @@ module Locallingo
     # truth) so independent batches don't share conversation history. The
     # response is parsed with the robust JsonExtraction extractor because not
     # every provider guarantees fenceless JSON.
+    #
+    # The system prompt is marked as a prompt cache boundary: the translation
+    # 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
@@ -25,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
@@ -45,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 " \
@@ -56,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)
 
+        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
@@ -93,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/quality_checker.rb

@@ -31,13 +31,15 @@ module Locallingo
       @terminology = Quality::Terminology.new(@config.terminology_setting, base_path: @config.base_path)
     end
 
-    # Check all translations for a locale.
-    def check(locale: nil, use_ai: false)
+    # Check the translations for a locale: all of them, those under +prefix+
+    # (e.g. "yoga."), or exactly the named +keys+. The AI pass reviews a sample
+    # of up to `quality.sample_size` keys, or every named key.
+    def check(locale: nil, use_ai: false, prefix: nil, keys: nil)
       locale ||= config.source_locale
-      translations = load_locale_translations(locale)
+      translations = scoped_translations(locale, prefix:, keys:)
 
       suggestions = translations.flat_map { |key, text| check_text(key, text, locale) }
-      suggestions.concat(ai_sample(translations, locale)) if use_ai
+      suggestions.concat(keys ? suggest_improvements(translations, locale) : ai_sample(translations, locale)) if use_ai
       suggestions
     end
 
@@ -116,8 +118,26 @@ module Locallingo
       }
     end
 
+    def scoped_translations(locale, prefix:, keys:)
+      translations = load_locale_translations(locale)
+      return slice_keys(translations, keys, locale) if keys
+      return translations unless prefix
+
+      scoped = translations.select { |key, _| key.start_with?(prefix) }
+      raise Error, "No keys match prefix #{prefix.inspect} in #{locale}" if scoped.empty?
+
+      scoped
+    end
+
+    def slice_keys(translations, keys, locale)
+      missing = keys - translations.keys
+      raise Error, "quality: key(s) not found in #{locale}: #{missing.join(", ")}" if missing.any?
+
+      translations.slice(*keys)
+    end
+
     def ai_sample(translations, locale)
-      sample_size = [translations.size, 100].min
+      sample_size = [translations.size, config.quality_sample_size].min
       sample = translations.to_a.sample(sample_size).to_h
       suggest_improvements(sample, locale)
     end
@@ -153,7 +173,7 @@ module Locallingo
       <<~PROMPT
         Review these UI translations for #{config.context}.
         Suggest improvements for clarity, professionalism, and user-friendliness.
-        #{glossary_section}
+        #{glossary_section}#{language_guide_section(locale)}
         For each translation that needs improvement, provide:
         1. The issue (brief)
         2. Suggested improvement
@@ -174,6 +194,11 @@ module Locallingo
       "\n#{config.context} terminology:\n#{lines.join("\n")}\n"
     end
 
+    def language_guide_section(locale)
+      guide = config.language_guide(locale)
+      guide.empty? ? "" : "\n#{guide}\n"
+    end
+
     def load_locale_translations(locale)
       translations = {}
       patterns = [