haveapi 0.32.1 → 0.32.2

data/spec/documentation/locale_spec.rb

@@ -0,0 +1,367 @@
+require 'spec_helper'
+require 'cgi'
+require 'ripper'
+require 'open3'
+
+RSpec.describe HaveAPI::DocumentationLocale do
+  api do
+    define_resource(:Thing) do
+      version 1
+      auth false
+      desc HaveAPI.message('documentation_locale_spec.resource')
+      define_action(:Show) do
+        route ''
+        http_method :get
+        input { string :query }
+        output { string :language }
+        authorize { allow }
+        def exec
+          { language: ::I18n.locale.to_s }
+        end
+      end
+    end
+  end
+
+  let(:server) do
+    HaveAPI::Server.new(get_opt(:api_module)).tap do |api|
+      api.use_version(1)
+      api.default_locale = :cs
+      api.locale_header = 'X-API-Language'
+      api.parameter_i18n_scope = 'documentation_locale_spec'
+      api.locale { :cs }
+      api.mount('/api/')
+    end
+  end
+  let(:app) { server.app }
+
+  before do
+    ::I18n.backend.store_translations(:en, documentation_locale_spec: {
+                                      resource: 'English resource',
+                                      attributes: { query: { label: 'English query' } }
+                                    })
+    ::I18n.backend.store_translations(:cs, documentation_locale_spec: {
+                                      resource: 'Český prostředek',
+                                      attributes: { query: { label: 'Český dotaz' } }
+                                    })
+  end
+
+  describe '#documentation_t' do
+    let(:helper) { Object.new.extend(described_class) }
+
+    it 'preserves translations, interpolation and defaults across repeated locale changes' do
+      ::I18n.backend.store_translations(:en, haveapi: { documentation: {
+                                        locale_spec_present: 'English %{name}', locale_spec_fallback: 'Fallback %{name}'
+                                      } })
+      ::I18n.backend.store_translations(:cs, haveapi: { documentation: { locale_spec_present: 'Česky %{name}' } })
+      %i[en cs en].each do |locale|
+        ::I18n.with_locale(locale) do
+          expected = locale == :en ? 'English <&>' : 'Česky <&>'
+          expect(helper.documentation_t('locale_spec_present', name: '<&>')).to eq(expected)
+          expect(helper.documentation_t('locale_spec_present', default: 'Ignored', name: '<&>')).to eq(expected)
+          expect(helper.documentation_t('locale_spec_fallback', name: 'input')).to eq('Fallback input')
+          expect(helper.documentation_t('locale_spec_absent', default: 'Default %{name}', name: 'input')).to eq('Default input')
+          expect(helper.documentation_t('locale_spec_absent')).to be_nil
+          expect(helper.documentation_t('browser')).to eq(::I18n.t('haveapi.documentation.browser'))
+        end
+      end
+    end
+
+    it 'reuses the resolved English fallback without translating the same key twice' do
+      allow(::I18n).to receive(:t).and_call_original
+      ::I18n.with_locale(:en) do
+        expect(helper.documentation_t('labels.language')).to eq('Language')
+      end
+      expect(::I18n).to have_received(:t).with('haveapi.documentation.labels.language', locale: :en, default: nil).once
+      expect(::I18n).to have_received(:t).once
+    end
+
+    context 'with a documentation render scope' do
+      let(:helper) do
+        Class.new do
+          attr_accessor :scope_locale
+
+          def settings = self
+          def api_server = self
+          def documentation_locale = scope_locale
+          def activate_locale(locale) = (::I18n.locale = locale)
+          def add_vary_header(_header); end
+        end.include(described_class).new.tap { |instance| instance.scope_locale = :en }
+      end
+
+      before do
+        ::I18n.backend.store_translations(:en, haveapi: { documentation: {
+                                          memo_static: 'English label', memo_interpolated: 'Hello %{name}',
+                                          memo_fallback: 'English fallback', memo_hash: { leaf: 'Leaf' }, memo_number: 7
+                                        } })
+        ::I18n.backend.store_translations(:cs, haveapi: { documentation: { memo_static: 'Český štítek' } })
+        allow(::I18n).to receive(:t).and_call_original
+      end
+
+      it 'memoizes static strings by active locale, including explicit nil defaults and English fallback' do
+        helper.with_documentation_locale(persist: false) do
+          %i[en cs en].each do |locale|
+            ::I18n.with_locale(locale) do
+              expected = locale == :en ? 'English label' : 'Český štítek'
+              expect(helper.documentation_t('memo_static', default: nil)).to eq(expected)
+              expect(helper.documentation_t('memo_static')).to eq(expected)
+            end
+          end
+          ::I18n.with_locale(:cs) do
+            2.times { expect(helper.documentation_t('memo_fallback')).to eq('English fallback') }
+          end
+        end
+
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_static', locale: :en, default: nil).twice
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_static', default: 'English label').once
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_fallback', locale: :en, default: nil).once
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_fallback', default: 'English fallback').once
+      end
+
+      it 'isolates caller mutation of both the initial result and later hit copies' do
+        helper.with_documentation_locale(persist: false) do
+          first = helper.documentation_t('memo_static')
+          first.replace('Changed first result')
+          hit = helper.documentation_t('memo_static')
+          expect(hit).to eq('English label')
+          expect(hit).not_to be_frozen
+          hit.replace('Changed hit')
+          expect(helper.documentation_t('memo_static')).to eq('English label')
+        end
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_static', locale: :en, default: nil).once
+      end
+
+      it 'keeps explicit defaults, interpolation and non-String keys on the original lookup path' do
+        helper.with_documentation_locale(persist: false) do
+          2.times do
+            expect(helper.documentation_t('memo_default_only', default: 'Explicit default')).to eq('Explicit default')
+            expect(helper.documentation_t(:memo_static)).to eq('English label')
+          end
+          %w[first second].each do |name|
+            expect(helper.documentation_t('memo_interpolated', name:)).to eq("Hello #{name}")
+          end
+        end
+
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_default_only', locale: :en, default: 'Explicit default').twice
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_static', locale: :en, default: nil).twice
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_interpolated', locale: :en, default: nil, name: 'first').once
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_interpolated', locale: :en, default: nil, name: 'second').once
+      end
+
+      it 'does not retain missing, hash or other non-String results' do
+        helper.with_documentation_locale(persist: false) do
+          2.times do
+            expect(helper.documentation_t('memo_late')).to be_nil
+            expect(helper.documentation_t('memo_hash')).to eq(leaf: 'Leaf')
+            expect(helper.documentation_t('memo_number')).to eq(7)
+          end
+          ::I18n.backend.store_translations(:en, haveapi: { documentation: { memo_late: 'Now available' } })
+          expect(helper.documentation_t('memo_late')).to eq('Now available')
+        end
+
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_late', locale: :en, default: nil).exactly(3).times
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_hash', locale: :en, default: nil).twice
+        expect(::I18n).to have_received(:t).with('haveapi.documentation.memo_number', locale: :en, default: nil).twice
+      end
+
+      it 'starts fresh on each render and leaves no memo outside that scope' do
+        helper.with_documentation_locale(persist: false) { expect(helper.documentation_t('memo_static')).to eq('English label') }
+        ::I18n.backend.store_translations(:en, haveapi: { documentation: { memo_static: 'Next render' } })
+        helper.with_documentation_locale(persist: false) { expect(helper.documentation_t('memo_static')).to eq('Next render') }
+        ::I18n.backend.store_translations(:en, haveapi: { documentation: { memo_static: 'Outside render' } })
+        ::I18n.with_locale(:en) { expect(helper.documentation_t('memo_static')).to eq('Outside render') }
+      end
+
+      it 'clears nested scopes after errors and restores the active locale' do
+        previous = ::I18n.locale
+        helper.scope_locale = :cs
+        helper.with_documentation_locale(persist: false) do
+          expect(helper.documentation_t('memo_static')).to eq('Český štítek')
+          helper.scope_locale = :en
+          expect do
+            helper.with_documentation_locale(persist: false) do
+              expect(helper.documentation_t('memo_static')).to eq('English label')
+              raise 'nested rendering failed'
+            end
+          end.to raise_error(RuntimeError, 'nested rendering failed')
+          expect(::I18n.locale).to eq(:cs)
+          ::I18n.backend.store_translations(:cs, haveapi: { documentation: { memo_static: 'After inner scope' } })
+          expect(helper.documentation_t('memo_static')).to eq('After inner scope')
+        end
+        expect(::I18n.locale).to eq(previous)
+
+        helper.scope_locale = :en
+        expect do
+          helper.with_documentation_locale(persist: false) do
+            expect(helper.documentation_t('memo_static')).to eq('English label')
+            raise 'outer rendering failed'
+          end
+        end.to raise_error(RuntimeError, 'outer rendering failed')
+        ::I18n.backend.store_translations(:en, haveapi: { documentation: { memo_static: 'After aborted render' } })
+        ::I18n.with_locale(:en) { expect(helper.documentation_t('memo_static')).to eq('After aborted render') }
+        expect(::I18n.locale).to eq(previous)
+      end
+
+      it 'does not memoize a failed lookup' do
+        calls = 0
+        allow(::I18n).to receive(:t).with('haveapi.documentation.memo_failure', locale: :en, default: nil) do
+          calls += 1
+          raise 'lookup failed' if calls == 1
+
+          'Recovered label'
+        end
+        helper.with_documentation_locale(persist: false) do
+          expect { helper.documentation_t('memo_failure') }.to raise_error(RuntimeError, 'lookup failed')
+          2.times { expect(helper.documentation_t('memo_failure')).to eq('Recovered label') }
+        end
+        expect(calls).to eq(2)
+      end
+    end
+  end
+
+  def document_language
+    last_response.body[/<html lang="([^"]+)"/, 1]
+  end
+
+  def index_url
+    CGI.unescapeHTML(last_response.body[/data-search-index-url="([^"]+)"/, 1])
+  end
+
+  it 'negotiates browser preferences independently of API configuration without saving detection' do
+    { 'CS-cz, en;q=0.8' => 'cs', 'de, en-GB;q=0.8,cs;q=0.5' => 'en',
+      'en;q=0,cs-CZ;q=0.7' => 'cs', 'en-US,cs;q=0.9' => 'en',
+      'de,*;q=0.5' => 'en', '*' => 'en', '' => 'en' }.each do |browser, expected|
+      get '/api/v1/', {}, 'HTTP_ACCEPT_LANGUAGE' => browser, 'HTTP_X_API_LANGUAGE' => 'cs'
+      expect(last_response).to be_ok
+      expect(document_language).to eq(expected), browser
+      expect(last_response.headers['Set-Cookie'].to_s).not_to include('haveapi.docs.locale')
+    end
+  end
+
+  it 'saves only explicit choices and gives a valid query priority over the saved language' do
+    get '/api/v1/?resource=thing&doc_lang=cs', {}, 'HTTP_ACCEPT_LANGUAGE' => 'en'
+    expect(document_language).to eq('cs')
+    cookie = last_response.headers['Set-Cookie'].to_s
+    expect(cookie).to include('haveapi.docs.locale=cs', 'path=/api/', 'samesite=lax')
+    expect(cookie.downcase).not_to include('domain=', 'secure')
+    get '/api/v1/', {}, 'HTTP_ACCEPT_LANGUAGE' => 'en'
+    expect(document_language).to eq('cs')
+    get '/api/v1/?doc_lang=en', {}, 'HTTP_ACCEPT_LANGUAGE' => 'cs'
+    expect(document_language).to eq('en')
+    expect(last_response.headers['Set-Cookie'].to_s).to include('haveapi.docs.locale=en')
+  end
+
+  it 'uses a secure host-only cookie over HTTPS and works without returning that cookie' do
+    get 'https://example.org/api/v1/?doc_lang=cs'
+    expect(document_language).to eq('cs')
+    expect(last_response.headers['Set-Cookie'].to_s).to include('secure')
+    clear_cookies
+    get '/api/v1/?doc_lang=cs'
+    expect(document_language).to eq('cs')
+    clear_cookies
+    get '/api/v1/'
+    expect(document_language).to eq('en')
+  end
+
+  it 'ignores unsupported, nested and duplicate preferences' do
+    set_cookie 'haveapi.docs.locale=unknown; path=/api/'
+    %w[doc_lang=unknown doc_lang=auto doc_lang[]=cs doc_lang=cs&doc_lang=en].each do |query|
+      get "/api/v1/?#{query}", {}, 'HTTP_ACCEPT_LANGUAGE' => 'en'
+      expect(document_language).to eq('en')
+      expect(last_response.headers['Set-Cookie'].to_s).not_to include('haveapi.docs.locale')
+    end
+  end
+
+  it 'localizes metadata and controls, retaining the exact language choices above Theme' do
+    get '/api/v1/?resource=thing&doc_lang=cs&q=dotaz'
+    body = last_response.body
+    expect(body).to include('Český prostředek', 'Český dotaz', 'data-documentation-language', '>English</option>', '>Česky</option>')
+    expect(body.index('data-documentation-language')).to be < body.index('docs-theme-label')
+    expect(body).to include('name="resource" value="thing"', 'name="q" value="dotaz"')
+    expect(body).not_to include('value="auto"')
+  end
+
+  it 'pins search to the displayed locale without persisting a read-only selector' do
+    get '/api/v1/?resource=thing&doc_lang=cs'
+    endpoint = index_url
+    expect(endpoint).to include('doc_lang=cs')
+    clear_cookies
+    get endpoint, {}, 'HTTP_ACCEPT_LANGUAGE' => 'en'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('"locale":"cs"', 'Český dotaz')
+    expect(last_response.headers['Set-Cookie'].to_s).not_to include('haveapi.docs.locale')
+    expect(last_response.headers['Cache-Control']).to eq('private, max-age=86400, immutable')
+    expect(last_response.headers['Vary']).to include('Cookie', 'Accept-Language', 'Authorization')
+    get endpoint.sub('doc_lang=cs', 'doc_lang=en')
+    expect(last_response.status).to eq(409)
+  end
+
+  it 'preserves native Ruby and JavaScript tokens while translating authored comments' do
+    scanner = <<~JS
+      const ts = require(process.argv[1]);
+      let source = "";
+      process.stdin.on("data", chunk => source += chunk);
+      process.stdin.on("end", () => {
+        const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, source);
+        const tokens = [];
+        let kind;
+        while ((kind = scanner.scan()) !== ts.SyntaxKind.EndOfFileToken) {
+          if (kind !== ts.SyntaxKind.SingleLineCommentTrivia && kind !== ts.SyntaxKind.MultiLineCommentTrivia) {
+            tokens.push([kind, scanner.getTokenText()]);
+          }
+        }
+        process.stdout.write(JSON.stringify(tokens));
+      });
+    JS
+    compiler = File.expand_path('../../../../clients/js/node_modules/typescript', __dir__)
+    rendered = %w[en cs].map do |locale|
+      get "/api/v1/?doc_lang=#{locale}"
+      last_response.body.scan(%r{<pre><code class="(ruby|javascript)"[^>]*>(.*?)</code></pre>}m).map do |language, html|
+        source = CGI.unescapeHTML(html)
+        if language == 'ruby'
+          Ripper.lex(source).reject { |(_, type, _, _)| type == :on_comment }.map { |(_, type, token, _)| [type, token] }
+        else
+          output, error, status = Open3.capture3('node', '-e', scanner, compiler, stdin_data: source)
+          expect(status).to be_success, error
+          JSON.parse(output)
+        end
+      end
+    end
+    expect(rendered.first).not_to be_empty
+    expect(rendered.last).to eq(rendered.first)
+  end
+
+  it 'leaves ordinary actions and OPTIONS in the configured API locale' do
+    set_cookie 'haveapi.docs.locale=cs; path=/api/'
+    get '/api/v1/things?doc_lang=cs', {}, 'HTTP_X_API_LANGUAGE' => 'en'
+    expect(JSON.parse(last_response.body).dig('response', 'thing', 'language')).to eq('en')
+    options '/api/v1/?doc_lang=cs', {}, 'HTTP_X_API_LANGUAGE' => 'en'
+    expect(last_response.body).to include('English resource', 'English query')
+    expect(last_response.body).not_to include('Český prostředek')
+  end
+
+  it 'restores the thread locale after successful and failed documentation rendering' do
+    previous = ::I18n.locale
+    get '/api/v1/?doc_lang=cs'
+    expect(::I18n.locale).to eq(previous)
+    allow(server).to receive(:describe_version) do
+      expect(::I18n.locale).to eq(:cs)
+      raise 'description failure'
+    end
+    app.set :raise_errors, true
+    expect { get '/api/v1/?doc_lang=cs' }.to raise_error(RuntimeError, 'description failure')
+    expect(::I18n.locale).to eq(previous)
+  end
+
+  it 'uses localized articles and stable mounted links with explicit English fallback' do
+    get '/api/doc/protocol?doc_lang=cs'
+    expect(document_language).to eq('cs')
+    expect(last_response.body).to include('id="resources"', 'src="/api/doc/protocol.png"', 'href="/api/doc/typed-input-validation')
+    get '/api/doc/documentation-ui'
+    expect(document_language).to eq('cs')
+    expect(last_response.body).to include('lang="en"', 'Browsing API documentation')
+    get '/api/doc/protocol.md'
+    expect(last_response).to be_ok
+    get '/api/doc/../../Gemfile'
+    expect(last_response.status).to eq(404)
+  end
+end

data/spec/documentation/navigation_spec.rb

@@ -1,4 +1,5 @@
 require 'spec_helper'
+require 'open3'
 
 module DocumentationNavigationSpec
   User = Struct.new(:login)
@@ -232,7 +233,7 @@ describe DocumentationNavigationSpec do
 
   it 'links nested resource breadcrumbs to the directory and each real parent' do
     get '/v1/?resource=widget.child'
-    breadcrumb = last_response.body.match(%r{<nav aria-label="Breadcrumb" data-resource-breadcrumbs>(.*?)</nav>}m)[1]
+    breadcrumb = last_response.body.match(%r{<nav class="docs-breadcrumb"[^>]*data-resource-breadcrumbs>(.*?)</nav>}m)[1]
     expect(breadcrumb).to include('href="/v1/?page=resources"', 'href="/v1/?resource=widget"',
                                   '<li aria-current="page">Child</li>')
     expect(last_response.body.index('data-action-nav')).to be < last_response.body.index('docs-preferences')
@@ -273,12 +274,69 @@ describe DocumentationNavigationSpec do
     response = Rack::MockRequest.new(app).get('/v1/?resource=widget',
                                               'HTTP_HOST' => 'example.test', 'SCRIPT_NAME' => '/rack')
     expect(response.status).to eq(200)
-    expect(response.body).to include('src="/rack/js/documentation.js"',
+    digests = HaveAPI::DocumentationHelpers::ASSET_DIGESTS
+    expect(response.body).to include("src=\"/rack/js/documentation.js?v=#{digests.fetch('js/documentation.js')}\"",
                                      'data-highlighter-url="/rack/js/highlighter.js"',
-                                     'href="/rack/css/documentation.css"',
+                                     "href=\"/rack/css/documentation.css?v=#{digests.fetch('css/documentation.css')}\"",
                                      'href="/rack/v1/?page=resources"')
   end
 
+  it 'versions the entry assets by installed content without reading files during requests' do
+    public_root = File.expand_path('../../lib/haveapi/public', __dir__)
+    digests = HaveAPI::DocumentationHelpers::ASSET_DIGESTS
+    expect(digests).to eq(%w[js/documentation.js css/documentation.css].to_h do |asset|
+      [asset, Digest::SHA256.file(File.join(public_root, asset)).hexdigest]
+    end)
+    expect(digests).to be_frozen
+    expect(digests.values).to all(be_frozen)
+    allow(Digest::SHA256).to receive(:file).and_call_original
+    %w[en cs].each do |locale|
+      get "/v1/?doc_lang=#{locale}"
+      digests.each do |asset, digest|
+        expect(last_response.body).to include("/#{asset}?v=#{digest}\"")
+      end
+    end
+    expect(Digest::SHA256).not_to have_received(:file)
+    digests.each do |asset, digest|
+      get "/#{asset}?v=#{digest}"
+      expect(last_response).to be_ok
+      expect(last_response.body).to eq(File.binread(File.join(public_root, asset)))
+    end
+  end
+
+  it 'retains content versions across loads and changes only the modified asset version' do
+    helper_path = File.expand_path('../../lib/haveapi/documentation_helpers.rb', __dir__)
+    script = <<~RUBY
+      require 'tmpdir'
+      require 'fileutils'
+      Dir.mktmpdir('haveapi-assets') do |root|
+        path = File.join(root, 'documentation_helpers.rb')
+        FileUtils.cp(ARGV.fetch(0), path)
+        %w[js/documentation.js css/documentation.css].each do |asset|
+          target = File.join(root, 'public', asset)
+          FileUtils.mkdir_p(File.dirname(target))
+          File.write(target, asset)
+        end
+        load path
+        first = HaveAPI::DocumentationHelpers::ASSET_DIGESTS
+        HaveAPI::DocumentationHelpers.send(:remove_const, :ASSET_DIGESTS)
+        load path
+        unchanged = HaveAPI::DocumentationHelpers::ASSET_DIGESTS
+        File.write(File.join(root, 'public/js/documentation.js'), 'changed JavaScript')
+        HaveAPI::DocumentationHelpers.send(:remove_const, :ASSET_DIGESTS)
+        load path
+        puts JSON.generate([first, unchanged, HaveAPI::DocumentationHelpers::ASSET_DIGESTS])
+      end
+    RUBY
+    output, status = Open3.capture2e(RbConfig.ruby, '-e', script, helper_path)
+    expect(status).to be_success, output
+    first, unchanged, changed = JSON.parse(output)
+    expect(unchanged).to eq(first)
+    expect(changed.fetch('css/documentation.css')).to eq(first.fetch('css/documentation.css'))
+    expect(changed.fetch('js/documentation.js')).to eq(Digest::SHA256.hexdigest('changed JavaScript'))
+    expect(changed.fetch('js/documentation.js')).not_to eq(first.fetch('js/documentation.js'))
+  end
+
   it 'uses mounted canonical navigation and keeps shared documentation on its layout' do
     server = HaveAPI::Server.new(get_opt(:api_module))
     server.use_version(1)

data/spec/documentation/oauth_spec.rb

@@ -137,6 +137,25 @@ describe HaveAPI::DocumentationOAuth do
     authorization
   end
 
+  it 'localizes failed browser sign-in without saving a detected language or leaking the thread locale' do
+    previous = ::I18n.locale
+    get 'https://docs.example/api/_documentation/oauth/callback', {}, 'HTTP_ACCEPT_LANGUAGE' => 'cs-CZ'
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to include(::I18n.t('haveapi.documentation.oauth.sign_in_failed', locale: :cs))
+    expect(cookie_headers).not_to include('haveapi.docs.locale')
+    expect(::I18n.locale).to eq(previous)
+  end
+
+  it 'localizes expired-session notices after authentication resolves the API locale' do
+    set_cookie 'haveapi.docs.locale=cs; path=/api/', URI('https://docs.example/api/')
+    sign_in
+    DocumentationOAuthSpec::Config.users = {}
+    get 'https://docs.example/api/v1/'
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).to include(::I18n.t('haveapi.documentation.oauth.session_ended', locale: :cs))
+    expect(last_response.body).not_to include('PRIVATE_ACCESS_TOKEN')
+  end
+
   def cookie_headers
     Array(last_response.headers['set-cookie']).join("\n")
   end
@@ -263,9 +282,32 @@ describe HaveAPI::DocumentationOAuth do
     end
   end
 
+  it 'keeps only the protected sign-out form when switching is unavailable' do
+    sign_in
+    get 'https://docs.example/api/v1/'
+    forms = last_response.body.scan(%r{<form method="post" action="https://docs.example/api/_documentation/oauth/logout">(.*?)</form>}m).flatten
+    expect(forms.length).to eq(1)
+    expect(forms.first).to include('>Sign out</button>')
+    expect(forms.first).to match(/name="csrf" value="[\w-]{43}"/)
+    expect(forms.first).not_to include('name="switch_user"', '>Switch user</button>')
+  end
+
   context 'with valid session CSRF and a switch-capable client' do
     let(:oauth_options) { super().merge(switch_user: true, switch_user_revoke_params: { 'end_shared_session' => '1' }) }
 
+    it 'places the native switch-user form before sign-out without changing their protected fields' do
+      sign_in
+      get 'https://docs.example/api/v1/'
+      forms = last_response.body.scan(%r{<form method="post" action="https://docs.example/api/_documentation/oauth/logout">(.*?)</form>}m).flatten
+      expect(forms.length).to eq(2)
+      expect(forms.first).to include('name="switch_user" value="1"', '>Switch user</button>')
+      expect(forms.last).to include('>Sign out</button>')
+      expect(forms.last).not_to include('name="switch_user"')
+      csrf_fields = forms.map { |form| form[/name="csrf" value="([^"]+)"/, 1] }
+      expect(csrf_fields.first).to match(/\A[\w-]{43}\z/)
+      expect(csrf_fields.last).to eq(csrf_fields.first)
+    end
+
     [nil, 'null', 'https://foreign.example', 'http://docs.example', 'https://docs.example:444'].each do |origin|
       [false, true].each do |switch_user|
         it "rejects #{switch_user ? 'switching' : 'sign-out'} from #{origin || 'an absent Origin'} without sign-out effects" do

data/spec/documentation/search_index_routes_spec.rb

@@ -86,7 +86,7 @@ RSpec.describe HaveAPI::DocumentationSearch::Helpers do
     expect(response.content_type).to match(%r{\Atext/html;\s*charset=utf-8\z})
     expect(response['cache-control']).to eq('private, max-age=86400, immutable')
     expect(response['etag']).to eq(%("#{key}"))
-    expect(response['vary'].split(/,\s*/)).to contain_exactly('X-Language', 'Cookie', 'Authorization')
+    expect(response['vary'].split(/,\s*/)).to contain_exactly('X-Language', 'Accept-Language', 'Cookie', 'Authorization')
     expect(envelope(response)).to include('key' => key)
     expect(response.body).to include('\\u003c/script\\u003e', '\\u0026')
     expect(response.body).not_to include('<!DOCTYPE', 'docs-sidebar', '<script src=', 'fixture')
@@ -139,10 +139,14 @@ RSpec.describe HaveAPI::DocumentationSearch::Helpers do
     expect(envelope(current)['index']).to include('version' => '1', 'base_path' => '/api/v1/')
   end
 
-  it 'binds the projection to resolved locale and canonical Rack/API mounts' do
+  it 'binds the projection to the documentation browser locale independently of the API header and Rack/API mounts' do
     server.available_locales = %i[en cs]
-    english = envelope(request('?page=resources&search_index=current', 'HTTP_X_LANGUAGE' => 'en'))
-    czech = envelope(request('?page=resources&search_index=current', 'HTTP_X_LANGUAGE' => 'cs'))
+    english = envelope(request('?page=resources&search_index=current', 'HTTP_ACCEPT_LANGUAGE' => 'en', 'HTTP_X_LANGUAGE' => 'cs'))
+    czech = envelope(request('?page=resources&search_index=current', 'HTTP_ACCEPT_LANGUAGE' => 'cs', 'HTTP_X_LANGUAGE' => 'en'))
+    custom_header = envelope(request('?page=resources&search_index=current', 'HTTP_X_LANGUAGE' => 'cs'))
+    expect(english['index']['locale']).to eq('en')
+    expect(custom_header['index']['locale']).to eq('en')
+    expect(custom_header['key']).to eq(english['key'])
     expect(english['key']).not_to eq(czech['key'])
     expect(czech['index']['locale']).to eq('cs')
     mounted = envelope(request('?page=resources&search_index=current', 'SCRIPT_NAME' => '/rack'))

data/spec/documentation/search_spec.rb

@@ -12,7 +12,7 @@ RSpec.describe HaveAPI::DocumentationSearch do
     { resources: { widget: { actions: { renew: action }, resources: {} } },
       authentication: { token: { resources: { token: { actions: { request: action }, resources: {} } } } } }
   end
-  let(:presentation) { Object.new.extend(described_class::Helpers) }
+  let(:presentation) { Object.new.extend(HaveAPI::DocumentationLocale).extend(described_class::Helpers) }
 
   def search(query, source = description)
     index = described_class::Index.new(description: source, base_path: '/v1/', version: '1', locale: 'en', visibility: 'anonymous')

data/spec/documentation/shared_pages_spec.rb

@@ -1,5 +1,7 @@
 require 'spec_helper'
 require 'rack/mock'
+require 'cgi'
+require 'ripper'
 
 RSpec.describe HaveAPI::SharedDocumentationHelpers do
   api do
@@ -90,7 +92,7 @@ RSpec.describe HaveAPI::SharedDocumentationHelpers do
       expect(last_response.body).to include(heading, 'aria-label="Breadcrumb"',
                                             'href="/"', 'href="/doc"', 'href="/v1/?page=resources"')
       expect_neutral_shell(last_response.body, 'guide')
-      breadcrumb = last_response.body.match(%r{<nav aria-label="Breadcrumb">(.*?)</nav>}m)[1]
+      breadcrumb = last_response.body.match(%r{<nav class="docs-breadcrumb"[^>]*>(.*?)</nav>}m)[1]
       expect(breadcrumb).to include('API versions', 'HaveAPI internals')
       expect(breadcrumb.scan(/<li\b/).length).to eq(path.match?(%r{\A/doc(?:/(?:index(?:\.md)?|readme))?\z}) ? 2 : 3)
       expect(server).not_to have_received(:describe)
@@ -121,6 +123,65 @@ RSpec.describe HaveAPI::SharedDocumentationHelpers do
     expect(pages.uniq.length).to eq(1)
   end
 
+  def article_samples(body)
+    body.scan(%r{<pre><code(?: class="([^"]*)")?>(.*?)</code></pre>}m).map do |language, source|
+      code = CGI.unescapeHTML(source)
+      if language == 'ruby'
+        Ripper.lex(code).reject { |(_, type, _, _)| %i[on_sp on_nl on_ignored_nl on_comment].include?(type) }
+                        .map { |(_, type, token, _)| [type, token] }
+      else
+        code.lines.reject { |line| line.lstrip.start_with?('#', '//') }.join.strip
+      end
+    end
+  end
+
+  {
+    'readme' => 'Serverová implementace',
+    'protocol' => 'Definice protokolu',
+    'create-client' => 'Definice klienta',
+    'typed-input-validation' => 'Validace typovaných vstupů',
+    'client-examples' => 'Klientské příklady'
+  }.each do |article, heading|
+    it "translates #{article} while preserving its English anchors and noncomment samples" do
+      get "/doc/#{article}", {}, 'HTTP_ACCEPT_LANGUAGE' => 'en'
+      english = last_response.body
+      expect(last_response).to be_ok
+      get "/doc/#{article}", {}, 'HTTP_ACCEPT_LANGUAGE' => 'cs-CZ'
+      czech = last_response.body
+      expect(last_response).to be_ok
+      expect(czech).to include('lang="cs"', heading)
+      expect(czech.scan(/<h[1-6]\b[^>]*\bid="([^"]+)"/).flatten)
+        .to eq(english.scan(/<h[1-6]\b[^>]*\bid="([^"]+)"/).flatten)
+      expect(article_samples(czech)).not_to be_empty
+      expect(article_samples(czech)).to eq(article_samples(english))
+    end
+  end
+
+  it 'uses identical schema code for the English and Czech presentations' do
+    get '/doc/json-schema', {}, 'HTTP_ACCEPT_LANGUAGE' => 'en'
+    english = last_response.body
+    get '/doc/json-schema', {}, 'HTTP_ACCEPT_LANGUAGE' => 'cs'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('<h1 id="envelope">Obálka</h1>')
+    expect(article_samples(last_response.body)).to eq(article_samples(english))
+  end
+
+  it 'keeps translated article and shared asset links mounted under Rack and API prefixes' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.mount('/api/')
+    request = Rack::MockRequest.new(server.app)
+    response = request.get('/api/doc/protocol', 'HTTP_HOST' => 'example.test',
+                                                'SCRIPT_NAME' => '/rack', 'HTTP_ACCEPT_LANGUAGE' => 'cs')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('href="/rack/api/doc/typed-input-validation"',
+                                     'src="/rack/api/doc/protocol.png"')
+    response = request.get('/api/doc/client-examples', 'HTTP_HOST' => 'example.test',
+                                                       'SCRIPT_NAME' => '/rack', 'HTTP_ACCEPT_LANGUAGE' => 'cs')
+    expect(response.body).to include('href="/rack/api/doc/documentation-ui"',
+                                     'href="/rack/api/doc/documentation-oauth"')
+  end
+
   it 'uses configured escaped identity or the actual host and port in neutral titles and brand' do
     server = HaveAPI::Server.new(get_opt(:api_module))
     server.use_version(1)
@@ -191,7 +252,7 @@ RSpec.describe HaveAPI::SharedDocumentationHelpers do
       expect(response['Cache-Control']).to eq('private, no-store')
       expect(response.body).to include('href="/rack/api/"', 'href="/rack/api/doc"',
                                        'href="/rack/api/v1/"', 'href="/rack/api/v1/?page=resources"',
-                                       'src="/rack/js/documentation.js"')
+                                       "src=\"/rack/js/documentation.js?v=#{HaveAPI::DocumentationHelpers::ASSET_DIGESTS.fetch('js/documentation.js')}\"")
       expect(response.body).not_to include('href="/doc"', 'href="/v1/"')
     end
   end