locallingo 0.1.0

data/lib/locallingo/quality/static_rules.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Locallingo
+  module Quality
+    # Regex-based, provider-free translation-quality rules. Ported from the
+    # original TranslationQualityChecker STATIC_RULES / UNIVERSAL_FIXES.
+    module StaticRules
+      # Locale-agnostic auto-fixable corrections.
+      UNIVERSAL_FIXES = {
+        "can not" => "cannot",
+        "Can not" => "Cannot"
+      }.freeze
+
+      RULES = {
+        terminology: {
+          /\bcan not\b/i => "Use 'cannot' (one word)",
+          /\blogin\s+(to|regularly|now|here|again|first|using|with)\b/i =>
+            "Use 'log in' (verb) not 'login' here",
+          /\bclick\s+here\b/i => "Avoid 'click here' - use descriptive link text",
+          /\bplease\b.*\bplease\b/i => "Multiple 'please' in same text - remove redundancy"
+        },
+        placeholders: {
+          /%\{[^}]*\s[^}]*\}/ => "Placeholder contains spaces - may cause issues",
+          /%\{[A-Z]/ => "Placeholder starts with uppercase - convention is lowercase"
+        },
+        clarity: {
+          /\betc\.?\b/i => "Avoid 'etc.' - be specific or use 'and more'",
+          /\bstuff\b/i => "Vague word 'stuff' - be more specific",
+          /\bthings\b/i => "Vague word 'things' - be more specific",
+          /\basap\b/i => "Avoid abbreviation 'ASAP' - use 'as soon as possible'",
+          /\bfyi\b/i => "Avoid abbreviation 'FYI' - rephrase",
+          /\s{2,}/ => "Multiple consecutive spaces"
+        },
+        business: {
+          /\bsorry\b/i => "Consider 'We apologize' for formal business tone",
+          /\boops\b/i => "Informal - use professional error messaging",
+          /\buh\s*oh\b/i => "Informal - use professional error messaging",
+          /\bawesome\b/i => "Consider more professional alternatives",
+          /\bcool\b(?!\s*down)/i => "Informal - consider 'great' or 'excellent'"
+        },
+        accessibility: {
+          /\bsee\s+below\b/i => "Screen reader unfriendly - describe the content",
+          /\babove\b/i => "Positional reference - may not work for all users",
+          /\bred\b.*\berror\b|\berror\b.*\bred\b/i => "Don't rely on color alone for meaning"
+        }
+      }.freeze
+
+      module_function
+
+      # Suggestions from the regex RULES for one key/text pair.
+      def check(key, text, locale)
+        suggestions = []
+
+        RULES.each do |category, rules|
+          rules.each do |pattern, message|
+            next unless text.match?(pattern)
+
+            suggestions << {
+              key:, text:, locale:, category:,
+              issue: message,
+              match: text.match(pattern).to_s,
+              severity: severity_for_category(category),
+              source: :static
+            }
+          end
+        end
+
+        suggestions
+      end
+
+      # Auto-fixable universal fixes for one key/text pair.
+      def universal_fixes(key, text, locale)
+        UNIVERSAL_FIXES.filter_map do |wrong, correct|
+          next unless text.include?(wrong)
+
+          {
+            key:, text:, locale:,
+            category: :grammar,
+            issue: "Use '#{correct}' instead of '#{wrong}'",
+            match: wrong,
+            fix: { from: wrong, to: correct },
+            severity: :warning,
+            source: :static
+          }
+        end
+      end
+
+      def severity_for_category(category)
+        case category
+        when :placeholders then :error
+        when :terminology, :accessibility then :warning
+        else :info # :clarity, :business, :length, etc.
+        end
+      end
+    end
+  end
+end

data/lib/locallingo/quality/terminology.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Locallingo
+  module Quality
+    # Business/domain terminology checks. A term maps to a suggestion string, or
+    # to nil when the term is acceptable (present only so it is documented as
+    # reviewed). Selected by `quality.terminology`: a built-in name ("business",
+    # "banking", "none") or a path to a custom YAML file.
+    class Terminology
+      # Generic business terminology (the cosmos-2 default).
+      BUSINESS = {
+        "wire transfer" => "Consider 'bank transfer' for broader understanding",
+        "checking account" => "Use 'current account' for non-US markets",
+        "savings account" => nil,
+        "routing number" => "Use 'sort code' (UK) or 'branch code' for non-US",
+        "zip code" => "Use 'postal code' for international audiences",
+        "transaction" => nil,
+        "company" => nil,
+        "business" => nil,
+        "customer" => nil,
+        "client" => nil,
+        "beneficiary" => nil,
+        "payee" => nil,
+        "kyc" => nil,
+        "kyb" => nil
+      }.freeze
+
+      # Banking terminology (the zazu/app default) — a superset of BUSINESS with
+      # extra always-acceptable regulatory terms.
+      BANKING = BUSINESS.merge(
+        "know your customer" => nil,
+        "know your business" => nil,
+        "aml" => nil,
+        "cdd" => nil
+      ).freeze
+
+      BUILTINS = { "business" => BUSINESS, "banking" => BANKING, "none" => {} }.freeze
+
+      attr_reader :terms
+
+      # +setting+ is a built-in name, a path to a YAML file, or nil (=> business).
+      def initialize(setting, base_path: Dir.pwd)
+        @terms = resolve(setting, base_path)
+      end
+
+      # Suggestions for flagged (non-nil) terms found in +text+.
+      def check(key, text, locale)
+        terms.filter_map do |term, suggestion|
+          next unless suggestion
+          next unless text.downcase.include?(term.downcase)
+
+          {
+            key:, text:, locale:,
+            category: :terminology,
+            issue: suggestion,
+            match: term,
+            severity: :info,
+            source: :static
+          }
+        end
+      end
+
+      private
+
+      def resolve(setting, base_path)
+        return BUSINESS if setting.nil?
+        return BUILTINS.fetch(setting) if BUILTINS.key?(setting)
+
+        path = File.expand_path(setting, base_path)
+        raise Error, "Unknown terminology #{setting.inspect} (not a builtin or a file)" unless File.exist?(path)
+
+        YAML.safe_load_file(path) || {}
+      end
+    end
+  end
+end

data/lib/locallingo/quality_checker.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "configuration"
+require_relative "key_flattener"
+require_relative "providers/ruby_llm"
+require_relative "quality/static_rules"
+require_relative "quality/british_spellings"
+require_relative "quality/terminology"
+
+module Locallingo
+  # Checks translation quality and suggests improvements.
+  #
+  # Static (provider-free) checks: regex rules, universal fixes, terminology,
+  # optional British-spelling drift, and a very-long-text heuristic. An optional
+  # AI pass (RubyLLM) reviews a sample for clarity/professionalism.
+  #
+  # `fix!` rewrites the auto-fixable suggestions (universal fixes + British
+  # spellings) back into the locale files, preserving case.
+  class QualityChecker
+    LONG_TEXT_THRESHOLD = 200
+
+    attr_reader :config, :verbose, :logger
+
+    def initialize(config: nil, root_path: nil, package: nil, verbose: false, logger: nil)
+      @config = config || Configuration.load(root_path: root_path || Dir.pwd, package:)
+      @verbose = verbose
+      @logger = logger
+      @provider = Providers::RubyLLM.new(provider: @config.provider)
+      @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)
+      locale ||= config.source_locale
+      translations = load_locale_translations(locale)
+
+      suggestions = translations.flat_map { |key, text| check_text(key, text, locale) }
+      suggestions.concat(ai_sample(translations, locale)) if use_ai
+      suggestions
+    end
+
+    # Check a single key.
+    def check_key(key, locale, use_ai: false)
+      translations = load_locale_translations(locale)
+      text = translations[key]
+      return [{ key:, error: "Key not found" }] unless text
+
+      suggestions = check_text(key, text, locale)
+      suggestions.concat(suggest_improvements({ key => text }, locale)) if use_ai
+      suggestions
+    end
+
+    # Auto-fix the fixable suggestions in the locale files. Returns
+    # { fixed: <file count>, skipped: <non-fixable count> }.
+    def fix!(locale: nil, dry_run: false)
+      locale ||= config.source_locale
+      suggestions = check(locale:)
+      fixable = suggestions.select { |s| s[:fix] }
+      return { fixed: 0, skipped: suggestions.size - fixable.size } if fixable.empty?
+
+      changed = apply_fixes(locale, fixable)
+
+      changed.each { |file, content| File.write(file, content) } unless dry_run
+      changed.each_key { |file| log("#{dry_run ? "Would fix" : "Fixed"}: #{file}") }
+
+      { fixed: changed.size, skipped: suggestions.size - fixable.size }
+    end
+
+    # AI suggestions for a batch of key=>text pairs.
+    def suggest_improvements(keys_with_text, locale)
+      unless @provider.credentials?
+        warn "⚠️  No LLM credentials — skipping AI suggestions"
+        return []
+      end
+
+      result = @provider.chat(
+        model: config.quality_model,
+        instructions: quality_prompt(locale),
+        payload: keys_with_text
+      )
+
+      result.map do |key, suggestion|
+        symbolized = suggestion.transform_keys(&:to_sym)
+        symbolized[:severity] = symbolized[:severity]&.to_sym || :info
+        { key:, text: keys_with_text[key], locale:, source: :ai, **symbolized }
+      end
+    rescue StandardError => e
+      warn "⚠️  AI suggestion failed: #{e.message}"
+      []
+    end
+
+    private
+
+    def check_text(key, text, locale)
+      suggestions = []
+      suggestions.concat(Quality::StaticRules.universal_fixes(key, text, locale))
+      suggestions.concat(Quality::StaticRules.check(key, text, locale))
+      suggestions.concat(@terminology.check(key, text, locale))
+      suggestions.concat(Quality::BritishSpellings.check(key, text, locale)) if british_spellings_for?(locale)
+      suggestions << long_text_suggestion(key, text, locale) if text.length > LONG_TEXT_THRESHOLD
+      suggestions.compact
+    end
+
+    def british_spellings_for?(locale)
+      config.british_spellings? && locale.to_s == config.source_locale.to_s
+    end
+
+    def long_text_suggestion(key, text, locale)
+      {
+        key:, text: truncate(text, 100), locale:,
+        category: :length,
+        issue: "Text is very long (#{text.length} chars) - consider splitting",
+        severity: :info, source: :static
+      }
+    end
+
+    def ai_sample(translations, locale)
+      sample_size = [translations.size, 100].min
+      sample = translations.to_a.sample(sample_size).to_h
+      suggest_improvements(sample, locale)
+    end
+
+    def apply_fixes(locale, fixable)
+      changed = {}
+      Dir.glob(File.join(config.locales_dir, "**", "*.#{locale}.yml")).each do |file|
+        original = File.read(file)
+        content = original.dup
+
+        fixable.each do |suggestion|
+          next unless content.include?(suggestion[:text])
+
+          fixed_text = apply_case_preserving_fix(suggestion[:text], suggestion[:fix])
+          content = content.gsub(suggestion[:text], fixed_text)
+        end
+
+        changed[file] = content if content != original
+      end
+      changed
+    end
+
+    def apply_case_preserving_fix(text, fix)
+      text.gsub(/\b#{Regexp.escape(fix[:from])}\b/i) do |match|
+        if match == match.upcase then fix[:to].upcase
+        elsif match[0] == match[0].upcase then fix[:to].capitalize
+        else fix[:to]
+        end
+      end
+    end
+
+    def quality_prompt(locale)
+      <<~PROMPT
+        Review these UI translations for #{config.context}.
+        Suggest improvements for clarity, professionalism, and user-friendliness.
+        #{glossary_section}
+        For each translation that needs improvement, provide:
+        1. The issue (brief)
+        2. Suggested improvement
+        3. Severity: "error" (must fix), "warning" (should fix), "info" (nice to have)
+
+        Only include translations that actually need changes.
+        Return ONLY a raw JSON object, with no surrounding prose and no markdown
+        code fences: {"key": {"issue": "...", "suggestion": "...", "severity": "..."}}
+
+        Locale: #{locale}
+      PROMPT
+    end
+
+    def glossary_section
+      return "" if config.glossary.empty?
+
+      lines = config.glossary.map { |term, meaning| "        - \"#{term}\" = #{meaning}" }
+      "\n#{config.context} terminology:\n#{lines.join("\n")}\n"
+    end
+
+    def load_locale_translations(locale)
+      translations = {}
+      patterns = [
+        File.join(config.locales_dir, "**", "*.#{locale}.yml"),
+        File.join(config.locales_dir, "#{locale}.yml")
+      ]
+
+      patterns.each do |pattern|
+        Dir.glob(pattern).each do |file|
+          content = YAML.load_file(file)
+          next unless content.is_a?(Hash) && content[locale]
+
+          KeyFlattener.flatten(content[locale]).each do |key, value|
+            translations[key] = value if value.is_a?(String)
+          end
+        end
+      end
+
+      translations
+    end
+
+    def truncate(text, length)
+      text.length > length ? "#{text[0, length]}..." : text
+    end
+
+    def log(message)
+      logger&.info(message)
+      warn(message) if verbose
+    end
+  end
+end

data/lib/locallingo/reporter.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Locallingo
+  # Renders status/violation/quality output for the CLI (text + JSON) and
+  # computes strict exit codes. Extracted from the original bin/translate
+  # printers so the CLI stays thin.
+  class Reporter
+    SEVERITY_ICONS = { error: "🔴", warning: "🟡", info: "🔵" }.freeze
+    TYPE_ICONS = {
+      missing: "❌", outdated: "🔄", duplicate_value: "🔁", manual_edit: "✏️"
+    }.freeze
+
+    def initialize(config:, format: :text, io: $stdout, cli_name: "lingo")
+      @config = config
+      @format = format
+      @io = io
+      @cli_name = cli_name
+    end
+
+    def status(status)
+      return json(status) if json?
+
+      puts "\n📊 Translation Status"
+      puts "=" * 60
+      status.each { |locale, info| print_locale_status(locale, info) }
+      puts ""
+    end
+
+    # Prints violations and returns the strict exit code.
+    def violations(violations, strict: false, strict_all: false)
+      if json?
+        json(violations)
+        return exit_code(violations, strict:, strict_all:)
+      end
+
+      if violations.empty?
+        puts "\n✅ All translations valid!"
+        return 0
+      end
+
+      puts "\n❌ Translation Issues Found"
+      puts "=" * 60
+      violations.group_by { |v| v[:type] }.each { |type, items| print_violation_group(type, items) }
+      puts "\nTotal: #{violations.size} issues"
+
+      exit_code(violations, strict:, strict_all:)
+    end
+
+    def quality(suggestions, locale:)
+      return json(suggestions) if json?
+
+      if suggestions.empty?
+        puts "\n✅ No quality issues found!"
+        return
+      end
+
+      puts "\n📝 Translation Quality Suggestions"
+      puts "=" * 60
+      print_quality_by_severity(suggestions)
+      print_quality_summary(suggestions, locale)
+    end
+
+    # Exit code for a strict tier, per the configured strict_types.
+    def exit_code(violations, strict:, strict_all:)
+      return 0 unless strict || strict_all
+
+      tier = strict_all ? :strict_all : :strict
+      error_types = @config.strict_types(tier)
+      violations.any? { |v| error_types.include?(v[:type]) } ? 1 : 0
+    end
+
+    private
+
+    def json? = @format == :json
+    def puts(str = "") = @io.puts(str)
+
+    def json(data)
+      @io.puts(JSON.pretty_generate(data))
+    end
+
+    def print_locale_status(locale, info)
+      icon = info[:missing].zero? && info[:outdated].zero? ? "✅" : "⚠️"
+      puts "\n#{icon} #{locale}"
+      puts "   Total keys: #{info[:total_keys]}"
+      puts "   Translated: #{info[:translated]}"
+      puts "   Missing: #{info[:missing]}"
+      puts "   Outdated: #{info[:outdated]}"
+      print_key_list("Missing (first 10):", info[:missing_keys])
+      print_key_list("Outdated (first 10):", info[:outdated_keys])
+    end
+
+    def print_key_list(label, keys)
+      return unless keys&.any?
+
+      puts "   #{label}"
+      keys.each { |k| puts "     - #{k}" }
+    end
+
+    def print_violation_group(type, items)
+      puts "\n#{TYPE_ICONS.fetch(type, "❓")} #{type.to_s.tr("_", " ").capitalize} (#{items.size})"
+      items.first(10).each do |v|
+        puts "   #{v[:locale]}: #{v[:key]}"
+        puts "      → #{v[:suggestion]}"
+      end
+      puts "   ... and #{items.size - 10} more" if items.size > 10
+    end
+
+    def print_quality_by_severity(suggestions)
+      by_severity = suggestions.group_by { |s| s[:severity] }
+      %i[error warning info].each do |severity|
+        items = by_severity[severity] || []
+        next if items.empty?
+
+        fixable = items.count { |s| s[:fix] }
+        note = fixable.positive? ? " (#{fixable} auto-fixable)" : ""
+        puts "\n#{SEVERITY_ICONS[severity]} #{severity.to_s.capitalize} (#{items.size})#{note}"
+        items.first(20).each { |s| print_quality_item(s) }
+        puts "   ... and #{items.size - 20} more" if items.size > 20
+      end
+    end
+
+    def print_quality_item(suggestion)
+      puts "   #{suggestion[:key]}"
+      puts "      Text: #{truncate(suggestion[:text].to_s, 60)}"
+      puts "      Issue: #{suggestion[:issue]}"
+      puts "      Fix: Replace '#{suggestion[:fix][:from]}' → '#{suggestion[:fix][:to]}'" if suggestion[:fix]
+      puts ""
+    end
+
+    def print_quality_summary(suggestions, locale)
+      fixable = suggestions.count { |s| s[:fix] }
+      puts "\n#{"-" * 60}"
+      puts "Summary: #{suggestions.size} issues found"
+      if fixable.positive?
+        puts "\nTo auto-fix #{fixable} issues, run:"
+        puts "  #{@cli_name} fix-quality --locale #{locale}"
+      end
+      puts ""
+    end
+
+    def truncate(text, length)
+      text.length > length ? "#{text[0, length]}..." : text
+    end
+  end
+end

data/lib/locallingo/rubocop.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Loads Locallingo's RuboCop cops. `require`d only from a host app's
+# `.rubocop.yml` (`require: locallingo/rubocop`), so `rubocop` is never pulled
+# into the app's runtime — it is a development-time dependency of both the host
+# app and this gem.
+#
+# The shipped defaults live in config/default.yml; a host app enables/scopes the
+# cops there via `inherit_gem`.
+
+require "rubocop"
+
+require_relative "../rubocop/cop/locallingo/relative_i18n_key"
+require_relative "../rubocop/cop/locallingo/strftime_in_view"
+
+module Locallingo
+  # Absolute path to the cop defaults, for `inherit_gem: locallingo: <path>`.
+  module RuboCop
+    CONFIG_DEFAULT = File.expand_path("../../config/default.yml", __dir__)
+  end
+end

data/lib/locallingo/state_store.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+require "zlib"
+require "fileutils"
+
+module Locallingo
+  # Reads and writes the source-hash drift state under `state_dir`.
+  #
+  # State is split into one JSON file per top-level namespace and locale
+  # (`accounts.de.json`, ...) so diffs stay small and reviewable. Each entry
+  # records the source hash a key was translated from, so a later source change
+  # marks the translation outdated. Optionally a `target_hash` and `manual` flag
+  # are tracked so hand-edited target values can be protected from overwrites.
+  class StateStore
+    attr_reader :state_dir
+
+    def initialize(state_dir)
+      @state_dir = state_dir
+      FileUtils.mkdir_p(@state_dir)
+    end
+
+    # CRC32 hash — fast and compact (8 hex chars).
+    def self.hash(text)
+      format("%08x", Zlib.crc32(text.to_s))
+    end
+
+    def hash(text) = self.class.hash(text)
+
+    # Load the combined state for a locale (merged across its namespace files).
+    def load(locale)
+      combined = {}
+      Dir.glob(File.join(state_dir, "*.#{locale}.json")).each do |file|
+        combined.merge!(JSON.parse(File.read(file)))
+      end
+      combined
+    rescue JSON::ParserError => e
+      raise Error,
+            "Corrupted state file: #{e.message}\n" \
+            "This would cause state loss. Fix the JSON manually or restore from git."
+    end
+
+    # Save a locale's state, split back into per-namespace files. Namespace files
+    # that no longer have keys are removed.
+    def save(locale, locale_state)
+      by_namespace = locale_state.each_with_object({}) do |(key, value), groups|
+        namespace = key.split(".").first
+        (groups[namespace] ||= {})[key] = value
+      end
+
+      by_namespace.each do |namespace, keys|
+        state_file = File.join(state_dir, "#{namespace}.#{locale}.json")
+        File.write(state_file, JSON.pretty_generate(keys.sort.to_h))
+      end
+
+      Dir.glob(File.join(state_dir, "*.#{locale}.json")).each do |file|
+        namespace = File.basename(file).delete_suffix(".#{locale}.json")
+        File.delete(file) unless by_namespace.key?(namespace)
+      end
+    end
+  end
+end

data/lib/locallingo/validators/duplicate_values.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Locallingo
+  module Validators
+    # Detects source-locale keys whose value matches an
+    # `activerecord.attributes.*` value. The AR key wins; the non-AR key is the
+    # "duplicate" and should reuse the AR key instead.
+    #
+    # Operates on the flat source hash only, to avoid false positives from
+    # grammatical-form differences in non-English locales.
+    class DuplicateValues
+      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:)
+        ar_keys_by_value = source
+                           .select { |key, _| key.start_with?(AR_ATTRIBUTES_PREFIX) }
+                           .group_by { |_key, value| value }
+                           .transform_values { |pairs| pairs.map(&:first) }
+
+        source.filter_map do |key, value|
+          # Skip ALL activerecord.* keys (models, attributes, etc.). Rails
+          # reserves this namespace for AR-generated translations, and model
+          # names colliding with attribute labels is intentional, not a dup.
+          next if key.start_with?(AR_PREFIX)
+          next unless ar_keys_by_value.key?(value)
+
+          ar_dupes = ar_keys_by_value[value]
+          {
+            type: :duplicate_value,
+            locale: "en",
+            key:,
+            suggestion: "Value '#{value}' duplicates #{ar_dupes.join(", ")}. " \
+                        "Use #{ar_dupes.first} instead."
+          }
+        end
+      end
+    end
+  end
+end

data/lib/locallingo/validators/manual_edits.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../state_store"
+
+module Locallingo
+  module Validators
+    # Detects target values that were hand-edited after Locallingo wrote them.
+    #
+    # When enabled, the Manager records a `target_hash` alongside `source_hash`
+    # for each translated key. If the current target value's hash differs from
+    # the recorded `target_hash` (and the key is not already flagged `manual`),
+    # it was edited by a human — surface it so the operator can protect it with
+    # `accept-edits` before the next translate run overwrites it.
+    class ManualEdits
+      def initialize(cli_name: "lingo")
+        @cli_name = cli_name
+      end
+
+      # +target+ is the flat target hash; +locale_state+ its loaded state.
+      def call(target:, locale_state:, locale:)
+        target.filter_map do |key, value|
+          entry = locale_state[key]
+          next unless entry.is_a?(Hash)
+          next if entry["manual"]
+
+          stored = entry["target_hash"]
+          next unless stored && stored != StateStore.hash(value)
+
+          {
+            type: :manual_edit,
+            locale:,
+            key:,
+            suggestion: "Value was hand-edited. Protect it: #{@cli_name} accept-edits --locale #{locale}"
+          }
+        end
+      end
+    end
+  end
+end