translation_diff 1.0.0

data/lib/translation_diff/languages.rb

@@ -0,0 +1,30 @@
+# What each provider translates, captured from the vendor and shipped; unknown means no opinion, never a refusal.
+module TranslationDiff::Languages
+  DIRECTORY = File.expand_path("../../data/languages", __dir__).freeze
+  # Derived from the directory itself: shipping a new file makes it load without editing this list too.
+  SHIPPED = Dir.children(DIRECTORY).grep(/\.json\z/).map { |file| File.basename(file, ".json").to_sym }.sort.freeze
+  # Amazon needs AWS credentials most maintainers lack; LibreTranslate's list is one private instance's own.
+  NOT_SHIPPED = %i[amazon libretranslate].freeze
+
+  class << self
+    # nil, not false: a provider we ship no data for must never refuse a pair.
+    def supports?(provider, from:, to:)
+      set = self.for(provider)
+      return nil if set.nil? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+
+      set.supports_source?(from) && set.supports_target?(to)
+    end
+
+    def for(provider)
+      name = provider.to_s
+      return nil unless SHIPPED.include?(name.to_sym)
+
+      sets[name] ||= Set.load(File.join(DIRECTORY, "#{name}.json"))
+    end
+
+    private
+
+    # Loaded on first use: six JSON files read at require time would slow every application that never validates.
+    def sets = @sets ||= {}
+  end
+end

data/lib/translation_diff/leaves.rb

@@ -0,0 +1,22 @@
+# The two things this pipeline has always promised about a caller's structure that Document deliberately does not:
+# a nested nil comes back as the empty string, and the size of a document is every leaf in it, translatable or not.
+module TranslationDiff::Leaves
+  # Document hands every non-String leaf straight back, which is the honest behaviour for a general structural map.
+  # Answering a nested nil with "" is the pipeline's own promise, so it is made here rather than there.
+  def self.collapse_nils(node)
+    case node
+    when Hash then node.to_h { |key, value| [key, collapse_nils(value)] }
+    when Array then node.map { |value| collapse_nils(value) }
+    when nil then ""
+    else node
+    end
+  end
+
+  # Every leaf the caller wrote, whatever its type: the number a `translate` payload reports as `values`.
+  def self.count(node)
+    return node.each_value.sum { |value| count(value) } if node.is_a?(Hash)
+    return node.sum { |value| count(value) } if node.is_a?(Array)
+
+    1
+  end
+end

data/lib/translation_diff/markup.rb

@@ -0,0 +1,85 @@
+# Entity references, and a `<` that opens no tag: the two places a document's text is not the text `ox` reports.
+module TranslationDiff::Markup
+  # Escaping a lone `<` is a workaround around `ox`, not a fix of it: the real fix is our own lexer, and out of scope.
+
+  # A `<` opens a tag only when an element name, a closing name, a declaration or an instruction follows it.
+  TAG_OPENER = %r{[A-Za-z!?]|/[A-Za-z]}
+
+  # The two characters escaping has to move: a lone `<`, and an `&` that would read as an escape this module wrote.
+  AMBIGUOUS = /&(?=(?:amp;)*lt;)|<(?!#{TAG_OPENER})/
+
+  # `&lt;` was a lone `<`; every further `amp;` is a level the source itself wrote and escaping pushed up by one.
+  ESCAPED_ANGLE = /&((?:amp;)*)lt;/
+
+  # The bargain: an untranslated segment renders byte-exact, a translated one renders equivalent HTML, not equal bytes.
+
+  # Named and numeric alike, so nothing an `&` opens survives to be escaped again and rendered as its own spelling.
+  DECODABLE = /&(?:[A-Za-z][A-Za-z0-9]*|#\d+|#[xX]\h+);/
+
+  # Which of the two decoders an entity belongs to: Ox knows every HTML5 name, CGI knows both numeric forms.
+  NAMED = /\A&([A-Za-z][A-Za-z0-9]*);\z/
+
+  # Only the two characters that are unsafe in HTML text; every other decoded character is left as the character it is.
+  ENCODED = { "&" => "&amp;", "<" => "&lt;" }.freeze
+
+  ENCODABLE = /[&<]/
+
+  # Hands back markup `ox` can parse: same document, with every lone `<` written as the entity it should have been.
+  def self.escape_bare_angles(source)
+    source.gsub(AMBIGUOUS) { |ambiguous| ambiguous == "&" ? "&amp;" : "&lt;" }
+  end
+
+  # The exact inverse: one `amp;` off every escaped angle, and the angles with none left were the lone ones.
+  def self.restore_bare_angles(rendered)
+    rendered.gsub(ESCAPED_ANGLE) do
+      levels = Regexp.last_match(1)
+      levels.empty? ? "<" : "&#{levels.delete_prefix('amp;')}lt;"
+    end
+  end
+
+  # What a provider is sent is text, so it gets the characters; one left-to-right pass, so nothing is decoded twice.
+  def self.decode_entities(text) = text.gsub(DECODABLE) { |entity| decoded(entity) }
+
+  # An entity neither decoder knows stays as it arrived, and so does a surrogate: that decodes to invalid UTF-8.
+  def self.decoded(entity)
+    name = entity[NAMED, 1]
+    plain = name ? named(name) : CGI.unescapeHTML(entity)
+    plain.valid_encoding? ? plain : entity
+  end
+
+  # A document repeats the same handful of names, and only a name that resolved is kept, so the table cannot be grown.
+  def self.named(name) = resolved[name] || resolve(name)
+
+  def self.resolved = @resolved ||= {}
+
+  # One well-formed entity alone in an element is the only input Ox decodes safely -- prose with a lone `&` raises.
+  def self.resolve(name)
+    entity = "&#{name};"
+    resolver = Resolver.new
+    Ox.sax_html(resolver, StringIO.new("<e>#{entity}</e>"))
+    return entity if resolver.text.nil? || resolver.text == entity
+
+    resolved[name] = resolver.text
+  rescue StandardError
+    entity
+  end
+
+  # What a document renders is markup, so text that changed is made safe again -- and only where it is unsafe.
+  def self.encode_entities(text) = text.gsub(ENCODABLE, ENCODED)
+
+  # An entity the round trip already produced must not be escaped a second time, and a `<` shaped like a tag is
+  # trusted the same way a source tag already is -- everything else a provider sent back is untrusted new text.
+  TRANSLATED_ENCODABLE = /&(?:amp|lt|gt);|&|<(?!#{TAG_OPENER})/
+
+  # What a translation renders as: unlike #encode_entities, this leaves a provider's own reproduced tags alone.
+  def self.encode_translation(text)
+    text.gsub(TRANSLATED_ENCODABLE) { |match| match.length == 1 ? ENCODED[match] : match }
+  end
+
+  # Ox hands back the decoded text of the one element it was given; a name it does not know arrives as the text it was.
+  class Resolver < Ox::Sax
+    attr_reader :text
+
+    def value(value) = @text = value.as_s
+  end
+end

data/lib/translation_diff/passage.rb

@@ -0,0 +1,149 @@
+# A source document as markup and prose: the markup kept as found, the prose cut into segments a provider can take.
+class TranslationDiff::Passage
+  attr_reader :fragments
+
+  # The source is scanned with every lone `<` escaped, so the offsets, the slices and the render all agree on it.
+  # opaque_elements defaults to the live config, read here rather than memoised, so a runtime change takes effect
+  # without a caller that only ever passes segmenter and language having to be touched.
+  def initialize(source, segmenter:, language: nil, opaque_elements: TranslationDiff.config.opaque_elements)
+    @source = TranslationDiff::Markup.escape_bare_angles(source)
+    @segmenter = segmenter
+    @language = language
+    @fragments = Scanner.new(@source, opaque_elements: opaque_elements).runs.map { |run| fragment(run) }
+  end
+
+  # The translatable sentences, in document order; the empty ones are whitespace a provider has no use for.
+  def segments = fragments.flat_map(&:segments)
+
+  # Entities are a segment's business, so the only thing left to undo here is the escape this class put in.
+  def render
+    TranslationDiff::Markup.restore_bare_angles(fragments.map(&:render).join)
+  end
+
+  private
+
+  # Every fragment is a slice of the source, never a rebuilt string; that is what makes an untranslated render exact.
+  def fragment(run)
+    from, to, prose = run
+    slice = @source.byteslice(from, to - from)
+    return TranslationDiff::Fragment.markup(slice) unless prose
+
+    TranslationDiff::Fragment.prose(slice, segmenter: @segmenter, language: @language)
+  end
+
+  # Ox reports a byte position for every construct it sees; recording those is what lets rendering slice the source.
+  class Scanner < Ox::Sax
+    # Providers honour this class themselves under the HTML mode this gem sends, so the element must reach them whole.
+    PROTECTED = "notranslate".freeze
+
+    OPENING_ANGLE = "<".ord
+
+    # Where a run begins and whether it is prose; prose is set after the fact when an element claims protection.
+    Mark = Struct.new(:offset, :prose)
+
+    # Ox reports positions only to a handler that already has the ivar, so @pos exists before parsing starts.
+    # opaque_elements is a caller-supplied set of element names, so it is normalised here rather than trusted as given.
+    def initialize(source, opaque_elements:)
+      super()
+      @source = source
+      @opaque = opaque_elements.map { |element| element.to_s.downcase.to_sym }
+      @pos = 0
+      @marks = []
+      @protected_depth = 0
+      @opaque_depth = 0
+      @opaque_bump = false
+      @pending = nil
+    end
+
+    # Triples of [first byte, last byte + 1, prose?], contiguous, covering the source exactly once.
+    def runs
+      Ox.sax_html(self, StringIO.new(@source))
+      merge(bounds)
+    end
+
+    # Protection beats opacity on purpose: a caller wrapping a subtree asked for it to be passed through as it is.
+    # @opaque_bump remembers whether *this* element is the one that raised @opaque_depth, so attr can undo exactly
+    # that increment if the element turns out to be protected -- its own end_element never gets the chance to.
+    def start_element(name)
+      return @protected_depth += 1 if @protected_depth.positive?
+
+      @opaque_bump = @opaque_depth.positive? || @opaque.include?(name.to_s.downcase.to_sym)
+      @opaque_depth += 1 if @opaque_bump
+      @pending = mark(prose: false)
+    end
+
+    # Attributes arrive straight after their own start element, so @pending is that element and never another.
+    # A protected element's own end_element takes the protected branch and never reaches the opaque decrement, so
+    # an opaque_depth this element raised has to be given back here or it would outlive the element that raised it.
+    def attr(name, value)
+      return unless @pending && protection?(name, value)
+
+      @pending.prose = true
+      @opaque_depth -= 1 if @opaque_bump
+      @protected_depth = 1
+      @pending = nil
+    end
+
+    def end_element(_name)
+      return @protected_depth -= 1 if @protected_depth.positive?
+
+      @opaque_depth -= 1 if @opaque_depth.positive?
+      record(prose: false)
+    end
+
+    def value(_value) = record(prose: @opaque_depth.zero?)
+
+    def comment(_content) = record(prose: false)
+
+    def cdata(_content) = record(prose: false)
+
+    def doctype(_content) = record(prose: false)
+
+    def instruct(_target) = record(prose: false)
+
+    private
+
+    # Ox hands back names exactly as written, never lowercased, so both comparisons here are case-insensitive.
+    def protection?(name, value)
+      name.to_s.casecmp?("class") && value.split.include?(PROTECTED)
+    end
+
+    # Everything inside a protected element belongs to the run that element opened, so it records nothing of its own.
+    def record(prose:)
+      @pending = nil
+      return if @protected_depth.positive?
+
+      mark(prose: prose)
+    end
+
+    # Ox counts from one. A markup mark that does not land on a "<" is a tag Ox implied, not one the source holds.
+    def mark(prose:)
+      offset = @pos - 1
+      return nil if offset.negative? || (!prose && @source.getbyte(offset) != OPENING_ANGLE)
+
+      Mark.new(offset, prose).tap { |recorded| @marks << recorded }
+    end
+
+    # Each mark owns the source as far as the next one begins, and the last one owns whatever is left.
+    def bounds
+      marks = ordered
+      finishes = marks.drop(1).map(&:offset) << @source.bytesize
+      marks.zip(finishes).map { |mark, finish| [mark.offset, finish, mark.prose] }
+    end
+
+    # Ox skips the whitespace ahead of the first construct it reports, so a prose run is seeded where it starts.
+    def ordered
+      sorted = @marks.sort_by.with_index { |mark, index| [mark.offset, index] }
+      return sorted if sorted.first&.offset&.zero?
+
+      sorted.unshift(Mark.new(0, true))
+    end
+
+    # Adjacent prose has to become one run, or a notranslate element would be cut off from the sentence it sits in.
+    def merge(spans)
+      spans.reject { |from, to, _prose| from == to }
+           .chunk_while { |before, after| before.last == after.last }
+           .map { |chunk| [chunk.first[0], chunk.last[1], chunk.first[2]] }
+    end
+  end
+end

data/lib/translation_diff/preview.rb

@@ -0,0 +1,3 @@
+# What a #translate call would do without doing it: sentences it would send, sentences already cached, their
+# size, and characters -- the total the translate event itself reports, the denominator sendable_characters needs.
+TranslationDiff::Preview = Data.define(:sendable_sentences, :cached_sentences, :sendable_characters, :characters)

data/lib/translation_diff/previewer.rb

@@ -0,0 +1,78 @@
+# Answers what #translate would send and find cached, using the same segmenter, cache key and provider
+# resolution translate uses -- without calling the provider or writing anything. Detection is a paid request
+# this method never makes, so a nil `from:` for a provider that must detect the language is refused, not guessed at.
+class TranslationDiff::Previewer
+  # Its own class, so rescuing a preview that cannot be answered cannot also swallow a cache or provider failure.
+  class Error < TranslationDiff::Error; end
+
+  include TranslationDiff::CallPreparation
+
+  EMPTY = TranslationDiff::Preview.new(sendable_sentences: 0, cached_sentences: 0, sendable_characters: 0,
+                                       characters: 0).freeze
+
+  attr_reader :config
+
+  # `provider:`, `config:` and `assume_supported:` are reserved, exactly as they are for Translator#initialize.
+  def initialize(values, from: nil, to: nil, provider: nil, config: nil, assume_supported: false, **options)
+    raise ArgumentError, "a preview needs a target language: pass `to:` a language code." if to.nil?
+
+    @values = values
+    @from = from
+    @to = to
+    @options = options
+    @config = config || TranslationDiff.config
+    @requested_provider = provider
+    @assume_supported = assume_supported
+  end
+
+  def call
+    segments = document_segments
+    return EMPTY if segments.empty? || same_language?(@from)
+
+    provider = resolve_provider
+    from = resolve_source_language(provider)
+    return EMPTY if same_language?(from)
+
+    preview_for(provider, from, segments)
+  end
+
+  private
+
+  def document_segments
+    document = TranslationDiff::Document.new(TranslationDiff::Leaves.collapse_nils(@values))
+    document.strings.flat_map { |string| passage(string).segments }.reject(&:empty?)
+  end
+
+  # Same resolution Translator#call uses: a name to build, an object to use as it is, or the configured one.
+  def resolve_provider = TranslationDiff::Providers.resolve(@requested_provider, config)
+
+  # `from:` given means the pair is already known, so it is validated once; `from:` nil needs a detection this
+  # method never pays for, so it stops here instead of guessing what a paid request would have answered.
+  def resolve_source_language(provider)
+    return @from.tap { |from| ensure_supported!(provider, from) } unless @from.nil?
+
+    ensure_supported!(provider, nil)
+    raise_undetectable!(provider)
+  end
+
+  # A provider that cannot detect at all is refused with the same message translate uses; one that could but
+  # would cost a paid request is refused too -- preview never spends money to answer what it would send.
+  def raise_undetectable!(provider)
+    ensure_detects_language!(provider, Error, "previewing")
+
+    raise Error, "TranslationDiff.preview cannot detect the source language for #{provider.cache_key} " \
+                 "without a paid request: pass `from:` explicitly."
+  end
+
+  # characters is the denominator: the same total the translate event itself reports, present even when every
+  # segment is already cached and sendable_characters alone would leave nothing to divide by.
+  def preview_for(provider, from, segments)
+    misses = fill(provider, from, segments)
+    TranslationDiff::Preview.new(sendable_sentences: misses.size, cached_sentences: segments.size - misses.size,
+                                 sendable_characters: misses.sum { |segment| segment.core.size },
+                                 characters: segments.sum { |segment| segment.core.size })
+  end
+
+  # Reads the store through the same SentenceCache#fill translate uses; nothing here ever calls #store.
+  def fill(provider, from, segments) = cache_for(provider, from).fill(segments)
+end

data/lib/translation_diff/provider.rb

@@ -0,0 +1,91 @@
+# Connects this library to one translation service; knows nothing about HTTP itself -- that's HTTPProvider.
+class TranslationDiff::Provider
+  # A subclass that forgets to declare capabilities under-promises, not over-promises: smaller batches, not silent risk.
+  DEFAULT_CAPABILITIES = TranslationDiff::Capabilities.new(
+    max_request_size: 1_000, max_batch_size: 1, max_text_size: nil,
+    html: :none, notranslate: false, detects_language: false, reports_billing: false
+  ).freeze
+
+  # A bare alphabetic code is cased the way the vendor documents; anything with a subtag is left alone.
+  BARE_LANGUAGE_CODE = /\A[A-Za-z]{2,3}\z/
+
+  # Stamped by the registry at build time. See #cache_key.
+  attr_accessor :name
+
+  attr_reader :config
+
+  def initialize(config)
+    @config = config
+    ensure_configured!
+  end
+
+  # Callers write whichever casing their old configuration used; the vendor gets the one it documents.
+  def language(value)
+    code = value.to_s
+    return nil if code.empty?
+    return code unless code.match?(BARE_LANGUAGE_CODE)
+
+    self.class.language_case == :upcase ? code.upcase : code.downcase
+  end
+
+  # nil means the provider reported no billing at all; 0 means it reported zero. Both are claims.
+  def billed_characters(reported)
+    values = reported.compact
+    values.empty? ? nil : values.sum
+  end
+
+  # Never the default: a provider holds the configuration, so the default renders every key it holds.
+  def inspect = "#<#{self.class.name} name=#{name.inspect} config=#{config.inspect}>"
+
+  def translate(_request) = raise NotImplementedError, "#{self.class} must implement #translate"
+
+  # Only called when `capabilities.detects_language?`.
+  def detect(_text) = raise NotImplementedError, "#{self.class} must implement #detect"
+
+  # Only `rake languages:refresh` calls this; a provider that cannot answer is skipped, not failed.
+  def languages = raise NotImplementedError, "#{self.class} cannot fetch its languages"
+
+  # The full URL #languages fetches; a provider whose fetch has more than one shape narrows this further.
+  def languages_endpoint = respond_to?(:api_base) ? api_base.to_s : ""
+
+  # Raising when never stamped, rather than falling back to "", is deliberate: "" would merge namespaces silently.
+  def cache_key
+    return name.to_s unless name.nil?
+
+    raise TranslationDiff::Error,
+          "#{self.class} has no cache key: it was instantiated directly instead of being " \
+          "built through the registry. Build it through TranslationDiff::Providers.build, " \
+          "or give #{self.class} its own #cache_key."
+  end
+
+  class << self
+    # The casing this vendor documents for a bare code. DeepL upcases; everyone else takes lower case.
+    def language_case = :downcase
+
+    def configuration_options = []
+
+    # Overridable: a provider whose credential is named unusually says so rather than leaking it.
+    def sensitive_options
+      configuration_options.flat_map { |o| o.is_a?(Hash) ? o.keys : [o] }
+                           .select { |key| TranslationDiff::Redaction.sensitive?(key) }
+    end
+
+    # Checked once, at build time, so a caller learns what to set before a vendor's own exception does.
+    def configuration_requirements = []
+
+    def capabilities = DEFAULT_CAPABILITIES
+
+    def build(config) = new(config)
+  end
+
+  private
+
+  def ensure_configured!
+    missing = self.class.configuration_requirements.reject { |key| config.public_send(key) }
+    return if missing.empty?
+
+    raise TranslationDiff::ConfigurationError,
+          "Provider #{self.class} is missing #{missing.join(', ')}. " \
+          "Set #{missing.size == 1 ? 'it' : 'them'} in TranslationDiff.configure."
+  end
+end

data/lib/translation_diff/providers/amazon.rb

@@ -0,0 +1,126 @@
+# Amazon Translate: no batch API (one text per call), no HTML mode, and requests are signed, not just headed.
+class TranslationDiff::Providers::Amazon < TranslationDiff::HTTPProvider
+  SERVICE = "translate".freeze
+  TARGET = "AWSShineFrontendService_20170701.TranslateText".freeze
+  LIST_LANGUAGES = "AWSShineFrontendService_20170701.ListLanguages".freeze
+  CONTENT_TYPE = "application/x-amz-json-1.1".freeze
+
+  # Amazon's own way of asking for detection; reaches Comprehend under the hood, in regions that have it.
+  AUTO = "auto".freeze
+
+  def self.capabilities
+    TranslationDiff::Capabilities.new(
+      max_request_size: 10_000, max_batch_size: 1, max_text_size: 10_000,
+      html: :none, notranslate: false, detects_language: true, reports_billing: false
+    )
+  end
+
+  # Deliberately no environment fallback: this library does not implement the AWS credential chain.
+  def self.configuration_options
+    %i[amazon_access_key_id amazon_secret_access_key amazon_session_token
+       amazon_region amazon_api_base]
+  end
+
+  def self.configuration_requirements
+    %i[amazon_access_key_id amazon_secret_access_key amazon_region]
+  end
+
+  def api_base = config.amazon_api_base || "https://#{SERVICE}.#{config.amazon_region}.amazonaws.com"
+
+  # Detected language is the first one Amazon reported: every text in a chunk shares a source language.
+  def translate(request)
+    detected = nil
+    texts = request.texts.map do |text|
+      body = call(text, request)
+      detected ||= body["SourceLanguageCode"]&.downcase
+      body["TranslatedText"]
+    end
+
+    TranslationDiff::Translation::Response.build(
+      request: request, texts: texts, detected_source: detected,
+      usage: TranslationDiff::Translation::Usage.new(characters: request.texts.sum(&:size))
+    )
+  end
+
+  def detect(text)
+    call(text, TranslationDiff::Translation::Request.new(texts: [text], from: nil, to: "en"))
+      .fetch("SourceLanguageCode", nil)&.downcase
+  end
+
+  # ListLanguages is a signed POST like every other Amazon call; the list serves both directions.
+  def languages
+    body = post_signed(JSON.generate({}), target: LIST_LANGUAGES).body
+    codes = Array(body["Languages"]).map { |entry| entry["LanguageCode"] }
+
+    { source: codes, target: codes }
+  end
+
+  # There is no distinct languages URL: every Amazon call, ListLanguages included, is a signed POST to the root.
+  def languages_endpoint = "#{api_base}/"
+
+  private
+
+  def call(text, request)
+    payload = request.options.transform_keys(&:to_s).merge(
+      "Text" => text,
+      "SourceLanguageCode" => request.from.nil? ? AUTO : language(request.from),
+      "TargetLanguageCode" => language(request.to)
+    )
+
+    post_signed(JSON.generate(payload)).body
+  end
+
+  def post_signed(body, target: TARGET)
+    raw = connection.post("/", body, signed_headers(body, target: target))
+    response = decoded_response(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
+
+  # Reuses the base's own decoding rather than a second, Faraday-middleware-based path (see HTTPProvider#decode).
+  def decoded_response(raw) = Decoded.new(status: raw.status, headers: raw.headers, body: decode(raw))
+
+  # Required here, not at load time, so an application using another provider never needs it installed.
+  def signer
+    @signer ||= begin
+      require_sigv4
+      Aws::Sigv4::Signer.new(
+        service: SERVICE, region: config.amazon_region,
+        access_key_id: config.amazon_access_key_id,
+        secret_access_key: config.amazon_secret_access_key,
+        session_token: config.amazon_session_token
+      )
+    end
+  end
+
+  def require_sigv4
+    require "aws-sigv4"
+  rescue LoadError
+    raise TranslationDiff::Error,
+          "provider is :amazon but the `aws-sigv4` gem is not available. " \
+          'Add `gem "aws-sigv4"` to your Gemfile.'
+  end
+
+  def signed_headers(body, target: TARGET)
+    signature = signer.sign_request(
+      http_method: "POST", url: "#{api_base}/", body: body,
+      headers: { "Content-Type" => CONTENT_TYPE, "X-Amz-Target" => target }
+    )
+
+    signature.headers.merge("Content-Type" => CONTENT_TYPE, "X-Amz-Target" => target)
+  end
+
+  # The signature covers the body exactly as sent, so this omits `faraday.request :json` unlike the base class.
+  def build_connection(&)
+    Faraday.new(url: api_base, headers: headers) do |faraday|
+      faraday.request :retry, retry_options
+      adapt(faraday, &)
+      apply_timeouts(faraday)
+    end
+  end
+end
+
+TranslationDiff::Providers.register(:amazon, TranslationDiff::Providers::Amazon)

data/lib/translation_diff/providers/azure.rb

@@ -0,0 +1,78 @@
+# Azure AI Translator, REST v3.0: cheapest per character, most generous per request (1,000 strings/50,000 chars).
+class TranslationDiff::Providers::Azure < TranslationDiff::HTTPProvider
+  HOST = "https://api.cognitive.microsofttranslator.com".freeze
+  API_VERSION = "3.0".freeze
+
+  # Azure spells HTML handling `textType`, and under it honours `class=notranslate` like DeepL and Google do.
+  DEFAULT_TEXT_TYPE = "html".freeze
+
+  def self.capabilities
+    TranslationDiff::Capabilities.new(
+      max_request_size: 50_000, max_batch_size: 1_000, max_text_size: 50_000,
+      html: :textType, notranslate: true, detects_language: true, reports_billing: true
+    )
+  end
+
+  def self.configuration_options = %i[azure_api_key azure_region azure_api_base]
+  def self.configuration_requirements = %i[azure_api_key]
+
+  def api_base = config.azure_api_base || HOST
+
+  # A multi-service resource needs the region header; a single-service one rejects nothing without it.
+  def headers
+    { "Ocp-Apim-Subscription-Key" => config.azure_api_key.to_s }
+      .tap { |h| h["Ocp-Apim-Subscription-Region"] = config.azure_region if config.azure_region }
+  end
+
+  # Azure takes the language pair in the query string, so the URL is built per request, not a constant.
+  def translate_url = "translate"
+
+  def translate(request)
+    response = post(url_for(request), render_translate_payload(request))
+    parse_translate_response(response.body, response.headers, request)
+  end
+
+  def render_translate_payload(request) = request.texts.map { |text| { Text: text } }
+
+  def parse_translate_response(body, headers, request)
+    results = Array(body)
+
+    TranslationDiff::Translation::Response.build(
+      request: request,
+      texts: results.map { |result| result.dig("translations", 0, "text") },
+      detected_source: results.first&.dig("detectedLanguage", "language")&.downcase,
+      usage: TranslationDiff::Translation::Usage.new(
+        characters: request.texts.sum(&:size),
+        billed_characters: headers["x-metered-usage"]&.to_i
+      )
+    )
+  end
+
+  def detect(text)
+    response = post("detect?api-version=#{API_VERSION}", [{ Text: text }])
+    response.body.dig(0, "language")&.downcase
+  end
+
+  # Azure's own docs mark this endpoint public, but this provider still requires a key to be built at all.
+  def languages
+    codes = Array(get("languages?api-version=#{API_VERSION}&scope=translation").body["translation"]&.keys)
+
+    { source: codes, target: codes }
+  end
+
+  def languages_endpoint = "#{api_base}/languages?api-version=#{API_VERSION}&scope=translation"
+
+  private
+
+  # Defaults, then caller options, then mandatory fields: a caller must not displace the language pair.
+  def url_for(request)
+    params = { "textType" => DEFAULT_TEXT_TYPE }
+             .merge(request.options.transform_keys(&:to_s))
+             .merge("api-version" => API_VERSION, "to" => language(request.to))
+    params["from"] = language(request.from) unless request.from.nil?
+
+    "#{translate_url}?#{URI.encode_www_form(params)}"
+  end
+end
+
+TranslationDiff::Providers.register(:azure, TranslationDiff::Providers::Azure)