translation_diff 1.0.0

data/lib/translation_diff/providers/deepl.rb

@@ -0,0 +1,88 @@
+# Talks to DeepL's REST API directly, not deepl-rb: it logged the auth key at DEBUG and defaulted notranslate off.
+class TranslationDiff::Providers::DeepL < TranslationDiff::HTTPProvider
+  PAID_HOST = "https://api.deepl.com".freeze
+  FREE_HOST = "https://api-free.deepl.com".freeze
+
+  # A key ending in :fx is a free-plan key, and the free plan lives on its own host.
+  FREE_KEY_SUFFIX = ":fx".freeze
+
+  # DeepL honours class="notranslate" only under HTML tag handling -- otherwise content translates, tags survive.
+  DEFAULT_OPTIONS = { tag_handling: :html, tag_handling_version: "v2" }.freeze
+
+  # 50 texts / 128 KiB are DeepL's documented per-request limits; max_batch_size was wrong before (it said 300).
+  def self.capabilities
+    TranslationDiff::Capabilities.new(
+      max_request_size: 1_700, max_batch_size: 50, max_text_size: nil,
+      html: :tag_handling, notranslate: true, detects_language: true, reports_billing: true
+    )
+  end
+
+  # DEEPL_AUTH_KEY is what deepl-rb read on our behalf; the callable keeps it read on use, not at load.
+  def self.configuration_options
+    [:deepl_api_base, { deepl_api_key: -> { ENV.fetch("DEEPL_AUTH_KEY", nil) } }]
+  end
+
+  def self.configuration_requirements = %i[deepl_api_key]
+
+  # DeepL is the one vendor documenting upper-case codes.
+  def self.language_case = :upcase
+
+  # DeepL requires a target language even when only detection is wanted, so the provider picks one.
+  DETECTION_TARGET = "EN".freeze
+
+  def api_base
+    config.deepl_api_base || (free_key? ? FREE_HOST : PAID_HOST)
+  end
+
+  def headers = { "Authorization" => "DeepL-Auth-Key #{config.deepl_api_key}" }
+
+  def translate_url = "v2/translate"
+
+  def render_translate_payload(request)
+    DEFAULT_OPTIONS
+      .merge(request.options)
+      .merge(text: request.texts, target_lang: language(request.to))
+      .tap { |payload| payload[:source_lang] = language(request.from) unless request.from.nil? }
+  end
+
+  def parse_translate_response(body, _headers, request)
+    translations = Array(body["translations"])
+
+    TranslationDiff::Translation::Response.build(
+      request: request,
+      texts: translations.map { |t| t["text"] },
+      detected_source: translations.first&.dig("detected_source_language")&.downcase,
+      usage: usage_for(request, translations)
+    )
+  end
+
+  # DeepL has no detection endpoint; translating a sample and reading the source it reports is the only way.
+  def detect(text)
+    request = TranslationDiff::Translation::Request.new(texts: [text], from: nil,
+                                                        to: DETECTION_TARGET)
+    translate(request).detected_source
+  end
+
+  def languages
+    { source: codes(get("v2/languages?type=source").body),
+      target: codes(get("v2/languages?type=target").body) }
+  end
+
+  # The source-list URL is enough to document what #languages fetches; the target one differs only by query.
+  def languages_endpoint = "#{api_base}/v2/languages"
+
+  private
+
+  def codes(body) = Array(body).map { |entry| entry["language"] }
+
+  def free_key? = config.deepl_api_key.to_s.end_with?(FREE_KEY_SUFFIX)
+
+  def usage_for(request, translations)
+    TranslationDiff::Translation::Usage.new(
+      characters: request.texts.sum(&:size),
+      billed_characters: billed_characters(translations.map { |t| t["billed_characters"] })
+    )
+  end
+end
+
+TranslationDiff::Providers.register(:deepl, TranslationDiff::Providers::DeepL)

data/lib/translation_diff/providers/google.rb

@@ -0,0 +1,64 @@
+# Talks to Cloud Translation v2 directly, not google-cloud-translate-v2, which pulled in grpc for one POST.
+class TranslationDiff::Providers::Google < TranslationDiff::HTTPProvider
+  HOST = "https://translation.googleapis.com".freeze
+
+  # Verified against the live API: `text` format translates the protected span and drops its markup.
+  DEFAULT_FORMAT = :html
+
+  # Google's documented limits: 128 strings/request, 5,000 chars recommended (hard ceiling 100 KB).
+  def self.capabilities
+    TranslationDiff::Capabilities.new(
+      max_request_size: 5_000, max_batch_size: 128, max_text_size: nil,
+      html: :format, notranslate: true, detects_language: true, reports_billing: false
+    )
+  end
+
+  # TRANSLATE_KEY then GOOGLE_CLOUD_KEY, the order google-cloud-translate-v2 read them in.
+  def self.configuration_options
+    [:google_api_base,
+     { google_api_key: -> { ENV.fetch("TRANSLATE_KEY", nil) || ENV.fetch("GOOGLE_CLOUD_KEY", nil) },
+       google_project_id: -> { ENV.fetch("TRANSLATE_PROJECT", nil) } }]
+  end
+
+  def self.configuration_requirements = %i[google_api_key]
+
+  def api_base = config.google_api_base || HOST
+  def translate_url = "language/translate/v2?key=#{CGI.escape(config.google_api_key.to_s)}"
+  def detect_url = "language/translate/v2/detect?key=#{CGI.escape(config.google_api_key.to_s)}"
+
+  def render_translate_payload(request)
+    { format: DEFAULT_FORMAT }
+      .merge(request.options)
+      .merge(q: request.texts, target: language(request.to))
+      .tap { |payload| payload[:source] = language(request.from) unless request.from.nil? }
+  end
+
+  def parse_translate_response(body, _headers, request)
+    translations = Array(body.dig("data", "translations"))
+
+    TranslationDiff::Translation::Response.build(
+      request: request,
+      texts: translations.map { |t| t["translatedText"] },
+      detected_source: translations.first&.dig("detectedSourceLanguage")&.downcase,
+      usage: TranslationDiff::Translation::Usage.new(characters: request.texts.sum(&:size))
+    )
+  end
+
+  def detect(text)
+    response = post(detect_url, { q: [text] })
+    response.body.dig("data", "detections", 0, 0, "language")&.downcase
+  end
+
+  # One list, used in both directions.
+  def languages
+    codes = Array(get("language/translate/v2/languages?key=#{CGI.escape(config.google_api_key.to_s)}")
+                    .body.dig("data", "languages")).map { |entry| entry["language"] }
+
+    { source: codes, target: codes }
+  end
+
+  # The key is left out: it is a credential, not part of what documents where this list comes from.
+  def languages_endpoint = "#{api_base}/language/translate/v2/languages"
+end
+
+TranslationDiff::Providers.register(:google, TranslationDiff::Providers::Google)

data/lib/translation_diff/providers/libretranslate.rb

@@ -0,0 +1,65 @@
+# The only free, self-hosted provider here; base URL is required (everyone runs their own), API key is optional.
+class TranslationDiff::Providers::LibreTranslate < TranslationDiff::HTTPProvider
+  DEFAULT_FORMAT = "html".freeze
+
+  # The API's own way of asking for detection: `source` is required, and "auto" means "work it out".
+  AUTO = "auto".freeze
+
+  # Observed 2026-09-09 via Docker: LibreTranslate's HTML format preserves markup but translates content anyway.
+  LIBRETRANSLATE_HONOURS_NOTRANSLATE = false
+
+  # LibreTranslate publishes no per-request limits; these are this library's own conservative numbers.
+  def self.capabilities
+    TranslationDiff::Capabilities.new(
+      max_request_size: 5_000, max_batch_size: 50, max_text_size: nil,
+      html: :format, notranslate: LIBRETRANSLATE_HONOURS_NOTRANSLATE,
+      detects_language: true, reports_billing: false
+    )
+  end
+
+  def self.configuration_options = %i[libretranslate_api_key libretranslate_api_base]
+  def self.configuration_requirements = %i[libretranslate_api_base]
+
+  def api_base = config.libretranslate_api_base
+  def translate_url = "translate"
+
+  def render_translate_payload(request)
+    { format: DEFAULT_FORMAT }
+      .merge(request.options)
+      .merge(q: request.texts, target: language(request.to),
+             source: request.from.nil? ? AUTO : language(request.from))
+      .tap { |payload| payload[:api_key] = config.libretranslate_api_key if config.libretranslate_api_key }
+  end
+
+  def parse_translate_response(body, _headers, request)
+    translated = body["translatedText"]
+    detected = body["detectedLanguage"]
+    detected = detected.first if detected.is_a?(Array)
+
+    TranslationDiff::Translation::Response.build(
+      request: request,
+      texts: translated.is_a?(Array) ? translated : [translated].compact,
+      detected_source: detected.is_a?(Hash) ? detected["language"]&.downcase : nil,
+      usage: TranslationDiff::Translation::Usage.new(characters: request.texts.sum(&:size))
+    )
+  end
+
+  def detect(text)
+    payload = { q: text }
+    payload[:api_key] = config.libretranslate_api_key if config.libretranslate_api_key
+
+    post("detect", payload).body.dig(0, "language")&.downcase
+  end
+
+  # Each entry lists its own targets; a self-hosted instance answers for itself, which is the point.
+  def languages
+    entries = Array(get("languages").body)
+
+    { source: entries.map { |entry| entry["code"] },
+      target: entries.flat_map { |entry| Array(entry["targets"]) }.uniq }
+  end
+
+  def languages_endpoint = "#{api_base}/languages"
+end
+
+TranslationDiff::Providers.register(:libretranslate, TranslationDiff::Providers::LibreTranslate)

data/lib/translation_diff/providers/modernmt.rb

@@ -0,0 +1,74 @@
+# ModernMT: adaptive translation with translation memories.
+class TranslationDiff::Providers::ModernMT < TranslationDiff::HTTPProvider
+  HOST = "https://api.modernmt.com".freeze
+
+  # ModernMT spells its formats as MIME types.
+  DEFAULT_FORMAT = "text/html".freeze
+
+  # Unverified, not observed: no key was available to probe it; false is the safe assumption either way.
+  MODERNMT_HONOURS_NOTRANSLATE = false
+
+  # 128 texts is documented; the character limit is not, so Google's 5,000 recommendation is borrowed.
+  def self.capabilities
+    TranslationDiff::Capabilities.new(
+      max_request_size: 5_000, max_batch_size: 128, max_text_size: nil,
+      html: :format, notranslate: MODERNMT_HONOURS_NOTRANSLATE,
+      detects_language: true, reports_billing: true
+    )
+  end
+
+  def self.configuration_options = %i[modernmt_api_key modernmt_api_base]
+  def self.configuration_requirements = %i[modernmt_api_key]
+
+  def api_base = config.modernmt_api_base || HOST
+  def headers = { "MMT-ApiKey" => config.modernmt_api_key.to_s }
+  def translate_url = "translate"
+
+  def render_translate_payload(request)
+    { format: DEFAULT_FORMAT }
+      .merge(request.options)
+      .merge(q: request.texts, target: language(request.to))
+      .tap { |payload| payload[:source] = language(request.from) unless request.from.nil? }
+  end
+
+  # One text comes back as an object rather than a one-element array, so the envelope is always coerced.
+  def parse_translate_response(body, _headers, request)
+    results = results_from(body)
+
+    TranslationDiff::Translation::Response.build(
+      request: request,
+      texts: results.map { |r| r["translation"] },
+      detected_source: results.first&.dig("detectedLanguage")&.downcase,
+      usage: usage_for(request, results)
+    )
+  end
+
+  def detect(text)
+    request = TranslationDiff::Translation::Request.new(texts: [text], from: nil, to: "en")
+    translate(request).detected_source
+  end
+
+  def languages
+    codes = Array(get("translate/languages").body["data"])
+
+    { source: codes, target: codes }
+  end
+
+  def languages_endpoint = "#{api_base}/translate/languages"
+
+  private
+
+  def results_from(body)
+    data = body["data"]
+    data.is_a?(Array) ? data : [data].compact
+  end
+
+  def usage_for(request, results)
+    TranslationDiff::Translation::Usage.new(
+      characters: request.texts.sum(&:size),
+      billed_characters: billed_characters(results.map { |r| r["billedCharacters"] })
+    )
+  end
+end
+
+TranslationDiff::Providers.register(:modernmt, TranslationDiff::Providers::ModernMT)

data/lib/translation_diff/providers/null.rb

@@ -0,0 +1,20 @@
+# Hands back what it was given -- for tests, and for wiring a pipeline up before a real provider is available.
+class TranslationDiff::Providers::Null < TranslationDiff::Provider
+  # Deliberately not detecting: this is the provider that proves the optional branch works.
+  def self.capabilities
+    TranslationDiff::Capabilities.new(
+      max_request_size: 1_000_000, max_batch_size: 1_000_000, max_text_size: nil,
+      html: :none, notranslate: false, detects_language: false, reports_billing: false
+    )
+  end
+
+  def translate(request)
+    TranslationDiff::Translation::Response.build(
+      request: request, texts: request.texts.map(&:to_s)
+    )
+  end
+
+  def cache_key = "null"
+end
+
+TranslationDiff::Providers.register(:null, TranslationDiff::Providers::Null)

data/lib/translation_diff/providers.rb

@@ -0,0 +1,69 @@
+# Translation providers, by name; registering one also declares its configuration options.
+module TranslationDiff::Providers
+  # Said once, so a provider refused by name, by class or as an object is refused in the same words.
+  CONTRACT = "The base class supplies the transport, the configuration check and the " \
+             "capability defaults, so a provider that skips it has none of them.".freeze
+
+  class << self
+    # Options are declared before the registry entry is written, so a name collision raises without replacing.
+    def register(name, klass)
+      ensure_provider_class!(klass)
+      TranslationDiff::Configuration.register_provider_options(klass.configuration_options, klass)
+      registry.register(name, klass)
+    end
+
+    # Guards registration. `klass < Provider` alone raises NoMethodError for an instance or a non-Module.
+    def ensure_provider_class!(klass)
+      return klass if klass.is_a?(Class) && klass < TranslationDiff::Provider
+
+      raise TranslationDiff::InvalidProviderError,
+            "#{describe(klass)} cannot be registered as a provider: the registry takes a " \
+            "class inheriting TranslationDiff::Provider. #{CONTRACT}"
+    end
+
+    # Guards the other two ways a provider arrives: assigned to config.provider, or passed as `provider:`.
+    def ensure_provider!(instance)
+      return instance if instance.is_a?(TranslationDiff::Provider)
+
+      raise TranslationDiff::InvalidProviderError,
+            "#{describe(instance)} cannot be used as a provider: it does not inherit " \
+            "TranslationDiff::Provider. #{CONTRACT}"
+    end
+
+    def build(name, config)
+      registry.build(name, config).tap { |provider| provider.name = name.to_sym }
+    end
+
+    # The one seam Translator and Previewer both resolve a provider through, cache_key guard included.
+    def resolve(requested, config)
+      provider = requested.nil? ? config.provider_instance : resolve_requested(requested, config)
+      ensure_cache_key!(provider)
+    end
+
+    def registered?(name) = registry.registered?(name)
+    def names = registry.names
+    def classes = registry.classes
+    def registry = @registry ||= TranslationDiff::Registry.new("provider")
+
+    private
+
+    # A provider arrives as a name to build, or as an object to use as it is.
+    def resolve_requested(requested, config)
+      return build(requested, config) if requested.is_a?(Symbol) || requested.is_a?(String)
+
+      ensure_provider!(requested)
+    end
+
+    # The cache key names the provider in every payload too: it is the one identifier every provider must have.
+    def ensure_cache_key!(provider)
+      return provider unless provider.cache_key.to_s.strip.empty?
+
+      raise TranslationDiff::InvalidProviderError,
+            "#{provider.class} must define #cache_key: a blank one would file its " \
+            "translations in every other provider's cache namespace."
+    end
+
+    # Never #to_s on a non-Module: an arbitrary object renders its own content, or an address.
+    def describe(value) = value.is_a?(Module) ? value.to_s : "an instance of #{value.class}"
+  end
+end

data/lib/translation_diff/railtie.rb

@@ -0,0 +1,12 @@
+# Loaded only when Rails already is (see the guarded require in translation_diff.rb), never on its own.
+require "active_support/core_ext/module/delegation"
+require "rails/railtie"
+
+# Adds translation_diff:prune to a host Rails application's own rake tasks; the gem's dev Rakefile loads the
+# same task file directly, so a host application's `rake -T` and this gem's own suite see one definition.
+class TranslationDiff::Railtie < Rails::Railtie
+  rake_tasks do
+    load File.expand_path("tasks/translation_diff.rake", __dir__)
+    Rake::Task["translation_diff:prune"].enhance(["environment"])
+  end
+end

data/lib/translation_diff/rate_limiters/active_record.rb

@@ -0,0 +1,92 @@
+# Throttles by counting characters into namespaced, time-bucketed rows in the application's own database.
+class TranslationDiff::RateLimiters::ActiveRecord
+  include TranslationDiff::ActiveRecord::Support
+
+  DEFAULT_THRESHOLD = 8000
+  DEFAULT_INTERVAL = 60
+
+  # A bucket a twelfth of the interval wide caps a window's slop at under 10%, the same shape the `ratelimit` gem
+  # gets from its own fixed five-second buckets at the default 60-second interval.
+  BUCKET_FRACTION = 12
+
+  # An unset rate_limit must mean DEFAULT_THRESHOLD, not the nil that would override that keyword default.
+  def self.build(config)
+    options = { namespace: config.cache_namespace, table_name: config.rate_limit_table_name,
+                interval: config.rate_interval, base: config.active_record_base }
+    options[:threshold] = config.rate_limit unless config.rate_limit.nil?
+    new(**options)
+  end
+
+  def initialize(namespace:, table_name:, threshold: DEFAULT_THRESHOLD, interval: DEFAULT_INTERVAL, base: nil,
+                 clock: -> { Time.now })
+    @namespace = namespace
+    @table_name = table_name
+    @threshold = threshold
+    @interval = interval
+    @base = base
+    @clock = clock
+    @bucket_width = [@interval / BUCKET_FRACTION, 1].max
+  end
+
+  # A sliding window: every bucket covering the last `interval` seconds is summed, not just the current one.
+  def check(size)
+    raise TranslationDiff::RateLimitExceeded, exceeded_message if current_total >= @threshold
+
+    add(size)
+  rescue StandardError => e
+    raise unless ar_error?(e)
+
+    raise redacted_error(e), cause: nil
+  end
+
+  # The limiter's own statements carry counts, not content -- but a ReadOnlyError quotes the statement, and
+  # a raw ActiveRecord error from inside a translate call tells a caller nothing about which gem it came from.
+  def redacted_error(error)
+    adapter_error = error.cause&.class || error.class
+    TranslationDiff::Error.new("the rate limit check failed (#{adapter_error}): a read or upsert on " \
+                               "#{@table_name}(namespace, bucket, characters)")
+  end
+
+  # Counts and settings, never a character of what was being translated.
+  def exceeded_message
+    "rate limit reached for #{@namespace}: #{@threshold} characters per #{@interval} seconds"
+  end
+
+  # Buckets that have fully aged out of the window as of now; the oldest bucket itself is still counted by it.
+  def prune = model.where(namespace: @namespace).where(bucket: ...oldest_bucket).delete_all
+
+  private
+
+  # The oldest bucket is only ever partially inside the window, so summing from it, not past it, errs strict.
+  def current_total
+    model.where(namespace: @namespace, bucket: oldest_bucket..current_bucket).sum(:characters)
+  end
+
+  def current_bucket = now / @bucket_width
+
+  def oldest_bucket = (now - @interval) / @bucket_width
+
+  def now = @clock.call.to_i
+
+  # One statement, so two processes incrementing the same bucket cannot lose an increment between them.
+  # A negative size would otherwise hand back headroom it never used, so it is clamped before it reaches SQL.
+  def add(size)
+    size = size.to_i.clamp(0..)
+    model.upsert_all([{ namespace: @namespace, bucket: current_bucket, characters: size }],
+                     **upsert_options(model.connection, size))
+  end
+
+  # MySQL's adapter never answers true here and its ON DUPLICATE KEY UPDATE already targets every unique key.
+  def upsert_options(connection, size)
+    table = connection.quote_table_name(model.table_name)
+    options = { on_duplicate: Arel.sql("characters = #{table}.characters + #{size}") }
+    options[:unique_by] = %i[namespace bucket] if connection.supports_insert_conflict_target?
+    options
+  end
+
+  def active_record_feature = "the rate limiter"
+  def active_record_component = "ActiveRecord rate limiter"
+  def active_record_upsert_detail = "upsert_all takes unique_by there."
+end
+
+TranslationDiff::RateLimiters.register(:active_record, TranslationDiff::RateLimiters::ActiveRecord)

data/lib/translation_diff/rate_limiters/redis.rb

@@ -0,0 +1,59 @@
+class TranslationDiff::RateLimiters::Redis
+  DEFAULT_THRESHOLD = 8000
+  DEFAULT_INTERVAL = 60
+  DEFAULT_NAMESPACE = "translation-diff".freeze
+
+  # This library limits the provider as a whole rather than per caller, so there is exactly one subject.
+  SUBJECT = "call".freeze
+
+  # An unset rate_limit must mean DEFAULT_THRESHOLD, not the nil that would override that keyword default.
+  def self.build(config)
+    options = { interval: config.rate_interval, namespace: config.cache_namespace }
+    options[:threshold] = config.rate_limit unless config.rate_limit.nil?
+    new(config.redis_pool, **options)
+  end
+
+  # `connection_pool` is duck-typed to #with; neither connection_pool nor ratelimit is a hard dependency.
+  def initialize(connection_pool,
+                 threshold: DEFAULT_THRESHOLD,
+                 interval: DEFAULT_INTERVAL,
+                 namespace: DEFAULT_NAMESPACE)
+    @connection_pool = connection_pool
+    @threshold = threshold
+    @interval = interval
+    @namespace = namespace
+  end
+
+  def check(size)
+    limiter_class = ratelimit_class
+
+    connection_pool.with do |redis|
+      rate_limit = limiter_class.new(namespace, redis: redis)
+      exceeded = rate_limit.exceeded?(SUBJECT, threshold: threshold, interval: interval)
+      raise TranslationDiff::RateLimitExceeded, exceeded_message if exceeded
+
+      rate_limit.add(SUBJECT, size)
+    end
+  end
+
+  private
+
+  # Counts and settings, never a character of what was being translated.
+  def exceeded_message
+    "rate limit reached for #{namespace}: #{threshold} characters per #{interval} seconds"
+  end
+
+  attr_reader :connection_pool, :threshold, :interval, :namespace
+
+  # Required at first check, not load time; naming the bare constant instead would raise a raw NameError.
+  def ratelimit_class
+    require "ratelimit"
+    ::Ratelimit
+  rescue LoadError
+    raise TranslationDiff::Error,
+          "a rate limit was configured but the `ratelimit` gem is not available. " \
+          'Add `gem "ratelimit"` to your Gemfile.'
+  end
+end
+
+TranslationDiff::RateLimiters.register(:redis, TranslationDiff::RateLimiters::Redis)

data/lib/translation_diff/rate_limiters.rb

@@ -0,0 +1,9 @@
+# Rate limiters, by name; assigning an object to `config.rate_limiter` bypasses this entirely.
+module TranslationDiff::RateLimiters
+  def self.register(name, klass) = registry.register(name, klass)
+  def self.build(name, config) = registry.build(name, config)
+  def self.registered?(name) = registry.registered?(name)
+  def self.names = registry.names
+  def self.classes = registry.classes
+  def self.registry = @registry ||= TranslationDiff::Registry.new("rate limiter")
+end

data/lib/translation_diff/redaction.rb

@@ -0,0 +1,45 @@
+require "uri"
+
+# Which configuration options must never be printed, decided by name rather than by a list someone maintains.
+module TranslationDiff::Redaction
+  SENSITIVE = /key|secret|token|password|auth|credential/
+  FILTERED = "[FILTERED]".freeze
+
+  def self.sensitive?(name) = name.to_s.match?(SENSITIVE)
+
+  # Unioned fresh on every call, never memoised -- a provider can register after the first inspect.
+  def self.declared_sensitive
+    TranslationDiff::Providers.classes.flat_map(&:sensitive_options).map(&:to_sym)
+  end
+
+  # Reads through the public accessor, or an option set only through its ENV-backed default goes unnoticed.
+  def self.render(config)
+    declared = declared_sensitive
+
+    TranslationDiff::Configuration.options.filter_map do |key|
+      value = config.public_send(key)
+      next if value.nil?
+
+      "#{key}=#{rendered_value(key, value, declared)}"
+    end
+  end
+
+  def self.rendered_value(key, value, declared)
+    return FILTERED if sensitive?(key) || declared.include?(key)
+
+    (redact_userinfo(value) || value).inspect
+  end
+
+  # redis_url and a provider's *_api_base can carry a credential inline; the host stays, only the userinfo hides.
+  def self.redact_userinfo(value)
+    return nil unless value.is_a?(String)
+
+    userinfo = URI.parse(value).userinfo
+    return nil unless userinfo
+
+    user, separator, = userinfo.partition(":")
+    value.sub(userinfo, separator.empty? ? FILTERED : "#{user}:#{FILTERED}")
+  rescue URI::Error
+    nil
+  end
+end

data/lib/translation_diff/registry.rb

@@ -0,0 +1,31 @@
+# Maps a symbol to a class that builds itself from a Configuration; the whole contract is answering `build(config)`.
+class TranslationDiff::Registry
+  # `kind` appears in the unknown-name error message, so it should be a singular noun: "provider".
+  def initialize(kind)
+    @kind = kind
+    @entries = {}
+  end
+
+  def register(name, klass)
+    @entries[name.to_sym] = klass
+  end
+
+  def build(name, config)
+    fetch(name).build(config)
+  end
+
+  def registered?(name) = @entries.key?(name.to_sym)
+
+  def names = @entries.keys
+
+  def classes = @entries.values
+
+  private
+
+  def fetch(name)
+    @entries.fetch(name.to_sym) do
+      raise TranslationDiff::Error,
+            "Unknown #{@kind} #{name.to_sym.inspect}. Registered: #{names.join(', ')}"
+    end
+  end
+end

data/lib/translation_diff/segment.rb

@@ -0,0 +1,32 @@
+# A sentence with the whitespace it was found in: its core is the text a provider sees, its render is markup again.
+class TranslationDiff::Segment
+  attr_reader :source, :body, :core
+  attr_accessor :translation
+
+  # A core is compared decoded, so a sentence that was only ` ` counts as the padding it is and is never sent.
+  BLANK = /\A[[:space:]]*\z/
+
+  def initialize(source)
+    @source = source.dup
+    @leading, @body, @trailing = @source.partition(/[^[:space:]].*[^[:space:]]|[^[:space:]]/m)
+    @core = TranslationDiff::Markup.decode_entities(@body)
+  end
+
+  # Reflects whether a translation is set right now, not history -- clearing it to nil flips this back to false.
+  def translated? = !translation.nil?
+
+  def empty? = core.match?(BLANK)
+
+  # Untranslated hands back the bytes it was cut from; a translation is text, so it is encoded as markup on the way out.
+  def render
+    "#{@leading}#{translated? ? escaped_translation : @body}#{@trailing}"
+  end
+
+  private
+
+  # @body already carries this same escape from Passage; without it, Passage's one shared restore pass would
+  # read a translated `&lt;` as a source document's own bare `<` and hand back markup nobody asked for.
+  def escaped_translation
+    TranslationDiff::Markup.escape_bare_angles(TranslationDiff::Markup.encode_translation(translation))
+  end
+end