locallingo 0.4.3 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e31de70770225e0fa02a19b214791252d80b79b46f69ff02fe4a4966079fb3bf
-  data.tar.gz: 1b32c3ef52453c291676585fa0ca6a1da301879d292b98de13c017c6d03195e6
+  metadata.gz: b218e7422188db797e061b9cf1133b1b25a630e9e4c6237c04f0f7fa94dd2b4f
+  data.tar.gz: 742d0794ade8f32f9346d4a02b61554b7cb81321569c5297f9d93c3f1639f4e3
 SHA512:
-  metadata.gz: c6293ed9127107f94800a144653e593aa2482aae0d5352dde2a7a02cd9043afedbcd441e112e3e3565e7842b981a9935623c70e94603a26fb0555e31b65397e9
-  data.tar.gz: e20e64e38717897b90ab7607dfe032b52ecd3d9b12af37ec8615ca8811fe2d4fef6d3eefb6f00196e0b1d9f4eded368a0118f3dcbbddc2704d04f6ecb50106b3
+  metadata.gz: 48e0a2e2625a03fc0d78e9b5a9884efc4ec0ee7525533f150865d7bb391c473edd96f44bbca6974a24a6e564d4d08e644a0b36403a5c8a51b28a0943d54c1d1c
+  data.tar.gz: 4f08c9b89ab57351c5099ff6e31c4c24fa6b33a16df8ec0b70cb0ba365e292d90ef0fbe047d4b5494b9c2c7abe0627657c6ce4b545fd4a4552150f7338fd159d

data/CHANGELOG.md

@@ -6,12 +6,81 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+- `Locallingo::Translator#translate(texts, from:, to:, style:, instructions:)`
+  translates a plain `{ key => text }` hash with the configured prompt,
+  glossary, language guide, provider and model, and returns `translations` and
+  `failed`. (#33)
+- `Locallingo::Prompt.translation`: the translation prompt, public. `style:
+  :prose` keeps Markdown structure and drops the UI brevity rule;
+  `instructions:` is appended after the language guide. The CLI's `:ui`
+  prompt is unchanged. (#33)
+- `Providers::RubyLLM.new(provider:, context:)` and `Translator.new(context:)`
+  take a `RubyLLM::Context`; with one, the global `RubyLLM.config` is never
+  written. (#33)
+- `translate.max_batch_chars` limits the source characters per batch (a single
+  value over the limit is sent alone, never split); `translate.pause` sets the
+  sleep after each batch (default `1.0`). (#33)
+- `Locallingo::Drift`: missing / outdated / manual / hand-edited decisions as a
+  value over the state entry shape, for strings and nested values, with a
+  pluggable hasher. `Manager` and the validators use it; behaviour is
+  unchanged. (#33)
+- `require "locallingo/active_record"` adds `Locallingo::Translatable`
+  (`translates_content`), and `Locallingo::RecordTranslator` translates many
+  records in one batched call, writing each under its row lock. (#33)
+- `lingo quality --prefix yoga.` checks only the keys under a prefix, in both
+  the static checks and the AI pass. A prefix that matches nothing exits `1`. (#10, #29)
+- `lingo quality --key a.b` (repeatable) checks exactly the named keys, and the
+  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 +90,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
@@ -144,6 +146,98 @@ Locallingo::Manager.new(config:).validate           # => [violations]
 Locallingo::QualityChecker.new(config:).check(locale: "en")
 ```
 
+### Translating text that is not in locale files
+
+`Locallingo::Translator` runs the same prompt (rules, glossary, language guide),
+provider, model and batching over a plain `{ key => text }` hash:
+
+```ruby
+require "ruby_llm" # for RubyLLM.context (Bundler.require already loads it in Rails)
+
+translator = Locallingo::Translator.new(
+  config: Locallingo.configuration(root_path: Dir.pwd),
+  context: RubyLLM.context { |c| c.anthropic_api_key = tenant_key }, # optional, per-tenant key
+  pause: 0                                                           # no sleep between batches
+)
+
+result = translator.translate(
+  { "title" => "Hello", "intro" => "Some **markdown**." },
+  from: "en", to: "de",
+  style: :prose,                                 # :ui (default) or :prose (keeps Markdown, no brevity rule)
+  instructions: "Write in a warm, plain voice."  # appended after the language guide
+)
+result.translations # => { "title" => "Hallo", "intro" => "Etwas **Markdown**." }
+result.failed       # => keys that failed after retries
+```
+
+- With a `context:`, every call uses that `RubyLLM::Context`'s config; the
+  global `RubyLLM.config` is never written, so tenants can translate
+  concurrently.
+- `MissingCredentialsError` is raised before any call when no key is found.
+- `translate.max_batch_chars` (or `max_batch_chars:`) limits the source
+  characters per batch (a single longer value is sent alone, not split); `translate.pause` (or `pause:`) is the sleep after each
+  batch. Retries of failed or omitted keys keep their own backoff.
+- `Locallingo::Prompt.translation(config:, from:, to:, style:, instructions:)`
+  returns the prompt itself.
+
+`Locallingo::Drift` is the missing / outdated / hand-edited rule over the state
+entry shape (`source_hash`, `target_hash`, `manual`), for strings or nested
+values:
+
+```ruby
+drift = Locallingo::Drift.new  # hasher: any callable(String) -> String
+drift.status(source:, target:, entry:)  # => :missing | :outdated | :current
+drift.due?(source:, target:, entry:, force: false, include_manual: false)
+drift.hand_edited?(target:, entry:)
+drift.record(source:, target:, manual: false) # => a new entry
+```
+
+### Translating records
+
+`require "locallingo/active_record"` (ActiveRecord >= 7.1; nothing loads
+ActiveRecord otherwise) adds a concern for a JSON(B) column keyed by locale
+plus a JSON(B) state column:
+
+```ruby
+class Article < ApplicationRecord
+  include Locallingo::Translatable
+
+  translates_content :body,                  # { "en" => { … }, "de" => { … } }
+    state: :translation_state,               # { "de" => { "source_hash", "target_hash", "manual" } }
+    source_locale: -> { "en" },              # String/Symbol, or a callable run on the record
+    target_locales: -> { %w[de sv] },
+    translatable: ->(path, value) { true }   # optional filter on flattened String leaves
+end
+
+article.translation_status(:de)   # => :missing | :outdated | :current
+article.translation_manual?(:de)
+article.translation_due?(:de, force: false)
+article.record_translation(:de, manual: false)
+
+Locallingo::RecordTranslator.new(translator:)
+  .call(Article.where(id: ids), to: "de", style: :prose)
+# => { translated: 3, failed: { article_id => [paths] }, skipped: [ids] }
+```
+
+- Saving a record runs `mark_hand_edits`: a target locale a person changed is
+  flagged `manual` and never machine-overwritten (`include_manual: true`
+  overrides, keeping the flag). That includes a target locale saved for the
+  first time, e.g. a source copy used as a placeholder at `create!`: leave
+  untranslated locales out of the column instead. A cleared locale is not
+  flagged and is due again, unless it was already `manual`: the flag stays, so
+  retranslating it needs `include_manual: true`.
+- `RecordTranslator` sends one batched translation per source locale across all
+  due records, then writes each record under `record.with_lock`. A record whose
+  source changed, or whose target became manual, while the model answered is
+  skipped (`skipped:`) and left for the next run, as is a due record with no
+  translatable text.
+- Nested values keep their shape; leaves the `translatable:` filter rejects are
+  copied from the source. A record with any segment that failed after retries
+  is not written at all: its paths are reported in `failed:`, and it stays due
+  for the next run (your fallback to the source locale applies meanwhile).
+- Writes use `update_columns`; pass `write: ->(record, attributes) { … }` to
+  bump a lock version or run validations.
+
 ## License
 
 MIT © Mikael Henriksson

data/config/locallingo.default.yml

@@ -26,9 +26,18 @@ defaults:
   translate:
     model: gpt-5-mini
     batch_size: 20
+    # Optional cap on the characters of source text per batch (a batch closes at
+    # batch_size keys or max_batch_chars, whichever comes first). Useful for long
+    # prose; a single oversized value is still sent alone. null = keys only.
+    max_batch_chars: null
+    # Seconds to sleep after each batch (rate-limit courtesy). 0 disables it.
+    pause: 1.0
 
   quality:
     model: gpt-4o-mini
+    # 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 +50,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/active_record.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+require_relative "../locallingo"
+require_relative "content_leaves"
+
+module Locallingo
+  # Opt-in ActiveRecord concern (`require "locallingo/active_record"`) for the
+  # common shape: a JSON(B) column keyed by locale plus a JSON(B) state column
+  # holding one Drift entry per target locale. Supports ActiveRecord >= 7.1.
+  #
+  #   class Article < ApplicationRecord
+  #     include Locallingo::Translatable
+  #
+  #     translates_content :body,                # { "en" => { … }, "de" => { … } }
+  #       state: :translation_state,             # { "de" => { "source_hash", "target_hash", "manual" } }
+  #       source_locale: -> { "en" },            # String/Symbol, or a callable run on the record
+  #       target_locales: -> { %w[de sv] },
+  #       translatable: ->(path, value) { true } # optional filter on flattened String leaves
+  #   end
+  #
+  # A `before_save` callback (#mark_hand_edits) flags target locales a person
+  # changed as manual, so Locallingo::RecordTranslator never overwrites them.
+  module Translatable
+    extend ActiveSupport::Concern
+
+    Definition = Data.define(:column, :state, :source_locale, :target_locales, :translatable, :drift)
+
+    included do
+      class_attribute :locallingo_translatable, instance_writer: false
+    end
+
+    class_methods do
+      def translates_content(column, state:, source_locale:, target_locales:, translatable: nil, hasher: nil)
+        self.locallingo_translatable = Definition.new(
+          column: column.to_s, state: state.to_s, source_locale:, target_locales:,
+          translatable: translatable || ->(_path, _value) { true },
+          drift: hasher ? Drift.new(hasher:) : Drift.new
+        )
+        before_save :mark_hand_edits
+      end
+    end
+
+    def translation_source_locale = resolve_translation_option(locallingo_translatable.source_locale).to_s
+
+    def translation_target_locales
+      Array(resolve_translation_option(locallingo_translatable.target_locales)).map(&:to_s)
+    end
+
+    def translation_source = translation_content[translation_source_locale]
+    def translation_target(locale) = translation_content[locale.to_s]
+    def translation_entry(locale) = translation_states[locale.to_s]
+    def translation_source_digest = translation_drift.digest(translation_source)
+
+    def translation_status(locale)
+      translation_drift.status(source: translation_source, target: translation_target(locale),
+                               entry: translation_entry(locale))
+    end
+
+    def translation_manual?(locale) = translation_drift.manual?(translation_entry(locale))
+
+    def translation_due?(locale, force: false, include_manual: false)
+      translation_drift.due?(source: translation_source, target: translation_target(locale),
+                             entry: translation_entry(locale), force:, include_manual:)
+    end
+
+    # Records the current source and target of +locale+ as its state entry
+    # (assigned, not saved).
+    def record_translation(locale, manual: false)
+      entry = translation_drift.record(source: translation_source, target: translation_target(locale), manual:)
+      self[locallingo_translatable.state] = translation_states.merge(locale.to_s => entry)
+    end
+
+    # Flags every target locale a person changed as manual: a recorded target
+    # that no longer matches its target_hash, or an untracked locale written in
+    # this save. A cleared target is not flagged — it is missing and due again.
+    def mark_hand_edits
+      (translation_target_locales - [translation_source_locale]).each do |locale|
+        target = translation_target(locale)
+        next if translation_drift.blank?(target)
+
+        entry = translation_entry(locale)
+        next unless translation_drift.hand_edited?(target:, entry:) || (entry.nil? && translation_written?(locale))
+
+        # A recorded source_hash is kept: a hand edit does not make an
+        # outdated translation current.
+        manual = translation_drift.record(source: translation_source, target:, manual: true)
+        manual["source_hash"] = entry["source_hash"] if entry&.key?("source_hash")
+        self[locallingo_translatable.state] = translation_states.merge(locale => manual)
+      end
+    end
+
+    # The source's translatable String leaves, flattened (`steps[1].text`,
+    # `table[0][1]`). Unlike KeyFlattener, strings in nested arrays count.
+    def translation_segments
+      translation_leaves.filter_map do |path, (_, value)|
+        next unless value.is_a?(String) && !value.strip.empty?
+
+        [path, value] if locallingo_translatable.translatable.call(path, value)
+      end.to_h
+    end
+
+    # The target for translated +segments+ (`path => text`): a deep copy of the
+    # source with each translated leaf set in place, so every other value and
+    # container (numbers, nested lists, empty ones) keeps its place.
+    def build_translation_target(segments)
+      target = JSON.parse(JSON.generate(translation_source || {}))
+      leaves = translation_leaves
+      segments.each do |path, text|
+        *parents, last = leaves.fetch(path).first
+        (parents.empty? ? target : target.dig(*parents))[last] = text
+      end
+      target
+    end
+
+    # Column attributes that write +target+ for +locale+ plus its state entry.
+    def translation_attributes(locale, target, manual: false)
+      locale = locale.to_s
+      entry = translation_drift.record(source: translation_source, target:, manual:)
+      {
+        locallingo_translatable.column => translation_content.merge(locale => target),
+        locallingo_translatable.state => translation_states.merge(locale => entry)
+      }
+    end
+
+    def translation_drift = locallingo_translatable.drift
+
+    private
+
+    def translation_leaves = ContentLeaves.call(translation_source || {}, label: "#{self.class.name}##{id}")
+
+    def translation_content = self[locallingo_translatable.column] || {}
+    def translation_states = self[locallingo_translatable.state] || {}
+
+    def translation_written?(locale)
+      column = locallingo_translatable.column
+      return false unless will_save_change_to_attribute?(column)
+
+      (attribute_in_database(column) || {})[locale] != translation_target(locale)
+    end
+
+    def resolve_translation_option(option)
+      option.respond_to?(:call) ? instance_exec(&option) : option
+    end
+  end
+end

data/lib/locallingo/batch_translator.rb

@@ -0,0 +1,151 @@
+# 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)`.
+    #
+    # A batch closes at `batch_size` keys or `max_batch_chars` characters of
+    # source text, whichever comes first; a single oversized value goes alone.
+    # `pause` is the sleep after each batch (0 in a background job).
+    def initialize(provider:, model:, batch_size:, log:, max_batch_chars: nil, pause: BASE_SLEEP_DURATION)
+      @provider = provider
+      @model = model
+      @batch_size = batch_size
+      @max_batch_chars = max_batch_chars
+      @pause = pause
+      @log = log
+    end
+
+    # 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 = []
+
+      batches(keys).each do |batch|
+        result = translate_batch(batch.to_h { |key| [key, @source[key]] })
+        batch.each do |key|
+          if result.key?(key) && !result[key].to_s.empty?
+            translations[key] = result[key]
+          else
+            failed << key
+          end
+        end
+        sleep(@pause) if @pause.positive?
+      end
+
+      [translations, failed]
+    end
+
+    def batches(keys)
+      return keys.each_slice(@batch_size).to_a unless @max_batch_chars
+
+      keys.each_with_object([[]]) do |key, groups|
+        groups << [] if full?(groups.last, key)
+        groups.last << key
+      end
+    end
+
+    def full?(batch, key)
+      return false if batch.empty?
+
+      batch.size >= @batch_size || chars(batch) + chars([key]) > @max_batch_chars
+    end
+
+    def chars(batch) = batch.sum { |key| @source[key].to_s.length }
+
+    def translate_batch(payload)
+      return {} if payload.empty?
+
+      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

@@ -54,7 +54,10 @@ module Locallingo
     def provider = data.fetch("provider").to_sym
     def translate_model = dig("translate", "model")
     def batch_size = dig("translate", "batch_size")
+    def max_batch_chars = dig("translate", "max_batch_chars")
+    def pause = dig("translate", "pause") || 1.0
     def quality_model = dig("quality", "model")
+    def quality_sample_size = dig("quality", "sample_size")
     def british_spellings? = !!dig("quality", "british_spellings")
     def terminology_setting = dig("quality", "terminology")
 
@@ -99,7 +102,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"