locallingo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45dfcfd181bb7d72fe62baef770bcf9b29f326ea60d851648d509e75e0bdf173
+  data.tar.gz: 228bdd7709806269301923738579ee9c21d564e27eb9d267dc1fa6f1cd560fa2
+SHA512:
+  metadata.gz: c396ffa2b39f45696f201082209ff1c2f3909598935b40adbd89141fd959839b9b1ce73806f1731ced0fa032caff64d66e4bcfa3ad36e190d95fcfb5dfe6c2c6
+  data.tar.gz: 2271440aa37c981b11d88415cf020c7d69627e9279bf59b2628f2cd0b415042ad2b514c1ba31bc1d7c146106cdb852e939034018b4352797db7fc9615d76dccf

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- 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
+  and print a deprecation notice.
+- `Locallingo::Configuration` — `.locallingo.yml` with a `defaults:` block plus
+  optional per-`packages:` overrides (deep-merged, ERB-evaluated).
+- Provider-agnostic translation via RubyLLM (`provider:`/`model:` config).
+- Validators (config-gated): `missing`, `outdated`, `duplicate_values`,
+  `manual_edits`.
+- Quality checks: static rules, universal fixes, configurable terminology lists
+  (`business`/`banking`/custom), optional British-spelling drift, plus an
+  optional AI review pass.
+- Source-hash drift detection with per-namespace state files under `.i18n-state/`.
+- Configurable `after_translate` hook commands (e.g. `i18n-tasks normalize -p`,
+  `rails i18n:export`).
+- RuboCop cops `Locallingo/RelativeI18nKey` (with autocorrect) and
+  `Locallingo/StrftimeInView`, loaded via `require: locallingo/rubocop`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mikael Henriksson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# Locallingo
+
+AI-assisted i18n translation, drift detection, and quality linting on top of
+[i18n-tasks](https://github.com/glebm/i18n-tasks) — packaged as a gem so the same
+toolchain works across every app instead of being copy-pasted (and forking) per
+repo.
+
+Locallingo:
+
+- **Translates** missing/changed keys through [RubyLLM](https://github.com/crmne/ruby_llm)
+  (OpenAI, Anthropic, Google, … — you pick the provider/model).
+- **Detects drift** with per-key source hashes, so only genuinely
+  missing/outdated keys are re-translated.
+- **Validates** translation completeness for CI (missing, outdated, and optional
+  duplicate-value / manual-edit checks).
+- **Lints quality** — static rules, terminology lists, optional British-spelling
+  drift, plus an optional AI review.
+- Ships **RuboCop cops** that enforce fully-qualified i18n keys and locale-aware
+  date formatting.
+
+Everything app-specific lives in `.locallingo.yml` — target locales, provider and
+model, prompt context/glossary, per-language style guides, which validators and
+quality rules run, and post-translate hooks — with a default block plus optional
+per-package overrides.
+
+## Installation
+
+```ruby
+# Gemfile
+group :development do
+  gem "locallingo"
+end
+```
+
+RubyLLM reads provider credentials from ENV (e.g. `OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`). Locallingo never stores keys.
+
+## Configuration
+
+Create `.locallingo.yml` at your app root:
+
+```yaml
+defaults:
+  source_locale: en
+  target_locales: [de, sv]
+
+  provider: openai            # any RubyLLM provider
+  translate:
+    model: gpt-5-mini
+  quality:
+    model: gpt-4o-mini
+    terminology: business     # "business" | "banking" | path/to/terms.yml
+    british_spellings: false
+
+  context: "Cosmos, a business application"
+  glossary:
+    entity: "business/company account holder"
+    member: "user belonging to an entity"
+  language_guides:
+    de: config/locales/.guides/de.md   # inline text or `file:` path
+
+  validators:
+    missing: true
+    outdated: true
+    duplicate_values: true    # flags non-AR keys duplicating an AR attribute value
+    manual_edits: false       # protects hand-edited target values
+
+  strict:
+    strict:     [missing, outdated]
+    strict_all: [missing, outdated, duplicate_value]
+
+  after_translate:
+    - "bundle exec i18n-tasks normalize -p"
+
+# Optional per-location overrides (each inherits `defaults`):
+packages: []
+#  - path: engines/billing
+#    context: "the billing engine"
+#    target_locales: [de]
+```
+
+With no `packages:`, the whole app uses `defaults` — the common case.
+
+## CLI
+
+```bash
+lingo status                       # translation status per locale
+lingo translate --locale de        # translate missing/changed keys
+lingo translate --force            # re-translate everything
+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 hash                         # source-translation fingerprint
+```
+
+Add `--package engines/billing` to any command to scope it to a package.
+
+The legacy flag forms (`lingo --translate`, `lingo --validate`, …) still work and
+print a one-line deprecation notice, so you can migrate CI and docs incrementally.
+
+## RuboCop cops
+
+```yaml
+# .rubocop.yml
+require:
+  - locallingo/rubocop
+inherit_gem:
+  locallingo: config/default.yml
+```
+
+- **`Locallingo/RelativeI18nKey`** — flags relative `t(".key")` lookups and
+  autocorrects them to fully-qualified keys derived from the file path and
+  enclosing method. Configure `ScopedDirectories` for your layout.
+- **`Locallingo/StrftimeInView`** — flags `.strftime(...)` in views; use
+  `I18n.l(value, format: :name)` instead. `value:`-pair inputs (HTML datetime)
+  are exempt.
+
+Locallingo recommends disabling Rails' `Rails/I18nLazyLookup` and
+`Rails/I18nLocaleTexts`, which fight the fully-qualified-key convention.
+
+## Programmatic use
+
+```ruby
+config = Locallingo.configuration(root_path: Dir.pwd)
+Locallingo::Manager.new(config:).validate           # => [violations]
+Locallingo::QualityChecker.new(config:).check(locale: "en")
+```
+
+## License
+
+MIT © Mikael Henriksson

data/config/default.yml

@@ -0,0 +1,47 @@
+# Locallingo's RuboCop cop defaults.
+#
+# In a host app's .rubocop.yml:
+#
+#   require:
+#     - locallingo/rubocop
+#   inherit_gem:
+#     locallingo: config/default.yml
+#
+# Then override Include/Exclude/ScopedDirectories as needed. Locallingo also
+# recommends disabling Rails' relative-key cops, which fight the fully-qualified
+# convention this cop enforces (uncomment in your app):
+#
+#   Rails/I18nLazyLookup: { Enabled: false }
+#   Rails/I18nLocaleTexts: { Enabled: false }
+
+Locallingo/RelativeI18nKey:
+  Description: "Use fully-qualified i18n keys instead of relative `t('.key')` keys."
+  Enabled: true
+  # Directories under app/ whose path maps to a lazy-lookup scope for autocorrect.
+  ScopedDirectories:
+    - controllers
+    - mailers
+    - views
+    - components
+    - models
+    - services
+    - jobs
+    - notifiers
+  Include:
+    - "app/components/**/*.rb"
+    - "app/views/**/*.rb"
+    - "app/controllers/**/*.rb"
+    - "app/mailers/**/*.rb"
+    - "app/models/**/*.rb"
+    - "app/services/**/*.rb"
+    - "app/jobs/**/*.rb"
+    - "app/notifiers/**/*.rb"
+
+Locallingo/StrftimeInView:
+  Description: "Use `I18n.l(value, format: :name)` instead of `.strftime` in views."
+  Enabled: true
+  Include:
+    - "app/views/**/*.rb"
+  Exclude:
+    # Mailer views format dates for email, not locale-specific display.
+    - "app/views/**/*_mailer/**/*.rb"

data/config/locallingo.default.yml

@@ -0,0 +1,70 @@
+# Locallingo configuration.
+#
+# Copy this to `.locallingo.yml` at your app root and edit. Everything under
+# `defaults:` applies to the whole app. Add `packages:` entries to override the
+# defaults for a sub-directory (engine, gem, package) — each package inherits
+# `defaults` and overrides only the keys it lists.
+#
+# The file is ERB-evaluated, so `<%= ENV["SOMETHING"] %>` works. NEVER put raw
+# API keys here — the LLM provider reads its own credentials from ENV via RubyLLM.
+
+defaults:
+  # The locale translations are authored in and translated FROM.
+  source_locale: en
+  # Locales translated TO (from the source). These are the ones Locallingo fills.
+  target_locales: [de, sv]
+
+  # Where the flat `<namespace>.<locale>.yml` files live, and where the
+  # source-hash drift state is tracked. Relative to the app root (or package path).
+  locales_dir: config/locales
+  state_dir: .i18n-state
+
+  # RubyLLM provider symbol (openai, anthropic, gemini, ...). Credentials come
+  # from ENV per RubyLLM's own config (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY).
+  provider: openai
+
+  translate:
+    model: gpt-5-mini
+    batch_size: 20
+
+  quality:
+    model: gpt-4o-mini
+    # Flag en-only British-vs-American spelling drift (organization -> organisation).
+    british_spellings: false
+    # Named built-in terminology list ("business" | "banking" | "none"), or a
+    # path to a YAML file mapping term -> suggestion (nil = term is acceptable).
+    terminology: business
+
+  # Prompt scaffolding. `context` names your product; `glossary` pins domain terms
+  # the model must not paraphrase; `placeholder_style` documents your interpolation
+  # syntax so the model preserves it.
+  context: "a business application"
+  placeholder_style: "%<name>s, %<count>s"
+  glossary: {}
+  # Extra per-locale style guidance appended to the translation prompt. Value is
+  # inline text or `file: path/to/guide.md`.
+  language_guides: {}
+
+  # Which validators `validate` runs.
+  validators:
+    missing: true
+    outdated: true
+    duplicate_values: false   # flags non-activerecord keys duplicating an AR attribute value
+    manual_edits: false       # protects hand-edited target values from being overwritten
+
+  # What each strict tier fails CI on. `validate --strict` uses `strict`;
+  # `validate --strict-all` uses `strict_all`.
+  strict:
+    strict: [missing, outdated]
+    strict_all: [missing, outdated, duplicate_value]
+
+  # Commands run (in order) after a successful `translate`, from the app root.
+  after_translate:
+    - "bundle exec i18n-tasks normalize -p"
+
+# Optional per-location overrides. Empty means "single default config" (the
+# common case). Each entry deep-merges onto `defaults`.
+packages: []
+#  - path: engines/billing
+#    context: "the billing engine"
+#    target_locales: [de]

data/exe/lingo

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "locallingo"
+
+Locallingo::CLI.start(ARGV)

data/lib/locallingo/cli.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "configuration"
+require_relative "manager"
+require_relative "quality_checker"
+require_relative "reporter"
+
+module Locallingo
+  # The `lingo` command-line interface.
+  #
+  # Canonical form is subcommands (`lingo translate`, `lingo validate`, ...).
+  # The legacy flag form (`lingo --translate`) still works but prints a
+  # deprecation notice, so callers can migrate incrementally.
+  class CLI
+    CLI_NAME = "lingo"
+
+    # subcommand => the legacy flag it replaces
+    COMMANDS = {
+      "status" => "--status",
+      "translate" => "--translate",
+      "validate" => "--validate",
+      "quality" => "--check-quality",
+      "fix-quality" => "--fix-quality",
+      "accept-edits" => "--accept-edits",
+      "hash" => "--hash",
+      "sync" => "--sync-state"
+    }.freeze
+
+    # legacy flag => subcommand (for the deprecation path)
+    LEGACY_FLAGS = {
+      "--status" => "status",
+      "--translate" => "translate",
+      "--validate" => "validate",
+      "--check-quality" => "quality",
+      "--fix-quality" => "fix-quality",
+      "--accept-edits" => "accept-edits",
+      "--hash" => "hash",
+      "--sync-state" => "sync"
+    }.freeze
+
+    def self.start(argv = ARGV)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+      @options = { format: :text }
+    end
+
+    def run
+      command = resolve_command
+      options = parse_options!
+      config = Locallingo.configuration(root_path: Dir.pwd, package: options[:package])
+      dispatch(command, config, options)
+    rescue Locallingo::Error => e
+      warn "❌ #{e.message}"
+      exit 1
+    end
+
+    private
+
+    # Determine the subcommand, translating a leading legacy flag (with a
+    # deprecation notice) and defaulting to `status`.
+    def resolve_command
+      first = @argv.first
+      return "status" if first.nil?
+
+      if LEGACY_FLAGS.key?(first)
+        @argv.shift
+        subcommand = LEGACY_FLAGS[first]
+        warn "[deprecated] `#{first}` — use `#{CLI_NAME} #{subcommand}` instead."
+        return subcommand
+      end
+
+      # A leading non-flag token is the subcommand.
+      return @argv.shift unless first.start_with?("-")
+
+      "status"
+    end
+
+    def parse_options!
+      parser = build_parser
+      parser.parse!(@argv)
+      @options
+    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("-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 }
+        opts.on("--strict-all", "Fail on strict-all-tier issues (for full CI)") do
+          @options[:strict] = true
+          @options[:strict_all] = true
+        end
+        opts.on("--ai", "Use AI for quality suggestions") { @options[:use_ai] = true }
+        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
+          puts opts
+          exit 0
+        end
+      end
+    end
+
+    def dispatch(command, config, options)
+      reporter = Reporter.new(config:, format: options[:format], cli_name: CLI_NAME)
+
+      case command
+      when "status" then cmd_status(config, options, reporter)
+      when "translate" then cmd_translate(config, options)
+      when "validate" then cmd_validate(config, options, reporter)
+      when "quality" then cmd_quality(config, options, reporter)
+      when "fix-quality" then cmd_fix_quality(config, options)
+      when "accept-edits" then cmd_accept_edits(config, options)
+      when "hash" then cmd_hash(config, options)
+      when "sync" then cmd_sync(config, options)
+      else
+        warn "Unknown command: #{command}\nRun `#{CLI_NAME} --help`."
+        exit 1
+      end
+    end
+
+    def cmd_status(config, options, reporter)
+      reporter.status(manager(config, options).status)
+    end
+
+    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] || [])
+      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]
+    end
+
+    def cmd_validate(config, options, reporter)
+      violations = manager(config, options).validate
+      exit(reporter.violations(violations, strict: options[:strict], strict_all: options[:strict_all]))
+    end
+
+    def cmd_quality(config, options, reporter)
+      locale = options[:locale] || config.source_locale
+      suggestions = quality_checker(config, options).check(locale:, use_ai: options[:use_ai])
+      reporter.quality(suggestions, locale:)
+    end
+
+    def cmd_fix_quality(config, options)
+      locale = options[:locale] || config.source_locale
+      puts(options[:dry_run] ? "🔍 Checking fixes for #{locale}..." : "🔧 Fixing quality issues for #{locale}...")
+      result = quality_checker(config, options).fix!(locale:, dry_run: options[:dry_run])
+      puts "\nFixed: #{result[:fixed]} files"
+      puts "Skipped: #{result[:skipped]} non-fixable suggestions"
+      puts "(dry run - no changes made)" if options[:dry_run]
+    end
+
+    def cmd_accept_edits(config, options)
+      unless config.validator_enabled?(:manual_edits)
+        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."
+      puts "(dry run - no changes made)" if options[:dry_run]
+    end
+
+    def cmd_hash(config, options)
+      hash = manager(config, options).source_hash
+      options[:format] == :json ? puts(JSON.generate({ hash: })) : puts(hash)
+    end
+
+    def cmd_sync(config, options)
+      mgr = manager(config, options)
+      puts(options[:dry_run] ? "🔍 Would sync state file..." : "🔄 Syncing state file with current translations...")
+      state = mgr.sync_state!
+      total = state.values.sum { |locale_state| locale_state.keys.size }
+      puts "\nState directory: #{config.state_dir}"
+      state.each { |locale, locale_state| puts "  #{locale}: #{locale_state.keys.size} keys" }
+      puts "Total tracked keys: #{total}"
+      puts "(dry run - no changes made)" if options[:dry_run]
+    end
+
+    def manager(config, options)
+      Manager.new(config:, dry_run: options[:dry_run], verbose: options[:verbose], cli_name: CLI_NAME)
+    end
+
+    def quality_checker(config, options)
+      QualityChecker.new(config:, verbose: options[:verbose])
+    end
+  end
+end

data/lib/locallingo/configuration.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+
+module Locallingo
+  # Loads and resolves `.locallingo.yml`.
+  #
+  # The file has a `defaults:` block that applies to the whole app, plus an
+  # optional `packages:` list. Each package entry deep-merges onto `defaults`,
+  # so a package only lists the keys it changes. With no `packages:` (the common
+  # case), the resolved config is just `defaults` merged over the shipped
+  # `config/locallingo.default.yml`.
+  #
+  # Typed readers expose everything the Manager/QualityChecker/CLI need, so no
+  # other class parses raw config hashes.
+  class Configuration
+    CONFIG_FILENAMES = %w[.locallingo.yml .locallingo.yaml].freeze
+    DEFAULT_CONFIG_PATH = File.expand_path("../../config/locallingo.default.yml", __dir__)
+
+    attr_reader :root_path, :package, :data
+
+    # Resolve config for +root_path+, optionally scoped to a +package+ path from
+    # the `packages:` list.
+    def self.load(root_path: Dir.pwd, package: nil)
+      new(root_path:, package:)
+    end
+
+    def initialize(root_path: Dir.pwd, package: nil, data: nil)
+      @root_path = File.expand_path(root_path)
+      @package = package
+      @data = data || resolve
+    end
+
+    # --- locations -----------------------------------------------------------
+
+    # The directory config paths resolve against — the package path when scoped,
+    # else the app root.
+    def base_path
+      package ? File.join(root_path, package) : root_path
+    end
+
+    def source_locale = data.fetch("source_locale")
+    def target_locales = Array(data.fetch("target_locales"))
+    def all_locales = [source_locale, *target_locales].uniq
+
+    def locales_dir = File.join(base_path, data.fetch("locales_dir"))
+    def state_dir = File.join(base_path, data.fetch("state_dir"))
+    def exceptions_dir = File.join(state_dir, "exceptions")
+    def log_file = File.join(state_dir, "translation.log")
+
+    # --- provider / models ---------------------------------------------------
+
+    def provider = data.fetch("provider").to_sym
+    def translate_model = dig("translate", "model")
+    def batch_size = dig("translate", "batch_size")
+    def quality_model = dig("quality", "model")
+    def british_spellings? = !!dig("quality", "british_spellings")
+    def terminology_setting = dig("quality", "terminology")
+
+    # --- prompt scaffolding --------------------------------------------------
+
+    def context = data.fetch("context", "a business application")
+    def placeholder_style = data.fetch("placeholder_style", "%<name>s, %<count>s")
+    def glossary = data.fetch("glossary", {}) || {}
+
+    # Extra per-locale style text appended to the translation prompt. A value of
+    # `{ "file" => path }` is read from disk (relative to base_path); a String is
+    # used verbatim. Returns "" when none is configured.
+    def language_guide(locale)
+      guide = (data.fetch("language_guides", {}) || {})[locale.to_s]
+      return "" if guide.nil?
+      return guide.to_s unless guide.is_a?(Hash) && guide["file"]
+
+      path = File.expand_path(guide["file"], base_path)
+      File.exist?(path) ? File.read(path) : ""
+    end
+
+    # Human-readable language name for a locale, from the guide config or a small
+    # built-in map, falling back to the locale code itself.
+    def language_name(locale)
+      BUILTIN_LANGUAGE_NAMES[locale.to_s] || locale.to_s
+    end
+
+    # --- validators / strictness ---------------------------------------------
+
+    def validator_enabled?(name)
+      !!dig("validators", name.to_s)
+    end
+
+    # Violation types (symbols) a strict tier fails on. +tier+ is :strict or
+    # :strict_all.
+    def strict_types(tier)
+      Array(dig("strict", tier.to_s)).map(&:to_sym)
+    end
+
+    # --- hooks ---------------------------------------------------------------
+
+    def after_translate = Array(data.fetch("after_translate", []))
+
+    BUILTIN_LANGUAGE_NAMES = {
+      "de" => "German", "sv" => "Swedish", "fr" => "French",
+      "af" => "Afrikaans", "es" => "Spanish", "it" => "Italian",
+      "nl" => "Dutch", "pt" => "Portuguese", "da" => "Danish",
+      "nb" => "Norwegian", "no" => "Norwegian", "fi" => "Finnish"
+    }.freeze
+
+    private
+
+    def dig(*keys) = data.dig(*keys)
+
+    # Merge: shipped defaults <- user `defaults:` <- selected `packages:` entry.
+    def resolve
+      merged = deep_merge(shipped_defaults, user_defaults)
+      merged = deep_merge(merged, package_overrides) if package
+      merged
+    end
+
+    def shipped_defaults
+      load_yaml(DEFAULT_CONFIG_PATH).fetch("defaults", {})
+    end
+
+    def user_defaults
+      file = config_file
+      return {} unless file
+
+      load_yaml(file).fetch("defaults", {}) || {}
+    end
+
+    def package_overrides
+      file = config_file
+      return {} unless file
+
+      packages = load_yaml(file).fetch("packages", []) || []
+      entry = packages.find { |p| p["path"] == package }
+      raise Error, "No package #{package.inspect} in #{file}" unless entry
+
+      entry.except("path")
+    end
+
+    def config_file
+      CONFIG_FILENAMES
+        .map { |name| File.join(root_path, name) }
+        .find { |path| File.exist?(path) }
+    end
+
+    def load_yaml(path)
+      YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_key, base_val, override_val|
+        if base_val.is_a?(Hash) && override_val.is_a?(Hash)
+          deep_merge(base_val, override_val)
+        else
+          override_val
+        end
+      end
+    end
+  end
+end