locallingo 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 931aa3bf94ee48a2021c8ec6f5de047e593f2f94bc5ba01e20b48bd1b2e96d3c
-  data.tar.gz: fcbab1174c9dbefb317fdae26a0c0a763f4a3b8026b19f8fe8f08a54d222f8fb
+  metadata.gz: 398a4540431fa5298a1eba1fedecef3c4b7344d2749f935a30882d8899ebcb69
+  data.tar.gz: c854c5c26ebee79b0d5663614207e0f75368c973058a5ac320f58ec4e45e3835
 SHA512:
-  metadata.gz: 9bc87c498dcc47fbda209f58005ce265f09ef5432107bbced4f9185e32ae51873b6aae014f7f11f650cd4905328169cb32e8f477c9ab1d310f2b4692da350ce8
-  data.tar.gz: 65f2c9cbf024baa4cb89202da61fff2d4feb0de544c2ea85371525714e83a322ac93f065ae08239e67f562d0158b0ddf01acd199e9d9060614f3c02afa8f37a5
+  metadata.gz: 5969d9cac09643f81e6e37ae72ad79003373d1870bbaf37300c0e4c5a95449c6c422176aa6ea1938b66a53889669bbf3c0a0f5525e56d7f0afd0e8c9c2c33c44
+  data.tar.gz: 22e5a7d6ff926e04baa3e0de58d7cea8d4993356a3ac931de745dbc8e817298b99b2ff591b4e353e1adc9052dd44307fce4cd957605fcd5527c448e83e8d40f4

data/CHANGELOG.md

@@ -6,7 +6,36 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Fixed
+- `lingo sync` no longer destroys hand-edit protection: it now only refreshes
+  each entry's `source_hash` and preserves `target_hash` and `manual: true`
+  (the pre-extraction `bin/translate` behavior). Previously a single sync wiped
+  both fields for every key, blinding the `manual_edits` validator and causing
+  `manual` flags to flip back and forth across branches.
+- `translate --force-key` on a `manual`-flagged key keeps the flag. The value is
+  still retranslated on explicit request, but no command removes `manual: true`
+  anymore — unprotecting a key requires editing the state JSON by hand.
+- State files whose content is unchanged are no longer rewritten, so operations
+  never touch `.i18n-state/` files for unrelated namespaces.
+
+### Changed
+- Unscoped `lingo accept-edits` now accepts only the keys the `manual_edits`
+  validator flags (actually hand-edited), instead of stamping `manual: true` on
+  every key of the locale. Use the new `--key KEY` (repeatable) for surgical
+  accepts, or `--all` for the old blanket behavior (initial adoption).
+- Validator suggestions are scoped and safe to follow verbatim: `manual_edit`
+  violations suggest `accept-edits --locale <l> --key <key>`, and `outdated`
+  violations on manual keys tell you to update the value by hand and re-accept
+  it rather than force-translating over curated text.
+
 ### Added
+- `Locallingo.configure { |c| c.anthropic_api_key = ... }` — gem-level provider
+  credentials as Strings or lazy callables, for apps whose keys don't live in
+  ENV (Rails credentials, app config objects, vaults). Precedence:
+  `Locallingo.configure` → host `RubyLLM.configure` → ENV.
+- `.locallingo.rb` setup file: the CLI loads it from the project root before
+  dispatch, so standalone `lingo` runs can configure credentials without
+  booting Rails.
 - Initial extraction from the `bin/translate` toolchain into a standalone gem.
 - `lingo` CLI with subcommands: `status`, `translate`, `validate`, `quality`,
   `fix-quality`, `accept-edits`, `hash`, `sync`. Legacy `--flag` forms still work

data/README.md

@@ -32,8 +32,21 @@ group :development do
 end
 ```
 
-RubyLLM reads provider credentials from ENV (e.g. `OPENAI_API_KEY`,
-`ANTHROPIC_API_KEY`). Locallingo never stores keys.
+Provider credentials come from ENV (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)
+or from Ruby, for apps whose keys live elsewhere (Rails credentials, an app
+config object, a vault):
+
+```ruby
+Locallingo.configure do |config|
+  config.anthropic_api_key = "sk-ant-..."            # a String…
+  config.openai_api_key = -> { AppConf.openai_key }  # …or a lazy callable
+end
+```
+
+Put that in a `.locallingo.rb` file next to `.locallingo.yml` and the `lingo`
+CLI loads it on start — no Rails boot required. A key set via
+`Locallingo.configure` wins over one set through `RubyLLM.configure`, which
+wins over ENV. Locallingo never stores keys itself.
 
 ## Configuration
 
@@ -91,8 +104,10 @@ 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 fix-quality --locale en      # auto-fix fixable issues
-lingo accept-edits --locale de     # mark current translations as intentional
-lingo sync                         # rebuild drift state from current files
+lingo accept-edits --locale de     # protect hand-edited translations (drifted keys only)
+lingo accept-edits --key a.b.c     # protect a specific key
+lingo accept-edits --all           # protect everything (initial adoption)
+lingo sync                         # refresh drift state (preserves manual flags)
 lingo hash                         # source-translation fingerprint
 ```
 

data/lib/locallingo/cli.rb

@@ -16,6 +16,11 @@ module Locallingo
   class CLI
     CLI_NAME = "lingo"
 
+    # Optional Ruby setup file loaded before dispatch — the hook for apps to
+    # configure credentials (via Locallingo.configure or RubyLLM.configure)
+    # without booting Rails.
+    SETUP_FILENAME = ".locallingo.rb"
+
     # subcommand => the legacy flag it replaces
     COMMANDS = {
       "status" => "--status",
@@ -52,6 +57,7 @@ module Locallingo
     def run
       command = resolve_command
       options = parse_options!
+      load_setup_file
       config = Locallingo.configuration(root_path: Dir.pwd, package: options[:package])
       dispatch(command, config, options)
     rescue Locallingo::Error => e
@@ -61,6 +67,13 @@ module Locallingo
 
     private
 
+    # An absent file is fine; errors in the file propagate loudly. `load` (not
+    # require) so repeated in-process invocations re-execute it.
+    def load_setup_file
+      path = File.join(Dir.pwd, SETUP_FILENAME)
+      load path if File.file?(path)
+    end
+
     # Determine the subcommand, translating a leading legacy flag (with a
     # deprecation notice) and defaulting to `status`.
     def resolve_command
@@ -96,6 +109,10 @@ module Locallingo
         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|
+          (@options[:keys] ||= []) << v
+        end
+        opts.on("--all", "accept-edits: mark every translated key as manual") { @options[:all] = true }
         opts.on("-v", "--verbose", "Verbose output") { @options[:verbose] = true }
         opts.on("-n", "--dry-run", "Show what would be done without changing files") { @options[:dry_run] = true }
         opts.on("--strict", "Fail on strict-tier issues (for CI)") { @options[:strict] = true }
@@ -172,11 +189,25 @@ module Locallingo
         warn "manual_edits validator is disabled in .locallingo.yml — nothing to accept."
         return
       end
-      manager(config, options).accept_edits!(locale: options[:locale])
-      puts "✅ Marked current translations as intentional."
+
+      results = manager(config, options).accept_edits!(
+        locale: options[:locale], keys: options[:keys] || [], all: options.fetch(:all, false)
+      )
+      report_accepted(results)
       puts "(dry run - no changes made)" if options[:dry_run]
     end
 
+    def report_accepted(results)
+      total = results.values.sum(&:size)
+      if total.zero?
+        puts "Nothing to accept — no hand-edited translations found."
+        return
+      end
+
+      results.each { |locale, keys| puts "  #{locale}: #{keys.size} key(s)" if keys.any? }
+      puts "✅ Marked #{total} translation(s) as intentional."
+    end
+
     def cmd_hash(config, options)
       hash = manager(config, options).source_hash
       options[:format] == :json ? puts(JSON.generate({ hash: })) : puts(hash)

data/lib/locallingo/manager.rb

@@ -97,27 +97,35 @@ module Locallingo
       locales_to_process.each { |target_locale| translate_locale(source, target_locale, force:, force_keys:) }
     end
 
-    # Mark every current target value as intentional (source_hash + target_hash +
-    # manual flag) so the manual-edits validator stops flagging it.
-    def accept_edits!(locale: nil)
+    # Mark hand-edited target values as intentional (source_hash + target_hash +
+    # manual flag) so the manual-edits validator stops flagging them and
+    # translate won't overwrite them. Unscoped, it accepts exactly the keys the
+    # manual-edits validator flags; `keys:` accepts the named keys regardless of
+    # drift; `all: true` marks every translated key (initial adoption). Returns
+    # `{ locale => accepted_keys }`.
+    def accept_edits!(locale: nil, keys: [], all: false)
       source = load_source_translations
       locales = locale ? [locale] : config.target_locales
 
-      locales.each do |target_locale|
+      plans = locales.map do |target_locale|
         target = load_locale_translations(target_locale)
         locale_state = @state.load(target_locale)
+        accepted = keys_to_accept(source, target, locale_state, keys:, all:)
+        [target_locale, target, locale_state, accepted]
+      end
 
-        target.each do |key, value|
-          next unless source[key]
+      ensure_keys_matched!(keys, plans)
 
+      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(value),
+            "target_hash" => @state.hash(target[key]),
             "manual" => true
           }
         end
-
         @state.save(target_locale, locale_state) unless dry_run
+        results[target_locale] = accepted
       end
     end
 
@@ -126,8 +134,11 @@ module Locallingo
       format("%08x", Zlib.crc32(load_source_translations.to_json))
     end
 
-    # Rewrite state from the current translation files (initial setup / after
-    # manual edits). Returns the combined state.
+    # Refresh source hashes from the current translation files and prune state
+    # for keys that no longer exist. Existing `target_hash`/`manual` fields are
+    # preserved — hand-edit protection is never dropped by a sync; use
+    # `accept_edits!` to resolve hand-edit drift explicitly. Returns the
+    # combined state.
     def sync_state!
       source = load_source_translations
 
@@ -136,18 +147,7 @@ module Locallingo
       en_state.each_key { |key| en_state.delete(key) unless source.key?(key) }
       @state.save(config.source_locale, en_state) unless dry_run
 
-      config.target_locales.each do |locale|
-        target = load_locale_translations(locale)
-        locale_state = @state.load(locale)
-
-        target.each_key do |key|
-          next unless source[key]
-
-          locale_state[key] = { "source_hash" => @state.hash(source[key]) }
-        end
-        locale_state.each_key { |key| locale_state.delete(key) unless target.key?(key) }
-        @state.save(locale, locale_state) unless dry_run
-      end
+      config.target_locales.each { |locale| sync_locale_state(source, locale) }
 
       combined = { config.source_locale => @state.load(config.source_locale) }
       config.target_locales.each { |locale| combined[locale] = @state.load(locale) }
@@ -167,6 +167,44 @@ module Locallingo
     def missing_validator = @missing_validator ||= Validators::Missing.new(cli_name:)
     def outdated_validator = @outdated_validator ||= Validators::Outdated.new(cli_name:)
 
+    def sync_locale_state(source, locale)
+      target = load_locale_translations(locale)
+      locale_state = @state.load(locale)
+
+      target.each_key do |key|
+        next unless source[key]
+
+        existing = locale_state[key]
+        entry = existing.is_a?(Hash) ? existing.dup : {}
+        entry["source_hash"] = @state.hash(source[key])
+        locale_state[key] = entry
+      end
+      locale_state.each_key { |key| locale_state.delete(key) unless target.key?(key) }
+      @state.save(locale, locale_state) unless dry_run
+    end
+
+    def keys_to_accept(source, target, locale_state, keys:, all:)
+      return keys.select { |key| source.key?(key) && target.key?(key) } if keys.any?
+      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])
+      end
+    end
+
+    def ensure_keys_matched!(keys, plans)
+      return if keys.empty?
+
+      matched = plans.flat_map { |_, _, _, accepted| accepted }
+      missing = keys - matched
+      return if missing.empty?
+
+      raise Error, "accept-edits: key(s) not found in any target locale: #{missing.join(", ")}"
+    end
+
     def translate_locale(source, target_locale, force:, force_keys:)
       log("Processing #{target_locale}...")
 
@@ -301,10 +339,15 @@ module Locallingo
       translations.each_key do |key|
         next unless source[key]
 
-        locale_state[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
       end
     end
 

data/lib/locallingo/providers/ruby_llm.rb

@@ -31,14 +31,14 @@ module Locallingo
         @provider = provider.to_sym
       end
 
-      # True when credentials for the configured provider are present in ENV.
-      # Unknown providers are assumed configured (RubyLLM may source the key
-      # elsewhere) rather than blocking.
+      # True when a key for the configured provider is found in any source
+      # (Locallingo settings, host RubyLLM config, ENV). Unknown providers are
+      # assumed configured (RubyLLM may source the key elsewhere) rather than
+      # blocking.
       def credentials?
-        env = CREDENTIAL_ENV[provider]
-        return true unless env
+        return true unless CREDENTIAL_ENV.key?(provider)
 
-        !ENV.fetch(env, "").to_s.strip.empty?
+        !resolved_api_key.nil?
       end
 
       # Raise a precise error when the provider has no credentials.
@@ -46,8 +46,10 @@ module Locallingo
         return if credentials?
 
         raise MissingCredentialsError,
-              "No credentials for provider #{provider.inspect} " \
-              "(expected #{CREDENTIAL_ENV[provider]} in ENV)"
+              "No credentials for provider #{provider.inspect}. " \
+              "Set #{CREDENTIAL_ENV[provider]} in ENV, call " \
+              "Locallingo.configure { |c| c.#{provider}_api_key = ... }, or add a " \
+              ".locallingo.rb setup file at the project root (loaded by the CLI)."
       end
 
       # Send +instructions+ (system prompt) + +payload+ (user message, JSON) to
@@ -70,20 +72,55 @@ module Locallingo
 
       # 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>". Fill the
-      # provider's key from ENV — unless the host app already configured
-      # one, which always wins.
+      # would raise "Missing configuration for <provider>". Push the resolved
+      # key into RubyLLM's config: an explicit `Locallingo.configure` key wins
+      # (re-resolved every chat so callables stay live), then a key the host
+      # app already set, then the ENV fallback.
       def configure_credentials!
-        env = CREDENTIAL_ENV[provider]
-        return unless env
+        return unless CREDENTIAL_ENV.key?(provider)
 
-        setting = "#{provider}_api_key"
         config = ::RubyLLM.config
+        setting = key_setting
         return unless config.respond_to?(setting) && config.respond_to?("#{setting}=")
-        return unless config.public_send(setting).to_s.strip.empty?
 
-        key = ENV.fetch(env, "")
-        config.public_send("#{setting}=", key) unless key.strip.empty?
+        key = settings_api_key
+        return if key.nil? && !presence(config.public_send(setting)).nil?
+
+        key ||= env_api_key
+        config.public_send("#{setting}=", key) unless key.nil?
+      end
+
+      # Key resolution across sources, in precedence order. Used by
+      # #credentials? as a fail-fast check before any network call.
+      def resolved_api_key
+        settings_api_key || host_configured_api_key || env_api_key
+      end
+
+      def settings_api_key
+        Locallingo.settings.api_key_for(provider)
+      end
+
+      # A key the host app set via RubyLLM.configure — only inspected when
+      # ruby_llm is already loaded (we never require it just to peek).
+      def host_configured_api_key
+        return nil unless defined?(::RubyLLM)
+
+        config = ::RubyLLM.config
+        return nil unless config.respond_to?(key_setting)
+
+        presence(config.public_send(key_setting))
+      end
+
+      def env_api_key
+        env = CREDENTIAL_ENV[provider]
+        env ? presence(ENV.fetch(env, "")) : nil
+      end
+
+      def key_setting = "#{provider}_api_key"
+
+      def presence(value)
+        key = value.to_s.strip
+        key.empty? ? nil : key
       end
     end
   end

data/lib/locallingo/settings.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Locallingo
+  # Code-level gem settings, configured via `Locallingo.configure`. Distinct
+  # from Locallingo::Configuration, which loads the `.locallingo.yml` project
+  # file — Settings holds what must never live in YAML: provider credentials.
+  #
+  #   Locallingo.configure do |config|
+  #     config.anthropic_api_key = ENV.fetch("MY_KEY")          # a String…
+  #     config.openai_api_key = -> { Vault.read("openai_key") } # …or a callable
+  #   end
+  #
+  # Callables are resolved lazily on every use (never memoized), so keys can
+  # come from sources that aren't ready at configure time or that rotate.
+  class Settings
+    PROVIDERS = %i[openai anthropic gemini deepseek openrouter].freeze
+
+    attr_accessor(*PROVIDERS.map { |name| :"#{name}_api_key" })
+
+    # The usable key for +provider+: callables are called, results stripped,
+    # and blank or unknown-provider values come back as nil.
+    def api_key_for(provider)
+      return nil unless PROVIDERS.include?(provider.to_sym)
+
+      value = public_send("#{provider}_api_key")
+      value = value.call if value.respond_to?(:call)
+      key = value.to_s.strip
+      key.empty? ? nil : key
+    end
+  end
+end

data/lib/locallingo/state_store.rb

@@ -40,8 +40,9 @@ module Locallingo
             "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.
+    # Save a locale's state, split back into per-namespace files. Files whose
+    # content is unchanged are left untouched so unrelated namespaces never
+    # churn in diffs. 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
@@ -50,7 +51,10 @@ module Locallingo
 
       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))
+        content = JSON.pretty_generate(keys.sort.to_h)
+        next if File.exist?(state_file) && File.read(state_file) == content
+
+        File.write(state_file, content)
       end
 
       Dir.glob(File.join(state_dir, "*.#{locale}.json")).each do |file|

data/lib/locallingo/validators/manual_edits.rb

@@ -30,7 +30,7 @@ module Locallingo
             type: :manual_edit,
             locale:,
             key:,
-            suggestion: "Value was hand-edited. Protect it: #{@cli_name} accept-edits --locale #{locale}"
+            suggestion: "Value was hand-edited. Protect it: #{@cli_name} accept-edits --locale #{locale} --key #{key}"
           }
         end
       end

data/lib/locallingo/validators/outdated.rb

@@ -19,7 +19,7 @@ module Locallingo
             type: :outdated,
             locale:,
             key:,
-            suggestion: "Source changed. Run: #{@cli_name} translate --locale #{locale} --force-key #{key}"
+            suggestion: suggestion_for(key, locale, locale_state)
           }
         end
       end
@@ -31,6 +31,19 @@ module Locallingo
           key if stored && stored != StateStore.hash(value)
         end
       end
+
+      private
+
+      # Manual keys must not be pushed toward machine retranslation — the value
+      # is hand-curated, so the human updates it and re-accepts.
+      def suggestion_for(key, locale, locale_state)
+        if locale_state.dig(key, "manual")
+          "Source changed for a manually-curated key. Update the #{locale} value by hand, " \
+            "then run: #{@cli_name} accept-edits --locale #{locale} --key #{key}"
+        else
+          "Source changed. Run: #{@cli_name} translate --locale #{locale} --force-key #{key}"
+        end
+      end
     end
   end
 end

data/lib/locallingo/version.rb

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

data/lib/locallingo.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "locallingo/version"
+require_relative "locallingo/settings"
 require_relative "locallingo/configuration"
 require_relative "locallingo/json_extraction"
 require_relative "locallingo/key_flattener"
@@ -35,4 +36,21 @@ module Locallingo
   def self.configuration(root_path: Dir.pwd, package: nil)
     Configuration.load(root_path:, package:)
   end
+
+  # Code-level settings (provider credentials) — see Locallingo::Settings.
+  def self.settings
+    @settings ||= Settings.new
+  end
+
+  # Configure the gem from Ruby — the credentials path for apps whose keys
+  # don't live in ENV (call it from a Rails initializer or a `.locallingo.rb`
+  # setup file next to `.locallingo.yml`; the CLI loads the latter on start).
+  def self.configure
+    yield settings
+    settings
+  end
+
+  def self.reset_settings!
+    @settings = nil
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: locallingo
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -81,6 +81,7 @@ files:
 - lib/locallingo/quality_checker.rb
 - lib/locallingo/reporter.rb
 - lib/locallingo/rubocop.rb
+- lib/locallingo/settings.rb
 - lib/locallingo/state_store.rb
 - lib/locallingo/validators/duplicate_values.rb
 - lib/locallingo/validators/manual_edits.rb