haveapi 0.32.1 → 0.32.2

data/lib/haveapi/documentation_helpers.rb

@@ -1,9 +1,14 @@
 require 'json'
 require 'uri'
+require 'digest/sha2'
 
 module HaveAPI
   # HTML navigation is derived only from this request's authorized description.
   module DocumentationHelpers
+    ASSET_DIGESTS = %w[js/documentation.js css/documentation.css].to_h do |asset|
+      [asset, Digest::SHA256.file(File.join(__dir__, 'public', asset)).hexdigest.freeze]
+    end.freeze
+
     def documentation_identity_name
       settings.api_server.documentation_name || request.host_with_port
     end
@@ -11,13 +16,13 @@ module HaveAPI
     def documentation_document_title
       page = @documentation_title || if @v
                                        case @documentation_page
-                                       when 'authentication' then 'Authentication'
-                                       when 'resources' then 'Resources'
+                                       when 'authentication' then documentation_t('labels.authentication')
+                                       when 'resources' then documentation_t('labels.resources')
                                        when 'resource' then @documentation_resource[:key]
-                                       else 'Overview'
+                                       else documentation_t('labels.overview')
                                        end
                                      else
-                                       'API versions'
+                                       documentation_t('labels.api_versions')
                                      end
       version = @v && !@documentation_title ? "API v#{@v}" : nil
       [page, version, documentation_identity_name].compact.join(' · ')
@@ -59,6 +64,12 @@ module HaveAPI
       documentation_search_query
       @v = version
       documentation_authenticated?(version)
+      with_documentation_locale do
+        render_localized_version_documentation(version)
+      end
+    end
+
+    def render_localized_version_documentation(version)
       @help = settings.api_server.describe_version(Context.new(
                                                      settings.api_server,
                                                      version:, user: current_user, params:
@@ -66,6 +77,7 @@ module HaveAPI
       return render_documentation_search_index if documentation_search_index_request?
 
       select_documentation_page
+      documentation_example_selection
       @documentation_ui = true
       content_type 'text/html'
       erb :doc_layout, layout: :main_layout do
@@ -81,36 +93,36 @@ module HaveAPI
     def documentation_selection
       @documentation_selection ||= begin
         query = request.query_string
-        halt 400, 'Invalid documentation selection' if query.match?(/%(?![0-9a-f]{2})/i)
+        halt 400, documentation_t('errors.selection') if query.match?(/%(?![0-9a-f]{2})/i)
         pairs = URI.decode_www_form(query)
         selected = pairs.select { |key, _| key.match?(/\A(?:page|resource)(?:\[|\z)/) }
         unless selected.all? { |key, value| %w[page resource].include?(key) && value.valid_encoding? } &&
                selected.map(&:first).uniq.length == selected.length && selected.length <= 1
-          halt 400, 'Invalid documentation selection'
+          halt 400, documentation_t('errors.selection')
         end
         selected.to_h
       end
     rescue ArgumentError
-      halt 400, 'Invalid documentation selection'
+      halt 400, documentation_t('errors.selection')
     end
 
     def select_documentation_page
       selection = documentation_selection
       @documentation_page = selection.fetch('page', 'overview')
       unless %w[overview authentication resources].include?(@documentation_page)
-        halt 400, 'Invalid documentation selection'
+        halt 400, documentation_t('errors.selection')
       end
       if @documentation_page == 'resources' && !documentation_search_query.empty?
-        @documentation_title = "Search API v#{@v}: #{documentation_search_query}"
+        @documentation_title = documentation_t('titles.search', version: @v, query: documentation_search_query)
       end
       return unless selection.has_key?('resource')
 
       key = selection['resource']
       unless key.match?(/\A[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*\z/)
-        halt 400, 'Invalid documentation selection'
+        halt 400, documentation_t('errors.selection')
       end
       @documentation_resource = documentation_resources.find { |entry| entry[:key] == key }
-      halt 404, 'Documentation resource not found' unless @documentation_resource
+      halt 404, documentation_t('errors.resource_not_found') unless @documentation_resource
       @documentation_page = 'resource'
     end
 
@@ -153,8 +165,8 @@ module HaveAPI
     end
 
     def documentation_action_sections(info, resource_path:, action_name:, authentication: nil)
-      sections = { input: 'Input parameters', output: 'Output parameters' }
-      sections[:examples] = 'Examples' unless info[:examples].empty?
+      sections = { input: documentation_t('labels.input_parameters'), output: documentation_t('labels.output_parameters') }
+      sections[:examples] = documentation_t('labels.examples') unless info[:examples].empty?
       sections.map do |section, label|
         { id: documentation_reference_anchor(resource_path:, action_name:, authentication:, section:), label: }
       end
@@ -169,16 +181,81 @@ module HaveAPI
     end
 
     def documentation_permalink(id, label)
-      "<a class=\"docs-permalink\" href=\"##{escape_html(id)}\" aria-label=\"#{escape_html("Link to #{label}")}\"><span aria-hidden=\"true\">#</span></a>"
+      "<a class=\"docs-permalink\" href=\"##{escape_html(id)}\" aria-label=\"#{escape_html(documentation_t('accessibility.link_to', label:))}\"><span aria-hidden=\"true\">#</span></a>"
+    end
+
+    def documentation_example_selection
+      return @documentation_example_selection if defined?(@documentation_example_selection)
+
+      keys = %w[example_language example_client example_detail]
+      pairs = URI.decode_www_form(request.query_string, Encoding::ASCII_8BIT).map do |key, value|
+        [key.force_encoding(Encoding::UTF_8), value.force_encoding(Encoding::UTF_8)]
+      end
+      selected = pairs.select { |key, _| key.match?(/\Aexample_(?:language|client|detail)(?:\[|\z)/) }
+      unless selected.all? { |key, value| keys.include?(key) && key.valid_encoding? && value.valid_encoding? } &&
+             selected.map(&:first).uniq.length == selected.length
+        halt 400, documentation_t('errors.selection')
+      end
+      requested = selected.to_h
+      clients = documentation_clients
+      client = clients.find { |entry| entry.id == requested['example_client'] }
+      language = if requested.has_key?('example_language')
+                   requested['example_language']
+                 else
+                   client&.language
+                 end
+      group = clients.select { |entry| entry.language == language }
+      if group.empty?
+        language = clients.first&.language
+        group = clients.select { |entry| entry.language == language }
+      end
+      client = group.find { |entry| entry.id == requested['example_client'] } || group.first
+      @documentation_example_selection = {
+        client:, language:, detail: requested['example_detail'] == 'thorough' ? 'thorough' : 'simple',
+        explicit: selected.any?
+      }
+    rescue ArgumentError
+      halt 400, documentation_t('errors.selection')
+    end
+
+    def documentation_example_detail(levels)
+      requested = documentation_example_selection[:detail]
+      levels.include?(requested) ? requested : 'simple'
+    end
+
+    def documentation_example_form_parameters
+      parameters = documentation_selection.to_a
+      parameters << ['q', documentation_search_query] unless documentation_search_query.empty?
+      parameters << ['doc_lang', documentation_locale_override] if documentation_locale_override
+      parameters
     end
 
     def documentation_client_metadata
       documentation_clients.map do |client|
-        { id: client.id, language: client.language, language_label: client.language_label, variant: client.variant,
+        { id: client.id, language: client.language, language_label: client.language_label, variant: documentation_client_variant(client),
           details: (@documentation_page_details || {}).fetch(client.id, [:simple]).map(&:to_s) }
       end
     end
 
+    def documentation_client_label(client)
+      case client.id
+      when 'go' then documentation_t('generated.labels.go', default: client.label)
+      when 'rust-async' then documentation_t('generated.labels.rust_async', default: client.label)
+      when 'rust-blocking' then documentation_t('generated.labels.rust_blocking', default: client.label)
+      when 'typescript-generated' then documentation_t('generated.labels.typescript', default: client.label)
+      else client.label
+      end
+    end
+
+    def documentation_client_variant(client)
+      case client.id
+      when 'rust-async' then documentation_t('generated.variants.async', default: client.variant)
+      when 'rust-blocking' then documentation_t('generated.variants.blocking', default: client.variant)
+      when 'typescript-generated' then documentation_t('generated.variants.api_client', default: client.variant)
+      else client.variant
+      end
+    end
+
     def documentation_json(value)
       JSON.generate(value).gsub('<', '\\u003c').gsub('>', '\\u003e').gsub('&', '\\u0026')
     end

data/lib/haveapi/documentation_locale.rb

@@ -0,0 +1,65 @@
+require 'uri'
+
+module HaveAPI
+  # Documentation has its own preference; API request locale remains independent.
+  module DocumentationLocale
+    LOCALES = %w[en cs].freeze
+    COOKIE = 'haveapi.docs.locale'.freeze
+
+    def documentation_locale
+      @documentation_locale ||= begin
+        explicit = documentation_locale_override
+        saved = request.cookies[COOKIE]
+        explicit || (saved if LOCALES.include?(saved)) ||
+          HaveAPI::I18n.accept_language(request.env['HTTP_ACCEPT_LANGUAGE'], LOCALES)&.to_s || 'en'
+      end
+    end
+
+    def documentation_locale_override
+      pairs = URI.decode_www_form(request.query_string)
+      values = pairs.select { |pair| pair.first == 'doc_lang' }
+      values.first.last if values.length == 1 && LOCALES.include?(values.first.last)
+    rescue ArgumentError
+      nil
+    end
+
+    def with_documentation_locale(persist: true)
+      previous = ::I18n.locale
+      @documentation_static_messages = {}
+      settings.api_server.activate_locale(documentation_locale)
+      add_vary_header('Accept-Language')
+      add_vary_header('Cookie')
+      if persist && documentation_locale_override && !documentation_search_index_request?
+        response.set_cookie(COOKIE, value: documentation_locale, path: root,
+                                    max_age: 31_536_000, same_site: :lax, secure: base_url.start_with?('https:'))
+      end
+      yield
+    ensure
+      @documentation_static_messages = nil
+      ::I18n.locale = previous
+    end
+
+    def documentation_language_parameters
+      URI.decode_www_form(request.query_string).reject { |pair| pair.first == 'doc_lang' }
+    rescue ArgumentError
+      []
+    end
+
+    def documentation_t(key, default: nil, **values)
+      if @documentation_static_messages && key.is_a?(String) && default.nil? && values.empty?
+        memo = (@documentation_static_messages[::I18n.locale] ||= {})
+        cached = memo[key]
+        return cached.dup if cached
+      end
+
+      full_key = "haveapi.documentation.#{key}"
+      fallback = ::I18n.t(full_key, locale: :en, default:, **values)
+      result = ::I18n.locale == :en ? fallback : ::I18n.t(full_key, default: fallback, **values)
+
+      # Own the stored bytes; neither the first result nor later hit copies can
+      # mutate labels used elsewhere in this request. Dynamic lookups stay live.
+      memo[key] = result.dup.freeze if memo && result.is_a?(String)
+      result
+    end
+  end
+end

data/lib/haveapi/documentation_oauth.rb

@@ -135,9 +135,9 @@ module HaveAPI
       @purposes = %w[pending session].to_h { |kind| [kind, "haveapi.docs.#{binding}.#{kind}"] }.freeze
       @names = %w[pending session].to_h { |kind| [kind, "haveapi_docs_#{Digest::SHA256.hexdigest(@path)[0, 12]}_#{kind}"] }.freeze
       that = self
-      sinatra.get(@routes.fetch('login')) { that.login(self) }
-      sinatra.get(@routes.fetch('callback')) { that.callback(self) }
-      sinatra.post(@routes.fetch('logout')) { that.logout(self) }
+      sinatra.get(@routes.fetch('login')) { with_documentation_locale(persist: false) { that.login(self) } }
+      sinatra.get(@routes.fetch('callback')) { with_documentation_locale(persist: false) { that.callback(self) } }
+      sinatra.post(@routes.fetch('logout')) { with_documentation_locale(persist: false) { that.logout(self) } }
     end
 
     def authenticate(handler, version)
@@ -153,7 +153,7 @@ module HaveAPI
         handler.instance_variable_set(:@documentation_oauth_csrf, session.fetch('csrf'))
       else
         clear_cookie(handler, 'session')
-        handler.instance_variable_set(:@documentation_oauth_message, 'Your documentation session ended. Sign in again.')
+        handler.instance_variable_set(:@documentation_oauth_message, HaveAPI.message('haveapi.documentation.oauth.session_ended'))
       end
       user
     end
@@ -228,7 +228,7 @@ module HaveAPI
       session = read_cookie(handler, 'session')
       csrf = handler.params['csrf']
       unless handler.request.env['HTTP_ORIGIN'] == @origin && session && nonce?(csrf) && secure_equal?(csrf, session['csrf'])
-        handler.halt(403, 'Invalid documentation sign-out request')
+        handler.halt(403, handler.documentation_t('oauth.sign_out_invalid'))
       end
       clear_cookie(handler, 'session')
       clear_cookie(handler, 'pending')
@@ -238,8 +238,8 @@ module HaveAPI
         @transport.post(@endpoints.fetch(:revoke), parameters)
       rescue Failure
         handler.halt(502, { 'content-type' => 'text/html; charset=utf-8' },
-                     '<p>Local sign-out succeeded, but the server session may remain until it expires.</p>' \
-                     "<p><a href=\"#{CGI.escapeHTML(destination_url('version' => @server.default_version.to_s))}\">Return to documentation</a></p>")
+                     "<p>#{CGI.escapeHTML(handler.documentation_t('oauth.sign_out_incomplete'))}</p>" \
+                     "<p><a href=\"#{CGI.escapeHTML(destination_url('version' => @server.default_version.to_s))}\">#{CGI.escapeHTML(handler.documentation_t('oauth.return'))}</a></p>")
       end
       if switch_user
         handler.redirect("#{@origin}#{@routes.fetch('login')}?#{URI.encode_www_form(version: @server.default_version.to_s)}", 303)
@@ -274,7 +274,7 @@ module HaveAPI
     end
 
     def require_origin(handler)
-      handler.halt(400, 'Documentation sign-in requires its configured HTTPS origin') unless documentation_origin?(handler)
+      handler.halt(400, handler.documentation_t('oauth.origin_required')) unless documentation_origin?(handler)
     end
 
     def protect_response(handler, referrer_policy: 'no-referrer')
@@ -339,12 +339,12 @@ module HaveAPI
 
       unless @switch_user && selected == [%w[switch_user 1]] && parameters['switch_user'] == '1' &&
              [nil, 'application/x-www-form-urlencoded'].include?(request.media_type)
-        handler.halt(403, 'Invalid documentation switch request')
+        handler.halt(403, handler.documentation_t('oauth.switch_invalid'))
       end
 
       true
     rescue ArgumentError
-      handler.halt(403, 'Invalid documentation switch request')
+      handler.halt(403, handler.documentation_t('oauth.switch_invalid'))
     end
 
     def nonce?(value)
@@ -392,7 +392,7 @@ module HaveAPI
       payload
     rescue ActiveSupport::MessageEncryptor::InvalidMessage, Failure, ArgumentError, TypeError
       clear_cookie(handler, kind)
-      handler.instance_variable_set(:@documentation_oauth_message, 'Your documentation session ended. Sign in again.') if kind == 'session'
+      handler.instance_variable_set(:@documentation_oauth_message, HaveAPI.message('haveapi.documentation.oauth.session_ended')) if kind == 'session'
       nil
     end
 
@@ -405,7 +405,7 @@ module HaveAPI
       protect_response(handler)
       link = "#{@origin}#{@routes.fetch('login')}"
       handler.halt(400, { 'content-type' => 'text/html; charset=utf-8' },
-                   "<p>Documentation sign-in failed. <a href=\"#{CGI.escapeHTML(link)}\">Try again</a>.</p>")
+                   "<p>#{CGI.escapeHTML(handler.documentation_t('oauth.sign_in_failed'))} <a href=\"#{CGI.escapeHTML(link)}\">#{CGI.escapeHTML(handler.documentation_t('oauth.try_again'))}</a>.</p>")
     end
   end
 end

data/lib/haveapi/documentation_search.rb

@@ -139,7 +139,7 @@ module HaveAPI
 
       def invalid_documentation_search_query
         headers 'Cache-Control' => 'private, no-store'
-        halt 400, 'Invalid documentation search query'
+        halt 400, documentation_t('errors.search_query')
       end
 
       def documentation_search_form_options(id:)
@@ -159,7 +159,7 @@ module HaveAPI
       end
 
       def documentation_search_index_url(version:, key:)
-        "#{url(settings.api_server.version_prefix(version), false)}?page=resources&search_index=#{key}"
+        "#{url(settings.api_server.version_prefix(version), false)}?page=resources&search_index=#{key}&doc_lang=#{documentation_locale}"
       end
 
       def documentation_search_index_request?
@@ -171,7 +171,7 @@ module HaveAPI
         index = documentation_search_index
         requested = documentation_search_parameters[:index]
         if requested != 'current' && requested != index.key
-          halt 409, 'Search has changed. Reload this page or submit to open current results.'
+          halt 409, documentation_t('search.changed')
         end
 
         content_type 'text/html', charset: 'utf-8'
@@ -215,8 +215,8 @@ module HaveAPI
         else
           context << "#{result[:resource_path].join('.')} · #{result[:action_name]}"
         end
-        context << "#{result[:direction].to_s.capitalize} · #{result[:type]}" if result[:kind] == :parameter
-        context << "Authentication: #{result[:authentication]}" if result[:authentication]
+        context << "#{documentation_t("browser.#{result[:direction]}")} · #{result[:type]}" if result[:kind] == :parameter
+        context << documentation_t('browser.authentication', provider: result[:authentication]) if result[:authentication]
         context << result[:label] if result[:kind] != :resource && result[:label] && result[:label] != result[:name]
         context
       end

data/lib/haveapi/documentation_validators.rb

@@ -1,5 +1,6 @@
 require 'cgi'
 require 'json'
+require 'haveapi/i18n'
 
 module HaveAPI
   # Presents already-authorized/localized metadata without changing validation.
@@ -10,31 +11,40 @@ module HaveAPI
 
       renderer = new(type)
       rules = validators.map { |name, options| renderer.rule(name, options) }.join
-      %(<div class="docs-validators"><table class="docs-validator-table"><caption>Validation rules</caption><thead><tr><th scope="col">Rule</th><th scope="col">Details</th></tr></thead><tbody>#{rules}</tbody></table></div>)
+      %(<div class="docs-validators"><table class="docs-validator-table"><caption>#{renderer.text('caption')}</caption><thead><tr><th scope="col">#{renderer.text('rule')}</th><th scope="col">#{renderer.text('details')}</th></tr></thead><tbody>#{rules}</tbody></table></div>)
     end
 
     def initialize(type)
       @type = type
     end
 
+    # Escape catalog text before interpolating markup produced by this renderer.
+    # Validator metadata is always escaped by value/literal/html first.
+    def text(key, **values)
+      full_key = "haveapi.documentation.validators.#{key}"
+      fallback = ::I18n.t(full_key, locale: :en, skip_interpolation: true)
+      template = ::I18n.t(full_key, default: fallback, skip_interpolation: true)
+      format(html(template), **values)
+    end
+
     def rule(name, options)
       content, used = explanation(name.to_s, options)
       if content && options.is_a?(Hash)
         remaining = options.reject { |key, _| used.include?(key.to_s) || key.to_s == 'message' }
-        content += "<p><strong>Validation error message:</strong> #{value(field(options, :message))}</p>" if option?(options, :message)
+        content += "<p><strong>#{text('message')}</strong> #{value(field(options, :message))}</p>" if option?(options, :message)
         unless remaining.empty?
-          content += "<details><summary>Additional details</summary>#{data(remaining)}</details>"
+          content += "<details><summary>#{text('additional')}</summary>#{data(remaining)}</details>"
         end
       elsif !content
-        content = "<p>Supplied validator metadata:</p>#{data(options)}"
+        content = "<p>#{text('metadata')}</p>#{data(options)}"
       end
       known = %w[present include exclude accept confirm number length format custom].include?(name.to_s)
-      title = known ? name.to_s.capitalize : name.to_s
-      %(<tr class="docs-validator"><th scope="row">#{html(title)}</th><td>#{content}</td></tr>)
+      title = known ? text("names.#{name}") : html(name)
+      %(<tr class="docs-validator"><th scope="row">#{title}</th><td>#{content}</td></tr>)
     end
 
     def explanation(name, options)
-      return ["<p>Application-specific rule: #{html(options)}</p>", []] if name == 'custom' && options.is_a?(String)
+      return ["<p>#{text('custom', rule: html(options))}</p>", []] if name == 'custom' && options.is_a?(String)
       return unless options.is_a?(Hash)
       # Two differently typed keys must not silently collapse to one option.
       return if options.keys.map(&:to_s).uniq.length != options.length
@@ -45,20 +55,20 @@ module HaveAPI
       when 'accept'
         return unless option?(options, :value)
 
-        ["<p>Must equal #{literal(field(options, :value))}.</p>", ['value']]
+        ["<p>#{text('accept', value: literal(field(options, :value)))}</p>", ['value']]
       when 'confirm'
         return unless field(options, :parameter).is_a?(String) || field(options, :parameter).is_a?(Symbol)
         return unless boolean?(field(options, :equal))
 
-        relation = field(options, :equal) ? 'Must equal' : 'Must differ from'
-        ["<p>#{relation} parameter <code>#{html(field(options, :parameter))}</code>.</p>", %w[parameter equal]]
+        relation = field(options, :equal) ? 'confirm_equal' : 'confirm_different'
+        ["<p>#{text(relation, parameter: "<code>#{html(field(options, :parameter))}</code>")}</p>", %w[parameter equal]]
       when 'number' then number(options)
       when 'length' then length(options)
       when 'format'
         return unless field(options, :rx).is_a?(String) && boolean?(field(options, :match))
 
-        relation = field(options, :match) ? 'Must match' : 'Must not match'
-        content = "<p>#{relation} this regular expression:</p><pre><code>#{html(field(options, :rx))}</code></pre>"
+        relation = field(options, :match) ? 'format_match' : 'format_no_match'
+        content = "<p>#{text(relation)}</p><pre><code>#{html(field(options, :rx))}</code></pre>"
         content += "<p>#{value(field(options, :description))}</p>" if option?(options, :description)
         [content, %w[rx match description]]
       end
@@ -67,22 +77,22 @@ module HaveAPI
     def presence(options)
       return unless boolean?(field(options, :empty))
 
-      empty = field(options, :empty) ? 'Empty values are allowed.' : 'Must not be empty; strings must contain a non-whitespace character.'
-      ["<p>Must be supplied and cannot be null. #{empty}</p>", ['empty']]
+      empty = field(options, :empty) ? 'empty_allowed' : 'empty_disallowed'
+      ["<p>#{text('present')} #{text(empty)}</p>", ['empty']]
     end
 
     def choices(name, options)
       values = field(options, :values)
       return unless values.is_a?(Array) || (name == 'include' && values.is_a?(Hash))
 
-      label = name == 'include' ? 'Allowed values' : 'Disallowed values'
+      label = name == 'include' ? 'allowed' : 'disallowed'
       items = if values.is_a?(Hash)
                 values.map { |machine, label_text| "<li>#{choice_literal(machine)}: #{value(label_text)}</li>" }
               else
                 values.map { |machine| "<li>#{choice_literal(machine)}</li>" }
               end
-      body = items.empty? ? '<p>The set is empty.</p>' : %(<ul class="docs-validator-values">#{items.join}</ul>)
-      ["<p>#{label}:</p>#{body}", ['values']]
+      body = items.empty? ? "<p>#{text('empty_set')}</p>" : %(<ul class="docs-validator-values">#{items.join}</ul>)
+      ["<p>#{text(label)}:</p>#{body}", ['values']]
     end
 
     def number(options)
@@ -90,18 +100,18 @@ module HaveAPI
       return unless numeric.all? { |key| !option?(options, key) || finite_number?(field(options, key)) }
       return unless %w[odd even].all? { |key| !option?(options, key) || boolean?(field(options, key)) }
 
-      lines = ['Must be a number after parameter type conversion.']
-      lines << "Minimum: #{literal(field(options, :min))} (inclusive)." if option?(options, :min)
-      lines << "Maximum: #{literal(field(options, :max))} (inclusive)." if option?(options, :max)
+      lines = [text('number')]
+      lines << text('minimum', value: literal(field(options, :min))) if option?(options, :min)
+      lines << text('maximum', value: literal(field(options, :max))) if option?(options, :max)
       if option?(options, :step)
         start = option?(options, :min) ? field(options, :min) : 0
-        lines << "Step: #{literal(field(options, :step))}, measured from #{literal(start)}."
+        lines << text('step', value: literal(field(options, :step)), start: literal(start))
       end
-      lines << "Must be a multiple of #{literal(field(options, :mod))}, measured from zero." if option?(options, :mod)
-      lines << 'Must be odd.' if field(options, :odd) == true
-      lines << 'Must be even.' if field(options, :even) == true
-      lines << 'Odd-only restriction: disabled.' if option?(options, :odd) && field(options, :odd) == false
-      lines << 'Even-only restriction: disabled.' if option?(options, :even) && field(options, :even) == false
+      lines << text('multiple', value: literal(field(options, :mod))) if option?(options, :mod)
+      lines << text('odd') if field(options, :odd) == true
+      lines << text('even') if field(options, :even) == true
+      lines << text('odd_disabled') if option?(options, :odd) && field(options, :odd) == false
+      lines << text('even_disabled') if option?(options, :even) && field(options, :even) == false
       ["<ul>#{lines.map { |line| "<li>#{line}</li>" }.join}</ul>", numeric + %w[odd even]]
     end
 
@@ -112,16 +122,16 @@ module HaveAPI
       return if option?(options, :equals) && (option?(options, :min) || option?(options, :max))
 
       unit = if %w[String Text].include?(@type)
-               ' characters'
+               text('characters')
              elsif %w[List Array].include?(@type)
-               ' items'
+               text('items')
              else
                ''
              end
       lines = []
-      lines << "Length must equal #{literal(field(options, :equals))}#{unit}." if option?(options, :equals)
-      lines << "Minimum length: #{literal(field(options, :min))}#{unit} (inclusive)." if option?(options, :min)
-      lines << "Maximum length: #{literal(field(options, :max))}#{unit} (inclusive)." if option?(options, :max)
+      lines << text('length_equal', value: literal(field(options, :equals)), unit:) if option?(options, :equals)
+      lines << text('length_minimum', value: literal(field(options, :min)), unit:) if option?(options, :min)
+      lines << text('length_maximum', value: literal(field(options, :max)), unit:) if option?(options, :max)
       ["<ul>#{lines.map { |line| "<li>#{line}</li>" }.join}</ul>", keys]
     end
 
@@ -152,7 +162,7 @@ module HaveAPI
     end
 
     def literal(value)
-      json_value?(value) ? "<code>#{html(JSON.generate(value))}</code>" : "<span>Ruby value: <code>#{html(value.inspect)}</code></span>"
+      json_value?(value) ? "<code>#{html(JSON.generate(value))}</code>" : "<span>#{text('ruby_value')}: <code>#{html(value.inspect)}</code></span>"
     end
 
     def choice_literal(value)
@@ -167,7 +177,7 @@ module HaveAPI
       label, text = if json_value?(value)
                       ['JSON', JSON.pretty_generate(value)]
                     else
-                      ['Ruby value', value.inspect]
+                      [text('ruby_value'), value.inspect]
                     end
       "<p>#{label}:</p><pre><code>#{html(text)}</code></pre>"
     end