locallingo 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e31de70770225e0fa02a19b214791252d80b79b46f69ff02fe4a4966079fb3bf
-  data.tar.gz: 1b32c3ef52453c291676585fa0ca6a1da301879d292b98de13c017c6d03195e6
+  metadata.gz: 4296369c42c6c23ce6a15be0cc51adf0976fd6c07fd6b4514cd1a945c7ec07f9
+  data.tar.gz: b842069155d70be0a3291f67637deb719096b3654825768265cc8007e9ae27c5
 SHA512:
-  metadata.gz: c6293ed9127107f94800a144653e593aa2482aae0d5352dde2a7a02cd9043afedbcd441e112e3e3565e7842b981a9935623c70e94603a26fb0555e31b65397e9
-  data.tar.gz: e20e64e38717897b90ab7607dfe032b52ecd3d9b12af37ec8615ca8811fe2d4fef6d3eefb6f00196e0b1d9f4eded368a0118f3dcbbddc2704d04f6ecb50106b3
+  metadata.gz: 9f586a4ea9bd383bf58370219d99535f73f83994a2181ca7974302787a727df645f54c5e20c1465dc9f9f3e1ac586772b3bd97069b52f68c4bc0f03b99cf1422
+  data.tar.gz: bc075cce32d4602a4c0f8672340eca7cc7edee7afd779b95fb2822d1454794d3f804816c9a50d7f095c19aa2042dc916b203556813ddaff71d918b6e87f08bb7

data/CHANGELOG.md

@@ -6,12 +6,60 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+- `lingo quality --prefix yoga.` checks only the keys under a prefix, in both
+  the static checks and the AI pass. A prefix that matches nothing exits `1`. (#10, #29)
+- `lingo quality --key a.b` (repeatable) checks exactly the named keys, and the
+  AI pass reviews every named key without sampling. An unknown key exits `1`;
+  `--key` and `--prefix` cannot be combined. (#10, #29)
+- `quality.sample_size` (default `100`) sets how many keys `quality --ai`
+  samples. (#10, #29)
+- `lingo translate --include-manual` lets `--force-key` overwrite keys flagged
+  `manual`; each overwritten key is named on stderr and its `manual` flag
+  survives. (#11, #30)
+
 ### Changed
-- Allow `ruby_llm` 2.x (dependency constraint widened from `< 2` to `< 3`). The
-  gem only uses RubyLLM's stable chat API and guarded config accessors, so a
-  host app can take the RubyLLM 2.0 bump without waiting on Locallingo.
+- `lingo translate --force-key` skips keys flagged `manual` (hand-edited, via
+  `accept-edits`) and names each skipped key on stderr, the same protection
+  `--force` already gave. If every named key is manual, nothing is translated.
+  Pass `--include-manual` to overwrite them as before. (#11, #30)
+- The translation prompt asks for natural, idiomatic text in the target
+  language ("into natural, idiomatic German") instead of a word-for-word
+  translation: the meaning, phrasing and UI conventions a native speaker would
+  use, with idioms replaced by their local equivalent. Only newly translated or
+  outdated keys are affected; run `lingo translate --force` to redo all
+  non-manual keys (hand-edited `manual` keys stay untouched — redo those one at
+  a time with `--force-key <key> --include-manual` and compare).
+  The source language is now named too (`en` → "English").
+- The translation prompt no longer hardcodes "Use formal business language".
+  Register (formal "Sie"/"Lei" vs. informal "du"/"tu") belongs in each
+  locale's `language_guides` entry; add it there to keep a formal tone.
+- `lingo translate` exits `1` when any key fails to translate, and prints
+  `⚠️ Translation finished: N keys failed` with the failed keys instead of
+  `✅ Translation complete!`. Translated keys are still written and the
+  `after_translate` hooks still run; `--dry-run` reports failures but exits `0`.
+  Appending `|| true` restores the old always-`0` behaviour, but also hides
+  every other failure (missing credentials, a broken config). (#25)
+- `Manager#translate!` returns `{ locale => failed_keys }`. (#25)
+- Require `ruby_llm` >= 2.1 (constraint is now `>= 2.1, < 3`; host apps pinned
+  to RubyLLM 1.x or 2.0 must bump). The translation and quality-review system
+  prompts are marked as prompt cache boundaries; the translation prompt is
+  reused by every batch of a locale, so providers with prompt caching
+  (Anthropic, OpenAI-compatible) bill that repeated prefix at the cached rate. Anthropic only caches prompts
+  above its minimum length (~1024 tokens); shorter prompts are sent uncached.
 
 ### Fixed
+- `lingo quality --ai` includes the locale's `language_guides` entry in the
+  review prompt, as `translate` does, so the AI pass can flag violations of the
+  guide (e.g. du/Sie register). (#9, #29)
+- One invalid value in a model reply (e.g. typographic quotes returned as
+  unescaped `"`) no longer fails every key in its batch. A reply that cannot be
+  parsed is never resent as-is: the batch is split in half, down to single keys,
+  so only the bad key fails. Transport errors still retry with backoff. (#25)
+- When a ```json fence holds invalid JSON, the parse error now names the line
+  and column inside the fence instead of the fence at line 1. (#25)
+- The translation prompt asks the model to escape `"` inside values as `\"`
+  and keep typographic quotes (“ ” „ ‚ « ») as they appear in the source. (#25)
 - State files are written with a trailing final newline, so the output is
   POSIX-conformant and files that already end with a newline are no longer
   rewritten with newline-only diffs. One-time effect after upgrading: each
@@ -21,6 +69,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   through `translate` or `accept-edits`) get a baseline and the `manual_edits`
   validator can watch them. An existing `target_hash` is still never
   recomputed — that would silently absorb hand-edit drift.
+- The `duplicate_values` validator reports findings under the configured
+  `source_locale` instead of a hard-coded `en`. (#15)
 
 ### Fixed (0.4.0)
 - `lingo sync` no longer destroys hand-edit protection: it now only refreshes

data/README.md

@@ -100,9 +100,11 @@ With no `packages:`, the whole app uses `defaults` — the common case.
 lingo status                       # translation status per locale
 lingo translate --locale de        # translate missing/changed keys
 lingo translate --force            # re-translate everything
+lingo translate --force-key a.b.c  # re-translate one key (skips manual; add --include-manual)
 lingo validate --strict            # CI gate (exit 1 on strict-tier issues)
 lingo validate --strict-all        # stricter CI gate
 lingo quality --ai                 # quality linting (+ optional AI pass)
+lingo quality --ai --prefix yoga.  # lint one namespace
 lingo fix-quality --locale en      # auto-fix fixable issues
 lingo accept-edits --locale de     # protect hand-edited translations (drifted keys only)
 lingo accept-edits --key a.b.c     # protect a specific key

data/config/locallingo.default.yml

@@ -29,6 +29,9 @@ defaults:
 
   quality:
     model: gpt-4o-mini
+    # How many randomly sampled keys `quality --ai` sends for review per run
+    # (`--key` reviews every named key instead).
+    sample_size: 100
     # Flag en-only British-vs-American spelling drift (organization -> organisation).
     british_spellings: false
     # Named built-in terminology list ("business" | "banking" | "none"), or a
@@ -41,7 +44,8 @@ defaults:
   context: "a business application"
   placeholder_style: "%<name>s, %<count>s"
   glossary: {}
-  # Extra per-locale style guidance appended to the translation prompt. Value is
+  # Extra per-locale style guidance appended to the translation and AI quality
+  # review prompts. Value is
   # inline text or `file: path/to/guide.md`.
   language_guides: {}
 

data/lib/locallingo/batch_translator.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Locallingo
+  # Sends keys to the provider in batches and collects the translations.
+  #
+  # - Transport/API errors retry the same payload with backoff.
+  # - A reply that cannot be parsed is never resent as-is: one bad value (e.g.
+  #   an unescaped quote) would fail it again. The batch is halved instead,
+  #   down to single keys, so a bad value costs only its own key.
+  # - Keys the model omitted are re-batched for a few rounds; keys whose own
+  #   one-key reply could not be parsed are not.
+  class BatchTranslator
+    MAX_RETRIES = 3
+    MAX_MISSING_RETRIES = 2
+    BASE_SLEEP_DURATION = 1.0
+
+    # `log` is called as `log.call(message, level: :info)`.
+    def initialize(provider:, model:, batch_size:, log:)
+      @provider = provider
+      @model = model
+      @batch_size = batch_size
+      @log = log
+    end
+
+    # Translates `keys` (looked up in `source`) and returns
+    # `[translations, failed_keys]`.
+    def call(source, keys, instructions:)
+      @source = source
+      @instructions = instructions
+      @unparseable = []
+
+      translated, missing = translate_keys(keys)
+      missing = retry_missing(translated, missing)
+
+      failed = missing + @unparseable
+      report_failed(failed)
+      [translated, failed]
+    end
+
+    private
+
+    def retry_missing(translated, missing)
+      missing -= @unparseable
+      round = 0
+      while missing.any? && round < MAX_MISSING_RETRIES
+        round += 1
+        log("  Retry round #{round}: #{missing.size} keys remaining...")
+        sleep(BASE_SLEEP_DURATION * (2**round))
+        retried, missing = translate_keys(missing)
+        translated.merge!(retried)
+        missing -= @unparseable
+      end
+      missing
+    end
+
+    def report_failed(failed)
+      return if failed.empty?
+
+      log("  WARNING: #{failed.size} keys failed after all retries:", level: :warn)
+      failed.each { |key| log("    - #{key}", level: :warn) }
+    end
+
+    def translate_keys(keys)
+      translations = {}
+      failed = []
+
+      keys.each_slice(@batch_size) 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?
+            translations[key] = result[key]
+          else
+            failed << key
+          end
+        end
+        sleep(BASE_SLEEP_DURATION)
+      end
+
+      [translations, failed]
+    end
+
+    def translate_batch(payload)
+      return {} if payload.empty?
+
+      request_batch(payload)
+    rescue JSON::ParserError => e
+      split_unparseable_batch(payload, e)
+    end
+
+    def split_unparseable_batch(payload, error)
+      if payload.size == 1
+        log("  Unparseable reply for #{payload.keys.first}: #{error.message}", level: :error)
+        @unparseable.concat(payload.keys)
+        return {}
+      end
+
+      log("  Unparseable reply for #{payload.size} keys, splitting the batch: #{error.message}", level: :warn)
+      payload.each_slice((payload.size / 2.0).ceil).with_object({}) do |half, result|
+        result.merge!(translate_batch(half.to_h))
+      end
+    end
+
+    def request_batch(payload)
+      retries = 0
+      begin
+        result = @provider.chat(model: @model, instructions: @instructions, payload:)
+        log("  Batch translated: #{result.keys.size}/#{payload.keys.size} keys")
+        result
+      rescue JSON::ParserError
+        raise
+      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 log(message, level: :info) = @log.call(message, level:)
+  end
+end

data/lib/locallingo/cli.rb

@@ -99,17 +99,24 @@ module Locallingo
       @options
     end
 
+    def add_force_options(opts)
+      opts.on("-f", "--force", "Force re-translation of all keys") { @options[:force] = true }
+      opts.on("--force-key KEY", "Force re-translation of a specific key") do |v|
+        (@options[:force_keys] ||= []) << v
+      end
+      opts.on("--include-manual", "translate: let --force-key overwrite manual (hand-edited) keys") do
+        @options[:include_manual] = true
+      end
+    end
+
     def build_parser
       OptionParser.new do |opts|
         opts.banner = "Usage: #{CLI_NAME} <command> [options]\n\nCommands:\n  " \
                       "#{COMMANDS.keys.join(", ")}\n\nOptions:"
 
         opts.on("-l", "--locale LOCALE", "Process specific locale") { |v| @options[:locale] = v }
-        opts.on("-f", "--force", "Force re-translation of all keys") { @options[:force] = true }
-        opts.on("--force-key KEY", "Force re-translation of a specific key") do |v|
-          (@options[:force_keys] ||= []) << v
-        end
-        opts.on("--key KEY", "accept-edits: accept a specific key (repeatable)") do |v|
+        add_force_options(opts)
+        opts.on("--key KEY", "accept-edits, quality: act on a specific key (repeatable)") do |v|
           (@options[:keys] ||= []) << v
         end
         opts.on("--all", "accept-edits: mark every translated key as manual") { @options[:all] = true }
@@ -120,7 +127,7 @@ module Locallingo
           @options[:strict] = true
           @options[:strict_all] = true
         end
-        opts.on("--ai", "Use AI for quality suggestions") { @options[:use_ai] = true }
+        quality_options(opts)
         opts.on("--json", "Output in JSON format") { @options[:format] = :json }
         opts.on("--package PATH", "Scope to a package from .locallingo.yml") { |v| @options[:package] = v }
         opts.on("-h", "--help", "Show this help") do
@@ -130,6 +137,13 @@ module Locallingo
       end
     end
 
+    def quality_options(opts)
+      opts.on("--ai", "Use AI for quality suggestions") { @options[:use_ai] = true }
+      opts.on("--prefix PREFIX", "quality: check only keys starting with PREFIX (e.g. yoga.)") do |v|
+        @options[:prefix] = v
+      end
+    end
+
     def dispatch(command, config, options)
       reporter = Reporter.new(config:, format: options[:format], cli_name: CLI_NAME)
 
@@ -155,13 +169,29 @@ module Locallingo
     def cmd_translate(config, options)
       mgr = manager(config, options)
       puts "🔄 Translating..." if options[:verbose]
-      mgr.translate!(locale: options[:locale], force: options[:force], force_keys: options[:force_keys] || [])
+      failed = mgr.translate!(locale: options[:locale], force: options[:force],
+                              force_keys: options[:force_keys] || [],
+                              include_manual: options.fetch(:include_manual, false))
       unless options[:dry_run]
         puts "📝 Running post-translate hooks..."
         mgr.run_after_translate_hooks
       end
-      puts "✅ Translation complete!"
-      puts "(dry run - no changes made)" if options[:dry_run]
+      report_translated(failed, dry_run: options[:dry_run])
+    end
+
+    # Hooks have already run for the keys that were written; a failed key still
+    # fails the run (outside --dry-run) so CI does not ship missing translations.
+    def report_translated(failed, dry_run:)
+      count = failed.values.sum(&:size)
+      if count.zero?
+        puts "✅ Translation complete!"
+      else
+        puts "⚠️ Translation finished: #{count} #{count == 1 ? "key" : "keys"} failed " \
+             "(re-run with -v for details)"
+        failed.each { |locale, keys| keys.each { |key| puts "  - #{locale}: #{key}" } }
+      end
+      puts "(dry run - no changes made)" if dry_run
+      exit 1 if count.positive? && !dry_run
     end
 
     def cmd_validate(config, options, reporter)
@@ -171,7 +201,11 @@ module Locallingo
 
     def cmd_quality(config, options, reporter)
       locale = options[:locale] || config.source_locale
-      suggestions = quality_checker(config, options).check(locale:, use_ai: options[:use_ai])
+      raise Error, "--key and --prefix cannot be combined" if options[:keys] && options[:prefix]
+
+      suggestions = quality_checker(config, options).check(
+        locale:, use_ai: options[:use_ai], prefix: options[:prefix], keys: options[:keys]
+      )
       reporter.quality(suggestions, locale:)
     end
 

data/lib/locallingo/configuration.rb

@@ -55,6 +55,7 @@ module Locallingo
     def translate_model = dig("translate", "model")
     def batch_size = dig("translate", "batch_size")
     def quality_model = dig("quality", "model")
+    def quality_sample_size = dig("quality", "sample_size")
     def british_spellings? = !!dig("quality", "british_spellings")
     def terminology_setting = dig("quality", "terminology")
 
@@ -99,7 +100,7 @@ module Locallingo
     def after_translate = Array(data.fetch("after_translate", []))
 
     BUILTIN_LANGUAGE_NAMES = {
-      "de" => "German", "sv" => "Swedish", "fr" => "French",
+      "en" => "English", "de" => "German", "sv" => "Swedish", "fr" => "French",
       "af" => "Afrikaans", "es" => "Spanish", "it" => "Italian",
       "nl" => "Dutch", "pt" => "Portuguese", "da" => "Danish",
       "nb" => "Norwegian", "no" => "Norwegian", "fi" => "Finnish"

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

@@ -9,6 +9,7 @@ require_relative "configuration"
 require_relative "key_flattener"
 require_relative "state_store"
 require_relative "providers/ruby_llm"
+require_relative "batch_translator"
 require_relative "validators/missing"
 require_relative "validators/outdated"
 require_relative "validators/duplicate_values"
@@ -25,9 +26,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
 
@@ -69,7 +70,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 +90,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 +
@@ -168,6 +177,12 @@ 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, log: method(:log)
+      )
+    end
+
     def sync_locale_state(source, locale)
       target = load_locale_translations(locale)
       locale_state = @state.load(locale)
@@ -210,21 +225,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,82 +258,29 @@ module Locallingo
       end
 
       log("  Completed #{target_locale}: #{successful.size} translated, #{failed.size} 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
+      failed
     end
 
     def translation_prompt(locale)
+      language = config.language_name(locale)
       <<~PROMPT
-        Translate the following texts from #{config.language_name(config.source_locale)} to #{config.language_name(locale)}.
+        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
-        - Use formal business language
         - 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:
@@ -340,6 +311,26 @@ 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| locale_state[key].is_a?(Hash) && locale_state[key]["manual"] }
+      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]
@@ -349,8 +340,8 @@ module Locallingo
           "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.
+        # 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
       end

data/lib/locallingo/providers/ruby_llm.rb

@@ -13,6 +13,11 @@ 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.
     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
@@ -62,7 +67,7 @@ module Locallingo
           model:,
           provider:,
           assume_model_exists: true
-        ).with_instructions(instructions)
+        ).with_instructions(instructions, cache_until_here: true)
 
         response = conversation.ask(JSON.pretty_generate(payload))
         JsonExtraction.extract_object(response.content)

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 = [

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

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

data/lib/locallingo.rb

@@ -7,6 +7,7 @@ require_relative "locallingo/json_extraction"
 require_relative "locallingo/key_flattener"
 require_relative "locallingo/state_store"
 require_relative "locallingo/providers/ruby_llm"
+require_relative "locallingo/batch_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.0
 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,6 +69,7 @@ files:
 - config/locallingo.default.yml
 - exe/lingo
 - lib/locallingo.rb
+- lib/locallingo/batch_translator.rb
 - lib/locallingo/cli.rb
 - lib/locallingo/configuration.rb
 - lib/locallingo/json_extraction.rb