i18n-keyless-rails 3.5.0

data/lib/i18n_keyless/api_client.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module I18nKeyless
+  # The three routes of the i18n-keyless wire format this gem uses, with the
+  # network policy of the SDKs (conformance/vectors/backoff.json and
+  # retry-decision.json): a per-attempt timeout, three attempts with fixed
+  # backoff delays on a network error, a timeout, a 429, a 5xx or an unparsable
+  # 200 body; no retry on any other status; nothing ever raised.
+  #
+  # Usage analytics (POST /translate/last-used-translations) follow the node
+  # SDK: the cumulative map is POSTed, at most once every 10 s.
+  class ApiClient
+    # Sent as the `Version` header (the wire dialect: v3 language codes).
+    VERSION = I18nKeyless::VERSION
+
+    # Sent as the `sdk` header. `rails` is registered on the API as a server
+    # label, counted like `node`: a server sends no `unique_id`, the API counts
+    # it by its source connection, which the client cannot shape.
+    SDK = "rails"
+
+    DEFAULT_URL = "https://api.i18n-keyless.com"
+
+    ACTION_PARSE_BODY = "parse-body"
+    ACTION_NOT_MODIFIED = "not-modified"
+    ACTION_FAIL = "fail"
+    ACTION_RETRY = "retry"
+
+    # A network error or a timeout is transient and retried; any other
+    # exception ends the call now.
+    TRANSIENT_ERRORS = [
+      Timeout::Error, SocketError, SystemCallError, EOFError, IOError, OpenSSL::SSL::SSLError
+    ].freeze
+
+    Dictionary = Struct.new(:ok, :not_modified, :translations, :etag, :error, keyword_init: true)
+    UsageResult = Struct.new(:ok, :sent, :error, keyword_init: true)
+    Outcome = Struct.new(:action, :error, :response, :json, keyword_init: true)
+
+    attr_reader :api_key, :api_url, :timeout, :retry_delays, :concurrency
+    # The backoff sleep, `->(ms) { sleep(ms / 1000.0) }`. Tests replace it.
+    attr_accessor :sleeper
+
+    # @param retry_delays [Array<Integer>] milliseconds between attempts (two entries: three attempts)
+    # @param sleeper [#call] receives a number of milliseconds; replaced in tests
+    def initialize(api_key:, api_url: DEFAULT_URL, timeout: 10, retry_delays: [500, 1500], concurrency: 30,
+                   logger: nil, sleeper: nil)
+      @api_key = api_key.to_s
+      @api_url = api_url.to_s.sub(%r{/+\z}, "")
+      @api_url = DEFAULT_URL if @api_url.empty?
+      @timeout = timeout
+      @retry_delays = retry_delays.map(&:to_i)
+      @concurrency = [concurrency.to_i, 1].max
+      @logger = logger
+      @sleeper = sleeper || ->(ms) { sleep(ms / 1000.0) }
+    end
+
+    def max_attempts
+      retry_delays.length + 1
+    end
+
+    # The delay after a failed attempt (1-based), or nil when there is no next attempt.
+    def delay_after(failed_attempt)
+      retry_delays[failed_attempt - 1]
+    end
+
+    # GET /translate/{lang}: the whole dictionary of one language, or a 304
+    # when the ETag still matches.
+    def fetch_dictionary(lang, namespace, etag, last_refresh = "")
+      result = Dictionary.new(ok: false, not_modified: false, translations: {}, etag: nil, error: nil)
+      url = dictionary_url(lang, namespace, etag, last_refresh)
+      outcome = call { request(:get, url, etag: etag) }
+      if outcome.action == ACTION_NOT_MODIFIED
+        result.ok = true
+        result.not_modified = true
+        return result
+      end
+      if outcome.action != ACTION_PARSE_BODY
+        result.error = outcome.error
+        warn("fetch all translations error: #{outcome.error}")
+        return result
+      end
+      dictionary_from(outcome.json, outcome.response, result)
+    end
+
+    # POST /translate/last-used-translations: the cumulative usage map. An
+    # empty map is never sent. Same network policy as every other call.
+    def send_usage(primary, usage_by_namespace)
+      return UsageResult.new(ok: false, sent: false, error: nil) if usage_by_namespace.empty? || api_key.empty?
+
+      body = { "primaryLanguage" => primary, "translationsUsageByNamespace" => usage_by_namespace }
+      outcome = call { request(:post, "#{api_url}/translate/last-used-translations", body: body) }
+      if outcome.action != ACTION_PARSE_BODY
+        warn("send translations usage error: #{outcome.error}")
+        return UsageResult.new(ok: false, sent: true, error: outcome.error)
+      end
+      json = outcome.json
+      warn(json["message"].to_s) if json["message"].to_s != ""
+      unless json["ok"]
+        error = (json["error"] || "not ok").to_s
+        warn("send translations usage error: #{error}")
+        return UsageResult.new(ok: false, sent: true, error: error)
+      end
+      UsageResult.new(ok: true, sent: true, error: nil)
+    end
+
+    # POST /translate for every miss, at most `concurrency` at a time. Failed
+    # attempts are retried together, one backoff sleep per round.
+    #
+    # @param misses [Array<Miss>]
+    # @param languages [Array<String>] the configured languages (the primary is added)
+    # @return [Hash{String => Hash{String => String}, nil}] translations by language, keyed by miss id; nil when the call failed
+    def translate(misses, primary, languages)
+      results = {}
+      pending = {}
+      misses.each do |miss|
+        pending[miss.id] = miss
+        results[miss.id] = nil
+      end
+      errors = {}
+      attempt = 1
+      while attempt <= max_attempts && !pending.empty?
+        retry_next = {}
+        pending.values.each_slice(concurrency) do |chunk|
+          responses = post_chunk(chunk, primary, languages)
+          chunk.each do |miss|
+            outcome = outcome_of(responses.fetch(miss.id) { RuntimeError.new("no response") })
+            errors[miss.id] = outcome.error
+            if outcome.action == ACTION_PARSE_BODY
+              json = self.class.decode_json(outcome.response)
+              if json.nil?
+                errors[miss.id] = "invalid JSON"
+                retry_next[miss.id] = miss
+                next
+              end
+              results[miss.id] = translation_from(json, miss)
+              next
+            end
+            if outcome.action == ACTION_RETRY
+              retry_next[miss.id] = miss
+              next
+            end
+            # fail (or a 304 that makes no sense on a POST): give up on this miss now
+            warn("translate error for \"#{miss.key}\": #{outcome.error}")
+          end
+        end
+        pending = retry_next
+        sleep_after(attempt) unless pending.empty?
+        attempt += 1
+      end
+      pending.each_value do |miss|
+        warn("translate error for \"#{miss.key}\": #{errors[miss.id] || 'unknown error'}")
+      end
+      results
+    end
+
+    # The body of one POST /translate (conformance/vectors/translate-request.json).
+    def translate_body(miss, primary, languages)
+      body = {
+        "key" => miss.key,
+        "context" => miss.context,
+        # The default namespace is omitted on the wire, like the SDKs do.
+        "namespace" => miss.namespace == Translator::DEFAULT_NAMESPACE ? nil : miss.namespace,
+        # The configured list plus the primary, never the locale that missed: the
+        # API stores this list as the project's languages (the react SDK sends its
+        # required `supported` list the same way).
+        "languages" => (Array(languages) + [primary]).uniq,
+        "primaryLanguage" => primary
+      }
+      body.reject { |_, value| value.nil? || value == "" }
+    end
+
+    # What one attempt's answer does to the call. Statuses follow
+    # conformance/vectors/retry-decision.json; `error` is the reason phrase
+    # when non-empty, else `HTTP <code>`.
+    def self.decide(status, reason = nil)
+      status = status.to_i
+      error = reason.to_s.empty? ? "HTTP #{status}" : reason.to_s
+      return Outcome.new(action: ACTION_PARSE_BODY, error: "") if status == 200
+      return Outcome.new(action: ACTION_NOT_MODIFIED, error: "") if status == 304
+      return Outcome.new(action: ACTION_RETRY, error: error) if status == 429 || status >= 500
+
+      Outcome.new(action: ACTION_FAIL, error: error)
+    end
+
+    # A network error or a timeout is transient; the SDKs spell a timeout `timeout`.
+    def self.error_for(exception)
+      return "timeout" if exception.is_a?(Timeout::Error) || exception.message =~ /timed out|timeout/i
+
+      message = exception.message.to_s
+      message.empty? ? exception.class.name : message
+    end
+
+    def self.transient?(exception)
+      TRANSIENT_ERRORS.any? { |klass| exception.is_a?(klass) }
+    end
+
+    def self.decode_json(response)
+      json = JSON.parse(response.body.to_s)
+      json.is_a?(Hash) ? json : nil
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    # The URL of a bulk fetch (conformance/vectors/dictionary-request.json).
+    # With an ETag in hand, freshness travels in If-None-Match and the URL
+    # stays stable, so shared HTTP caches can hold it. Without one, the delta
+    # cursor travels as `last_refresh`: this gem keeps no cursor and sends it
+    # empty, which asks for the whole dictionary.
+    def dictionary_url(lang, namespace, etag, last_refresh = "")
+      # The default namespace is omitted from the query so a plain install
+      # hits the exact same URL as the SDKs.
+      namespace_query = namespace == Translator::DEFAULT_NAMESPACE ? "" : "&namespace=#{encode(namespace)}"
+      query = if etag
+                namespace_query.empty? ? "" : "?#{namespace_query[1..]}"
+              else
+                "?last_refresh=#{last_refresh.nil? ? 'null' : last_refresh}#{namespace_query}"
+              end
+      "#{api_url}/translate/#{lang}#{query}"
+    end
+
+    # The headers every request carries.
+    def headers
+      {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "Authorization" => "Bearer #{api_key}",
+        "Version" => VERSION,
+        "sdk" => SDK
+      }
+    end
+
+    private
+
+    # One call with the shared network policy: up to `max_attempts` attempts,
+    # a backoff sleep after each failed one. Ends with `parse-body` (and the
+    # decoded JSON), `not-modified`, or `fail` with the last error.
+    def call
+      error = ""
+      (1..max_attempts).each do |attempt|
+        outcome = begin
+          outcome_of(yield)
+        rescue Exception => e # rubocop:disable Lint/RescueException -- nothing ever raises out of a translation
+          raise if e.is_a?(NoMemoryError) || e.is_a?(SignalException) || e.is_a?(SystemExit)
+
+          outcome_of(e)
+        end
+        error = outcome.error
+        return outcome if outcome.action == ACTION_NOT_MODIFIED
+
+        if outcome.action == ACTION_PARSE_BODY
+          json = self.class.decode_json(outcome.response)
+          if json
+            outcome.json = json
+            return outcome
+          end
+          # An unparsable 200 body is a failed attempt, retried like a 5xx.
+          outcome.action = ACTION_RETRY
+          error = "invalid JSON"
+        end
+        break if outcome.action == ACTION_FAIL
+
+        sleep_after(attempt)
+      end
+      Outcome.new(action: ACTION_FAIL, error: error, response: nil, json: nil)
+    end
+
+    # @return [Hash{String => Net::HTTPResponse, Exception}] keyed by miss id
+    def post_chunk(chunk, primary, languages)
+      threads = chunk.map do |miss|
+        Thread.new do
+          Thread.current.report_on_exception = false
+          [miss.id, begin
+            request(:post, "#{api_url}/translate", body: translate_body(miss, primary, languages))
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            raise if e.is_a?(NoMemoryError) || e.is_a?(SignalException) || e.is_a?(SystemExit)
+
+            e
+          end]
+        end
+      end
+      threads.to_h(&:value)
+    end
+
+    def outcome_of(answer)
+      if answer.is_a?(Exception)
+        return Outcome.new(
+          action: self.class.transient?(answer) ? ACTION_RETRY : ACTION_FAIL,
+          error: self.class.error_for(answer),
+          response: nil
+        )
+      end
+      outcome = self.class.decide(answer.code, answer.message)
+      outcome.response = answer
+      outcome
+    end
+
+    def dictionary_from(json, response, result)
+      unless json["ok"]
+        result.error = (json["error"] || "not ok").to_s
+        warn("fetch all translations error: #{result.error}")
+        return result
+      end
+      warn(json["message"].to_s) if json["message"].to_s != ""
+      translations = json.dig("data", "translations")
+      result.ok = true
+      result.translations = translations.is_a?(Hash) ? translations.select { |_, v| v.is_a?(String) } : {}
+      etag = response["ETag"].to_s
+      result.etag = etag.empty? ? nil : etag
+      result
+    end
+
+    def translation_from(json, miss)
+      unless json["ok"]
+        warn("translate error for \"#{miss.key}\": #{json['error'] || 'not ok'}")
+        return nil
+      end
+      warn(json["message"].to_s) if json["message"].to_s != ""
+      translation = json.dig("data", "translation")
+      translation.is_a?(Hash) ? translation.select { |_, v| v.is_a?(String) } : {}
+    end
+
+    def request(method, url, body: nil, etag: nil)
+      uri = URI.parse(url)
+      req = method == :get ? Net::HTTP::Get.new(uri) : Net::HTTP::Post.new(uri)
+      headers.each { |name, value| req[name] = value }
+      req["If-None-Match"] = etag if etag
+      req.body = JSON.generate(body) if body
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+      http.start { |connection| connection.request(req) }
+    end
+
+    def encode(value)
+      URI.encode_www_form_component(value).gsub("+", "%20")
+    end
+
+    def sleep_after(failed_attempt)
+      delay = delay_after(failed_attempt)
+      @sleeper.call(delay) if delay && delay.positive?
+    end
+
+    def warn(message)
+      @logger&.warn("i18n-keyless: #{message}")
+    rescue StandardError
+      # Logging must never take a translation down.
+    end
+  end
+end

data/lib/i18n_keyless/backend.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+module I18nKeyless
+  # The I18n backend. Chained AFTER the application's own backend
+  # (`I18n::Backend::Chain.new(I18n.backend, I18nKeyless::Backend.new)`), so a
+  # key found in `config/locales/*.yml` wins and only what the YAML files do
+  # not have reaches the API.
+  #
+  # `I18n.t("Welcome to our app")` therefore resolves through i18n-keyless,
+  # while `I18n.t("users.index.title")` or `t(:hello)` stay Rails keys (see
+  # `I18nKeyless.keyless_key?`) and are never sent.
+  #
+  # `context:` and `namespace:` travel as I18n options:
+  # `t("8 heures", context: "duration")` is stored as `8 heures__duration`.
+  class Backend
+    include I18n::Backend::Base
+
+    def available_locales
+      []
+    end
+
+    def initialized?
+      true
+    end
+
+    def reload!
+      I18nKeyless.translator.reset_loaded! if I18nKeyless.enabled?
+      self
+    end
+
+    def eager_load!
+      self
+    end
+
+    def store_translations(_locale, _data, _options = {}); end
+
+    def translations(*)
+      {}
+    end
+
+    protected
+
+    def lookup(locale, key, scope = [], options = {})
+      return nil unless I18nKeyless.enabled?
+      return nil unless key.is_a?(String) && (scope.nil? || Array(scope).empty?) && I18nKeyless.keyless_key?(key)
+
+      I18nKeyless.translator.lookup(locale.to_s, key, context: options[:context], namespace: options[:namespace])
+    end
+  end
+end

data/lib/i18n_keyless/config.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module I18nKeyless
+  # The configuration, with the same names and defaults as the Laravel port.
+  # Every value is read from the environment first (`I18N_KEYLESS_*`), then
+  # overridden by `I18nKeyless.configure { |c| ... }`.
+  class Config
+    # A key matching this is a Rails key (`hello`, `users.index.title`): it is
+    # left to the YAML files. Everything else is a keyless source string.
+    DEFAULT_RAILS_KEY_PATTERN = /\A[a-z0-9_]+(\.[a-z0-9_]+)*\z/
+
+    FALSE_VALUES = %w[false 0 off no].freeze
+
+    # `false` switches the gem off: Rails behaves as without it.
+    attr_accessor :enabled
+    # Your project's key. Without it the gem stays inactive.
+    attr_accessor :api_key
+    # The official service, or your own backend / proxy speaking the same wire format.
+    attr_accessor :api_url
+    # The language the source strings are written in. Default: I18n.default_locale.
+    attr_accessor :primary
+    # REQUIRED for translation: every language the app serves ("en,fr,es" or an array).
+    attr_accessor :languages
+    # The i18n-keyless namespace of the `t()` strings. Default "default".
+    attr_accessor :namespace
+    # An ActiveSupport::Cache::Store. Default: Rails.cache, else a MemoryStore.
+    attr_accessor :cache
+    # Seconds a dictionary is served without asking the API. Default 3600.
+    attr_accessor :cache_ttl
+    # Prefix of every cache key the gem writes.
+    attr_accessor :cache_prefix
+    # HTTP timeout in seconds, per attempt.
+    attr_accessor :timeout
+    # Backoff in milliseconds between retries: two entries, two retries.
+    attr_accessor :retry
+    # Maximum POST /translate requests in flight at once.
+    attr_accessor :concurrency
+    # Usage analytics (the date each string was last served), like the node SDK.
+    attr_accessor :usage
+    # An ActiveJob queue name: misses are sent from a TranslateMissingKeysJob instead of after the response.
+    attr_accessor :queue
+    # Where warnings go. Default: Rails.logger, else STDERR.
+    attr_accessor :logger
+    # The Rails-key rule (see DEFAULT_RAILS_KEY_PATTERN). `nil`: every string is keyless.
+    attr_accessor :rails_key_pattern
+
+    def initialize(env = ENV)
+      @enabled = truthy?(env.fetch("I18N_KEYLESS_ENABLED", "true"))
+      @api_key = env["I18N_KEYLESS_API_KEY"]
+      @api_url = env["I18N_KEYLESS_API_URL"]
+      @primary = env["I18N_KEYLESS_PRIMARY_LANG"]
+      @languages = env["I18N_KEYLESS_LANGUAGES"]
+      @namespace = env["I18N_KEYLESS_NAMESPACE"]
+      @cache = nil
+      @cache_ttl = Integer(env.fetch("I18N_KEYLESS_CACHE_TTL", 3600), exception: false) || 3600
+      @cache_prefix = "i18n-keyless"
+      @timeout = 10
+      @retry = [500, 1500]
+      @concurrency = 30
+      @usage = truthy?(env.fetch("I18N_KEYLESS_USAGE", "true"))
+      @queue = env["I18N_KEYLESS_QUEUE"]
+      @logger = nil
+      @rails_key_pattern = DEFAULT_RAILS_KEY_PATTERN
+    end
+
+    def enabled?
+      truthy?(enabled) && !api_key.to_s.strip.empty?
+    end
+
+    # The primary language as an i18n-keyless code: the configured one, else
+    # I18n.default_locale mapped, else "en".
+    def resolved_primary
+      Locale.to_lang(primary&.to_s) || Locale.to_lang(I18n.default_locale.to_s) || "en"
+    end
+
+    # The configured languages as i18n-keyless codes, deduplicated. A comma
+    # separated string ("en,fr,es") or an array of locales.
+    def resolved_languages
+      list = languages
+      list = list.split(",") if list.is_a?(String)
+      Array(list).filter_map { |tag| Locale.to_lang(tag.to_s) }.uniq
+    end
+
+    def resolved_api_url
+      url = api_url.to_s.strip.sub(%r{/+\z}, "")
+      url.empty? ? ApiClient::DEFAULT_URL : url
+    end
+
+    def resolved_namespace
+      value = namespace.to_s
+      value.empty? ? Translator::DEFAULT_NAMESPACE : value
+    end
+
+    def resolved_cache
+      return cache if cache
+      return ::Rails.cache if defined?(::Rails) && ::Rails.respond_to?(:cache) && ::Rails.cache
+
+      @memory_store ||= ActiveSupport::Cache::MemoryStore.new
+    end
+
+    def resolved_logger
+      return logger if logger
+      return ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+      @stderr_logger ||= Logger.new($stderr)
+    end
+
+    def resolved_retry
+      Array(self.retry).map(&:to_i)
+    end
+
+    def usage?
+      truthy?(usage)
+    end
+
+    private
+
+    def truthy?(value)
+      return value if value == true || value == false
+      return false if value.nil?
+
+      !FALSE_VALUES.include?(value.to_s.strip.downcase) && !value.to_s.strip.empty?
+    end
+  end
+end

data/lib/i18n_keyless/dictionary_store.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module I18nKeyless
+  # The per-language dictionaries in an ActiveSupport cache store (any: memory,
+  # file, Redis, Memcached, the database), plus the cross-request guard that
+  # keeps one miss from being POSTed by every request.
+  #
+  # A dictionary entry is stored forever: `ttl` is not its lifetime but the time
+  # it is served without asking the API. A stale entry is still served, and
+  # revalidated with its ETag after the response (a 304 keeps it as is).
+  #
+  # Entry: { translations: Hash, etag: String|nil, fetched_at: Integer, failed: Boolean }
+  class DictionaryStore
+    # Seconds a failed fetch is remembered before the API is asked again.
+    FAILURE_TTL = 60
+
+    # Minimum seconds between two usage POSTs, across every process (the node SDK's debounce).
+    USAGE_FLUSH_SECONDS = 10
+
+    attr_reader :cache, :prefix, :ttl, :api_key_hash
+
+    def initialize(cache:, prefix:, ttl:, api_key_hash:)
+      @cache = cache
+      @prefix = prefix
+      @ttl = [ttl.to_i, 0].max
+      @api_key_hash = api_key_hash
+    end
+
+    def self.hash_key(api_key)
+      Digest::SHA1.hexdigest(api_key.to_s)[0, 8]
+    end
+
+    def get(lang, namespace)
+      entry = cache.read(key(lang, namespace))
+      return nil unless entry.is_a?(Hash)
+
+      entry = entry.transform_keys(&:to_sym)
+      entry[:translations].is_a?(Hash) ? entry : nil
+    end
+
+    def put(lang, namespace, translations, etag, failed: false)
+      entry = { translations: translations, etag: etag, fetched_at: Time.now.to_i, failed: failed }
+      cache.write(key(lang, namespace), entry)
+      entry
+    end
+
+    # After a 304: same dictionary, same ETag, fresh again.
+    def touch(lang, namespace)
+      entry = get(lang, namespace)
+      return if entry.nil?
+
+      entry[:fetched_at] = Time.now.to_i
+      entry[:failed] = false
+      cache.write(key(lang, namespace), entry)
+    end
+
+    # Adds freshly translated lines to a stored dictionary (after POST /translate),
+    # and marks it stale so the next request revalidates with the API.
+    def merge(lang, namespace, lines)
+      entry = get(lang, namespace) || { translations: {}, etag: nil, fetched_at: 0, failed: false }
+      entry[:translations] = entry[:translations].merge(lines)
+      entry[:fetched_at] = 0
+      cache.write(key(lang, namespace), entry)
+    end
+
+    def mark_stale(lang, namespace)
+      entry = get(lang, namespace)
+      return if entry.nil?
+
+      entry[:fetched_at] = 0
+      cache.write(key(lang, namespace), entry)
+    end
+
+    def stale?(entry)
+      max_age = entry[:failed] ? [FAILURE_TTL, ttl].min : ttl
+      (Time.now.to_i - entry[:fetched_at].to_i) > max_age
+    end
+
+    # Claims a miss for this process: true when nobody POSTed it during the last
+    # `ttl` seconds. Atomic on stores that honour `unless_exist` (Redis,
+    # Memcached, the database store, the file store, the memory store).
+    def claim_miss(miss)
+      return true if ttl.zero?
+
+      cache.write(miss_key(miss), 1, expires_in: ttl, unless_exist: true) ? true : false
+    end
+
+    # After a failed POST: let a later request try again.
+    def release_miss(miss)
+      cache.delete(miss_key(miss))
+    end
+
+    # The cumulative usage map, `{ namespace => { "key__context" => "YYYY-MM-DD" } }`,
+    # never cleared (the node SDK keeps it for the life of the process; here it
+    # lives in the cache for the life of the cache).
+    def usage
+      usage = cache.read(usage_key)
+      usage.is_a?(Hash) ? usage : {}
+    end
+
+    # Merges freshly recorded dates into the stored map. True when a date
+    # changed (a new key, or a key seen on a new day).
+    def merge_usage(recorded)
+      usage = self.usage
+      changed = false
+      recorded.each do |namespace, keys|
+        keys.each do |key, date|
+          next if usage.dig(namespace, key) == date
+
+          (usage[namespace] ||= {})[key] = date
+          changed = true
+        end
+      end
+      if changed
+        cache.write(usage_key, usage)
+        cache.write("#{usage_key}:dirty", true)
+      end
+      changed
+    end
+
+    # True while the stored map holds changes the API has not received.
+    def usage_dirty?
+      cache.read("#{usage_key}:dirty") ? true : false
+    end
+
+    def clear_usage_dirty
+      cache.delete("#{usage_key}:dirty")
+    end
+
+    # Claims the right to POST usage now: false when a POST left less than 10 s ago.
+    def claim_usage_slot
+      cache.write("#{usage_key}:lock", 1, expires_in: USAGE_FLUSH_SECONDS, unless_exist: true) ? true : false
+    end
+
+    def usage_key
+      "#{prefix}:#{api_key_hash}:usage"
+    end
+
+    def key(lang, namespace)
+      "#{prefix}:#{api_key_hash}:dict:#{namespace}:#{lang}"
+    end
+
+    private
+
+    def miss_key(miss)
+      "#{prefix}:#{api_key_hash}:miss:#{Digest::SHA1.hexdigest(miss.id)}"
+    end
+  end
+end