translation_diff 1.0.0

data/lib/translation_diff/configuration/option_table.rb

@@ -0,0 +1,38 @@
+# The full option table: every setting Configuration exposes, its default, and what it invalidates.
+# Lives apart from Configuration itself so the class that implements the behaviour isn't measured by
+# a list that only grows -- this module is documentation as much as code, read it as a reference.
+module TranslationDiff::Configuration::OptionTable
+  # [key, default, the memoised reader(s) it invalidates -- nil means it invalidates nothing]
+  TABLE = [
+    [:provider, :deepl, :provider_instance], # rubocop:disable Style/SymbolArray -- stays [key, default, invalidates]
+    [:cache, nil, :cache_store],
+    [:cache_ttl, 604_800, :cache_store],
+    # Also the rate limiter's own namespace (RateLimiters::Redis, RateLimiters::ActiveRecord both read it).
+    [:cache_namespace, "translation-diff", %i[cache_store rate_limiter_instance]],
+    [:cache_max_size, 1_000, :cache_store],
+    [:cache_table_name, "translation_diff_translations", :cache_store],
+    [:rate_limit_table_name, "translation_diff_rate_limits", :rate_limiter_instance],
+    [:active_record_base, nil, %i[cache_store rate_limiter_instance]],
+    [:cache_prune_probability, 0.0, :cache_store],
+    [:redis_url, -> { ENV.fetch("REDIS_URL", nil) }, %i[redis_pool cache_store rate_limiter_instance]],
+    [:redis_pool_size, 5, %i[redis_pool cache_store rate_limiter_instance]],
+    [:redis_pool_timeout, 5, %i[redis_pool cache_store rate_limiter_instance]],
+    [:rate_limit, nil, :rate_limiter_instance],
+    [:rate_interval, 60, :rate_limiter_instance],
+    [:rate_limiter, nil, :rate_limiter_instance],
+    [:segmenter, :pragmatic, :segmenter_instance], # rubocop:disable Style/SymbolArray
+    [:opaque_elements, %i[script style pre code], nil],
+    [:instrumenter, nil, nil],
+    [:logger, nil, nil],
+    # HTTPProvider#connection memoises a Faraday connection built from these three, and the provider itself
+    # is memoised too, so a change here has to reach provider_instance or it never reaches the connection.
+    [:open_timeout, 5, :provider_instance],
+    [:timeout, 30, :provider_instance],
+    [:max_retries, 3, :provider_instance],
+    [:validate_languages, true, nil]
+  ].freeze
+
+  def self.declare_on(configuration_class)
+    TABLE.each { |key, default, invalidates| configuration_class.option(key, default, invalidates: invalidates) }
+  end
+end

data/lib/translation_diff/configuration/provider_option_owners.rb

@@ -0,0 +1,40 @@
+# Tracks which provider declared each option; two silently sharing one accessor would leak a credential.
+class TranslationDiff::Configuration::ProviderOptionOwners
+  def initialize
+    @owners = {}
+  end
+
+  # All-or-nothing: recording key by key would attribute earlier keys to a provider that then failed.
+  def claim(keys, provider)
+    validate!(keys, provider)
+    keys.each { |key| @owners[key] = provider }
+  end
+
+  private
+
+  def validate!(keys, provider)
+    keys.each { |key| conflict!(key, provider) unless available?(key, provider) }
+  end
+
+  def available?(key, provider)
+    owner = @owners[key]
+    owner.nil? || same_provider?(owner, provider)
+  end
+
+  # `<=>` is non-nil exactly when both sit on one inheritance chain -- also true if `provider` isn't a Module.
+  def same_provider?(owner, provider)
+    owner.equal?(provider) ||
+      (!owner.name.nil? && owner.name == provider.name) ||
+      !(provider <=> owner).nil?
+  end
+
+  def conflict!(key, provider)
+    owner = @owners[key]
+    raise TranslationDiff::Error,
+          "#{provider} declares the configuration option #{key.inspect}, which #{owner} " \
+          "already declared. Provider options share one namespace on " \
+          "TranslationDiff::Configuration: two providers declaring the same name would " \
+          "share one accessor, so a credential set for one would be handed to the other. " \
+          "Prefix the option with the provider's own name."
+  end
+end

data/lib/translation_diff/configuration.rb

@@ -0,0 +1,135 @@
+# Every declared setting in one place; callable defaults are invoked on read, not at load time.
+class TranslationDiff::Configuration
+  class << self
+    # `invalidates:` names the memoised reader(s) this option feeds; a writer clears exactly those ivars.
+    # An option that names none -- logger, instrumenter, the timeouts -- clears nothing, which is also
+    # what an option nobody classifies does: invalidation is opt-in, never a guess from the option's name.
+    def option(key, default = nil, invalidates: nil)
+      key = key.to_sym
+      return if options.include?(key)
+
+      define_option_accessors(key, Array(invalidates))
+      defaults[key] = default
+      options << key
+    end
+
+    # See ProviderOptionOwners for the conflict rules and the all-or-nothing guarantee. Every provider
+    # option invalidates provider_instance, whatever it is named -- the registry, not a remembered list,
+    # is what makes the set known.
+    def register_provider_options(declared, provider)
+      declared = normalise_declarations(declared)
+      provider_option_owners.claim(declared.keys, provider)
+      declared.each { |key, default| option(key, default, invalidates: :provider_instance) }
+    end
+
+    def options = @options ||= []
+    def defaults = @defaults ||= {}
+
+    private
+
+    # The writer clears exactly the memos this option was declared to invalidate; the reader defers to `read`.
+    # A write that leaves the raw value unchanged clears none of them -- a per-request write of the same
+    # tenant must not rebuild a cache store that was already warm.
+    def define_option_accessors(key, memos)
+      ivar = :"@#{key}"
+      define_method(:"#{key}=") do |value|
+        value = nil if value.is_a?(String) && value.strip.empty?
+        next if instance_variable_get(ivar) == value
+
+        instance_variable_set(ivar, value)
+        memos.each { |memo| instance_variable_set(:"@#{memo}", nil) }
+      end
+      define_method(key) { read(key) }
+    end
+
+    # `:key` declares an option with no default; `{ key => default }` declares one, and a callable is read lazily.
+    def normalise_declarations(declared)
+      entries = declared.is_a?(Hash) ? [declared] : Array(declared)
+
+      entries.each_with_object({}) do |entry, result|
+        entry.is_a?(Hash) ? result.merge!(entry.transform_keys(&:to_sym)) : result[entry.to_sym] = nil
+      end
+    end
+
+    def provider_option_owners = @provider_option_owners ||= ProviderOptionOwners.new
+  end
+
+  # Required here, not centrally: the modules they define nest under this class, which must exist first.
+  require "translation_diff/configuration/option_table"
+  TranslationDiff::Configuration::OptionTable.declare_on(self)
+
+  require "translation_diff/configuration/cache_ttl_option"
+  require "translation_diff/configuration/cache_guard_options"
+  prepend TranslationDiff::Configuration::CacheTtlOption
+  prepend TranslationDiff::Configuration::CacheGuardOptions
+
+  # Credentials are filtered by name; everything else is shown, or an inspect is one nobody reads.
+  def inspect = "#<#{self.class.name} #{TranslationDiff::Redaction.render(self).join(' ')}>"
+
+  # Memoised collaborators aren't copied, or a tenant's own cache_namespace leaks its parent's rate limiter.
+  def copy
+    self.class.new.tap do |other|
+      self.class.options.each do |key|
+        other.instance_variable_set(:"@#{key}", instance_variable_get(:"@#{key}"))
+      end
+    end
+  end
+
+  # Guarded, unlike cache/segmenter/rate_limiter: only the provider gained a base class to check against.
+  def provider_instance
+    @provider_instance ||=
+      TranslationDiff::Providers.ensure_provider!(resolve(provider, TranslationDiff::Providers))
+  end
+
+  # Unset `cache` means Redis when a URL is configured, otherwise in-process -- works before anything runs.
+  def cache_store
+    @cache_store ||= resolve(cache || (redis_url ? :redis : :memory), TranslationDiff::Stores)
+  end
+
+  def segmenter_instance
+    @segmenter_instance ||= resolve(segmenter, TranslationDiff::Segmenters.registry)
+  end
+
+  # nil, not a null object: Dispatcher#throttle checks for nil and skips rate-limiting -- costs nothing normally.
+  def rate_limiter_instance
+    return nil if rate_limiter.nil? && rate_limit.nil?
+
+    @rate_limiter_instance ||= resolve(rate_limiter || :redis, TranslationDiff::RateLimiters)
+  end
+
+  # One pool shared by the cache store and the rate limiter; callers used to build and pass it by hand.
+  def redis_pool
+    @redis_pool ||= build_redis_pool
+  end
+
+  private
+
+  def build_redis_pool
+    require "connection_pool"
+    require "redis"
+    ConnectionPool.new(size: redis_pool_size, timeout: redis_pool_timeout) do
+      Redis.new(url: redis_url)
+    end
+  rescue LoadError
+    raise TranslationDiff::Error,
+          "a Redis-backed cache or rate limiter was requested but the gems are not " \
+          'available. Add `gem "redis"`, `gem "connection_pool"` and ' \
+          '`gem "redis-namespace"` to your Gemfile.'
+  end
+
+  # A default is resolved on every read, and a blank one is unset -- the rule the writer already applies.
+  def read(key)
+    value = instance_variable_get(:"@#{key}")
+    return value unless value.nil?
+
+    default = self.class.defaults[key]
+    blank_to_nil(default.respond_to?(:call) ? default.call : default)
+  end
+
+  def blank_to_nil(value) = value.is_a?(String) && value.strip.empty? ? nil : value
+
+  # The symbol-or-object rule, implemented once for all three extension points.
+  def resolve(value, registry)
+    value.is_a?(Symbol) || value.is_a?(String) ? registry.build(value, self) : value
+  end
+end

data/lib/translation_diff/context.rb

@@ -0,0 +1,23 @@
+# An isolated configuration scope with the same entry point as TranslationDiff itself.
+class TranslationDiff::Context
+  attr_reader :config
+
+  def initialize(config)
+    @config = config
+  end
+
+  def translate(values, from: nil, to: nil, provider: nil, assume_supported: false, **)
+    TranslationDiff::Translator.new(
+      values, from: from, to: to, provider: provider, config: config,
+              assume_supported: assume_supported, **
+    ).call
+  end
+
+  # Answers what #translate would do to `values` under this context's own configuration, without calling it.
+  def preview(values, from: nil, to: nil, provider: nil, assume_supported: false, **)
+    TranslationDiff::Previewer.new(
+      values, from: from, to: to, provider: provider, config: config,
+              assume_supported: assume_supported, **
+    ).call
+  end
+end

data/lib/translation_diff/dispatcher.rb

@@ -0,0 +1,57 @@
+# Sends batches to the provider, throttles each one, and reports what it cost -- the seam between cache and wire.
+class TranslationDiff::Dispatcher
+  include TranslationDiff::Instrumentation
+
+  attr_reader :config
+
+  def initialize(provider:, from:, to:, call_id:, options: {}, config: nil)
+    @provider = provider
+    @from = from
+    @to = to
+    @call_id = call_id
+    @options = options
+    @config = config || TranslationDiff.config
+  end
+
+  def dispatch(segments)
+    batches = TranslationDiff::Batch.pack(segments, capabilities: @provider.class.capabilities)
+    batches.each { |batch| send_batch(batch) }
+  end
+
+  private
+
+  # The batch applies the reply to the segments that produced it, so no step ever correlates by position again.
+  def send_batch(batch)
+    texts = batch.texts
+    payload = { call_id: @call_id, provider: @provider.cache_key, batch: texts.size, characters: texts.sum(&:size) }
+    throttle(payload[:characters])
+    response = instrument("request", payload) { @provider.translate(request(texts)) }
+    report_usage(response, payload[:characters])
+    batch.apply(response.texts)
+  end
+
+  def request(texts)
+    TranslationDiff::Translation::Request.new(texts: texts, from: @from, to: @to, options: @options)
+  end
+
+  # Consulted with what is about to be sent, before it is sent; nil means no rate limiting was configured at all.
+  def throttle(characters)
+    limiter = config.rate_limiter_instance
+    return if limiter.nil?
+
+    instrument("rate_limit", call_id: @call_id, provider: @provider.cache_key,
+                             characters: characters) { limiter.check(characters) }
+  end
+
+  # A point event: what this request cost, as this library counted it -- a provider's own count never overrides it.
+  def report_usage(response, characters)
+    usage = response.usage
+
+    instrument("usage", call_id: @call_id,
+                        provider: @provider.cache_key,
+                        characters: characters,
+                        billed_characters: usage&.billed_characters,
+                        reported: @provider.class.capabilities.reports_billing?,
+                        model: usage&.model)
+  end
+end

data/lib/translation_diff/document.rb

@@ -0,0 +1,23 @@
+# A caller's value together with its Hash/Array shape, walked without ever flattening it into an array.
+class TranslationDiff::Document
+  def initialize(value) = @value = value
+
+  # Returns a new structure of the same shape with every leaf String replaced by the block's result.
+  def map(&) = walk(@value, &)
+
+  # Returns the leaf strings in document order, without touching the original value.
+  def strings
+    [].tap { |acc| walk(@value) { |string| acc << string } }
+  end
+
+  private
+
+  def walk(node, &block)
+    case node
+    when Hash then node.to_h { |key, value| [key, walk(value, &block)] }
+    when Array then node.map { |value| walk(value, &block) }
+    when String then block.call(node)
+    else node
+    end
+  end
+end

data/lib/translation_diff/errors.rb

@@ -0,0 +1,44 @@
+# No error carries the text being translated -- errors are logged, and this library handles other people's content.
+module TranslationDiff
+  # Common ancestor for every error this gem raises, so `rescue TranslationDiff::Error` is enough.
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  # Raised by whichever limiter is configured, so a caller rescues one class rather than the one it happens to use.
+  class RateLimitExceeded < Error; end
+
+  # Raised before any request: the pair is checked against data captured from the vendor, not by asking it.
+  class UnsupportedLanguageError < Error; end
+
+  class ProviderError < Error
+    attr_reader :provider, :status
+
+    def initialize(message, provider: nil, status: nil)
+      super(message)
+      @provider = provider
+      @status = status
+    end
+  end
+
+  class AuthenticationError < ProviderError; end
+  class QuotaExceededError < ProviderError; end
+  class InvalidRequestError < ProviderError; end
+  class ServiceError < ProviderError; end
+
+  class RateLimitError < ProviderError
+    # Faraday's retry middleware already honours this header; it's here for a caller scheduling its own retry.
+    attr_reader :retry_after
+
+    def initialize(message, provider: nil, status: nil, retry_after: nil)
+      super(message, provider: provider, status: status)
+      @retry_after = retry_after
+    end
+  end
+
+  class TransportError < Error; end
+  class ResponseError < Error; end
+
+  # Its own class, not the generic Error, so rescuing "wrong shape" can't also swallow an option-name collision.
+  class InvalidProviderError < Error; end
+end

data/lib/translation_diff/fragment.rb

@@ -0,0 +1,33 @@
+# A run of the source that is either markup, handed back as found, or prose, handed back through its segments.
+class TranslationDiff::Fragment
+  EMPTY = [].freeze
+
+  attr_reader :source
+
+  # Markup has nothing a provider should see, so it carries no segments and renders the bytes it was cut from.
+  def self.markup(source) = new(source, nil)
+
+  # Prose is cut where the segmenter says sentences begin, so every segment keeps the whitespace it was found in.
+  def self.prose(source, segmenter:, language: nil)
+    new(source, cut(source, segmenter.split_offsets(source, language: language)))
+  end
+
+  # The offsets start at 0 and strictly increase, so slicing between them and from the last to the end is exact.
+  def self.cut(source, offsets)
+    sentences = offsets.each_cons(2).map { |from, to| source[from...to] } << source[offsets.last..]
+    sentences.map { |sentence| TranslationDiff::Segment.new(sentence) }
+  end
+  private_class_method :cut
+
+  def initialize(source, segments)
+    @source = source
+    @segments = segments
+  end
+
+  def markup? = @segments.nil?
+
+  def segments = @segments || EMPTY
+
+  # The slice is copied on the way out, as Segment copies its own: rendering must not hand a caller the passage.
+  def render = markup? ? source.dup : @segments.map(&:render).join
+end

data/lib/translation_diff/http_provider.rb

@@ -0,0 +1,128 @@
+require "faraday"
+require "faraday/retry"
+require "json"
+
+# Every HTTP provider inherits this; no logging middleware, ever -- lines must carry no source text or credential.
+class TranslationDiff::HTTPProvider < TranslationDiff::Provider
+  RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+  # Faraday raises these when nobody answered, as opposed to answering "no".
+  TRANSPORT_FAILURES = [Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError].freeze
+
+  def api_base = raise NotImplementedError, "#{self.class} must implement #api_base"
+  def headers = {}
+
+  def translate_url = raise NotImplementedError, "#{self.class} must implement #translate_url"
+
+  def render_translate_payload(_request)
+    raise NotImplementedError, "#{self.class} must implement #render_translate_payload"
+  end
+
+  def parse_translate_response(_body, _headers, _request)
+    raise NotImplementedError, "#{self.class} must implement #parse_translate_response"
+  end
+
+  def translate(request)
+    response = post(translate_url, render_translate_payload(request))
+    parse_translate_response(response.body, response.headers, request)
+  end
+
+  def connection = @connection ||= build_connection
+
+  private
+
+  # Mirrors the shape a Faraday::Response would give if its own JSON middleware were still in the stack.
+  Decoded = Data.define(:status, :headers, :body)
+  private_constant :Decoded
+
+  def post(url, payload)
+    raw = connection.post(url, payload)
+    response = Decoded.new(status: raw.status, headers: raw.headers, body: decode(raw))
+    raise_for_status!(response)
+    response
+  rescue *TRANSPORT_FAILURES => e
+    # The message is the transport's, never the payload's: the payload is the customer's text.
+    raise TranslationDiff::TransportError, "#{self.class}: #{e.class}: #{e.message}"
+  end
+
+  def get(url)
+    raw = connection.get(url)
+    response = Decoded.new(status: raw.status, headers: raw.headers, body: decode(raw))
+    raise_for_status!(response)
+    response
+  rescue *TRANSPORT_FAILURES => e
+    raise TranslationDiff::TransportError, "#{self.class}: #{e.class}: #{e.message}"
+  end
+
+  # Faraday's JSON middleware passes parser options positionally, which json 3 (default on Ruby 4.x) removed.
+  def decode(response)
+    body = response.body
+    return body unless body.is_a?(String)
+    return body if body.strip.empty?
+    return body unless json?(response)
+
+    JSON.parse(body)
+  rescue JSON::ParserError => e
+    raise TranslationDiff::ResponseError,
+          "#{self.class} returned a body that is not JSON: #{e.message[0, 200]}"
+  end
+
+  def json?(response) = response.headers["content-type"].to_s.match?(/\bjson\b/)
+
+  # The block is how a test swaps in Faraday's test adapter; Amazon overrides it too, to sign the body as sent.
+  def build_connection(&)
+    Faraday.new(url: api_base, headers: headers) do |faraday|
+      faraday.request :json
+      faraday.request :retry, retry_options
+      adapt(faraday, &)
+      apply_timeouts(faraday)
+    end
+  end
+
+  def adapt(faraday, &block)
+    block ? block.call(faraday) : faraday.adapter(Faraday.default_adapter)
+  end
+
+  def apply_timeouts(faraday)
+    faraday.options.open_timeout = config.open_timeout
+    faraday.options.timeout = config.timeout
+  end
+
+  # faraday-retry reads Retry-After itself, which is why a 429 usually never reaches #raise_for_status!.
+  def retry_options
+    { max: config.max_retries, interval: 0.5, backoff_factor: 2, interval_randomness: 0.5,
+      retry_statuses: RETRY_STATUSES, methods: %i[post get],
+      exceptions: TRANSPORT_FAILURES + [Faraday::RetriableResponse] }
+  end
+
+  def raise_for_status!(response)
+    status = response.status
+    return if status < 400
+
+    raise error_class(status).new(error_message(response), **error_options(response))
+  end
+
+  def error_class(status)
+    case status
+    when 401, 403 then TranslationDiff::AuthenticationError
+    when 429 then TranslationDiff::RateLimitError
+    when 456 then TranslationDiff::QuotaExceededError
+    when 400..499 then TranslationDiff::InvalidRequestError
+    else TranslationDiff::ServiceError
+    end
+  end
+
+  def error_options(response)
+    options = { provider: name, status: response.status }
+    return options unless response.status == 429
+
+    options.merge(retry_after: response.headers["Retry-After"]&.to_i)
+  end
+
+  # Truncated: an untruncated provider error body can be a whole HTML error page.
+  def error_message(response)
+    body = response.body
+    text = body.is_a?(Hash) ? (body["message"] || body["error"] || body.to_s) : body.to_s
+    "#{self.class} responded #{response.status}: #{text.to_s[0, 300]}"
+  end
+end

data/lib/translation_diff/instrumentation.rb

@@ -0,0 +1,25 @@
+# Payloads carry counts, language codes and provider names -- never the text, its translation, or a credential.
+module TranslationDiff::Instrumentation
+  SUFFIX = ".translation_diff".freeze
+
+  # `include` ignores the includer's own `private` keyword, so visibility has to be declared here.
+  private
+
+  # A point event (no block) reports a fact that already happened, e.g. a cache hit/miss tally.
+  def instrument(name, payload = {})
+    instrumenter = config.instrumenter
+    return yield if instrumenter.nil? && block_given?
+    return if instrumenter.nil?
+
+    instrumenter.instrument("#{name}#{SUFFIX}", payload) { yield if block_given? }
+  end
+
+  def log(message)
+    config.logger&.debug { "[translation_diff] #{message}" }
+  end
+
+  # For the things an operator must see at a production log level; carries no more content than #log does.
+  def warn_log(message)
+    config.logger&.warn { "[translation_diff] #{message}" }
+  end
+end

data/lib/translation_diff/languages/refresh.rb

@@ -0,0 +1,70 @@
+# A maintainer's tool: re-fetches every provider's lists and rewrites the shipped files.
+class TranslationDiff::Languages::Refresh
+  def self.call(providers:, directory: TranslationDiff::Languages::DIRECTORY, on: Time.now.strftime("%Y-%m-%d"))
+    new(providers: providers, directory: directory, on: on).call
+  end
+
+  def initialize(providers:, directory:, on:)
+    @providers = providers
+    @directory = directory
+    @on = on
+  end
+
+  # A provider whose fetch fails keeps its previous file: an emptied list is worse than a stale one.
+  def call
+    report = { updated: [], failed: {}, skipped: [] }
+
+    @providers.each do |provider|
+      name = provider.cache_key
+      fetched = fetch(provider, name, report)
+      next if fetched.nil?
+
+      persist(name, provider, fetched, report)
+    end
+
+    report
+  end
+
+  private
+
+  def fetch(provider, name, report)
+    fetched = provider.languages
+    return report_empty(name, report) if empty?(fetched)
+
+    fetched
+  rescue NotImplementedError
+    report[:skipped] << name
+    nil
+  rescue StandardError => e
+    report[:failed][name] = "#{e.class}: #{e.message}"
+    nil
+  end
+
+  # A 200 with an empty or malformed body degrades to [] through Array(...); that is not data, it's a failure.
+  def empty?(fetched) = Array(fetched[:source]).empty? || Array(fetched[:target]).empty?
+
+  def report_empty(name, report)
+    report[:failed][name] = "the vendor answered with an empty source or target list"
+    nil
+  end
+
+  # A write that cannot land -- a read-only checkout, a full disk -- must not cost the rest of the run.
+  def persist(name, provider, fetched, report)
+    write(name, provider, fetched)
+    report[:updated] << name
+  rescue StandardError => e
+    report[:failed][name] = "#{e.class}: #{e.message}"
+  end
+
+  def write(name, provider, fetched)
+    document = { "provider" => name, "captured_at" => @on,
+                 "endpoint" => endpoint(provider),
+                 "source" => normalise(fetched[:source]), "target" => normalise(fetched[:target]) }
+
+    File.write(File.join(@directory, "#{name}.json"), "#{JSON.pretty_generate(document)}\n")
+  end
+
+  def normalise(codes) = Array(codes).map { |code| code.to_s.downcase }.uniq.sort
+
+  def endpoint(provider) = provider.languages_endpoint.to_s
+end

data/lib/translation_diff/languages/set.rb

@@ -0,0 +1,53 @@
+# One provider's languages as captured on a date; source and target differ, so they are kept apart.
+class TranslationDiff::Languages::Set
+  attr_reader :provider, :captured_at, :endpoint, :source, :target
+
+  # ISO 639-1 macrolanguage codes callers write, mapped to the ISO 639-3 individual some vendors ship instead.
+  # One-way only: a vendor listing the individual has, by definition, covered its macro; the reverse is not true.
+  MACRO_ALIASES = {
+    "fa" => "pes", "uz" => "uzn", "yi" => "ydd", "om" => "gaz", "qu" => "quy", "ay" => "ayr",
+    "mn" => "khk", "ms" => "zsm", "lv" => "lvs", "mg" => "plt", "az" => "azj", "ps" => "pbt",
+    "sw" => "swh", "ku" => "kmr", "zh" => "cmn", "ne" => "npi", "or" => "ory", "sq" => "als"
+  }.freeze
+
+  def self.load(path)
+    document = parse(path)
+
+    new(provider: document["provider"], captured_at: document["captured_at"],
+        endpoint: document["endpoint"], source: document["source"], target: document["target"])
+  end
+
+  # A maintainer sees a path and the parser's own complaint instead of guessing which of the shipped files broke.
+  def self.parse(path)
+    JSON.parse(File.read(path))
+  rescue JSON::ParserError => e
+    raise TranslationDiff::Error, "#{path} is not valid JSON: #{e.message}"
+  end
+  private_class_method :parse
+
+  def initialize(provider:, captured_at:, endpoint:, source:, target:)
+    @provider = provider
+    @captured_at = captured_at
+    @endpoint = endpoint
+    @source = normalise(source)
+    @target = normalise(target)
+    freeze
+  end
+
+  def supports_source?(code) = matches?(@source, code)
+  def supports_target?(code) = matches?(@target, code)
+
+  private
+
+  def normalise(codes) = Array(codes).map { |code| code.to_s.downcase }.freeze
+
+  # Primary subtag in both directions, plus a macro wanted against the individual code this provider lists for it.
+  def matches?(codes, code)
+    wanted = code.to_s.downcase
+    return true if wanted.empty?
+
+    primary = wanted.split("-").first
+    accepted = [primary, MACRO_ALIASES[primary]].compact
+    codes.any? { |known| known == wanted || accepted.include?(known.split("-").first) }
+  end
+end