openclaw - 💡(How to fix) Fix Docs language switcher loses page path (Mintlify platform behavior) [1 comments, 2 participants]

Related

• Previous issue: #34021 (closed by stale bot, same problem)
• Attempted fix PRs: #73415, #73436 (closed — see explanation below)

Problem

When switching languages via the Mintlify language dropdown (top-left), the site navigates to the target locale's homepage instead of the equivalent page.

Reproduction:

1. Open https://docs.openclaw.ai/install/docker
2. Click the language dropdown → select 简体中文
3. Expected: navigates to /zh-CN/install/docker
4. Actual: navigates to /zh-CN (Chinese homepage)

Same behavior in reverse — switching from any Chinese page back to English also loses the path.

Technical analysis

This is a Mintlify platform behavior, not a bug in OpenClaw's docs content or config. We inspected the live DOM via Puppeteer and found:

The dropdown items are <div>, not <a>

// Puppeteer result from live docs.openclaw.ai
{
  id: "localization-select-item-zh-Hans",
  tag: "DIV",           // not "A"
  href: null,           // no href at all
  text: "简体中文",
  selected: "false"
}

All 14 language items are <div role="menuitem"> elements rendered lazily by Radix UI when the dropdown opens. There are no <a href="..."> links — navigation is handled entirely by Mintlify's internal JavaScript. This means there's no client-side hook to intercept and rewrite the target URL.

CSS selectors confirmed

Mintlify's localization dropdown uses these IDs (matching their custom-scripts docs):

The item id encodes the Mintlify locale code: localization-select-item-{locale} (e.g. zh-Hans, ja, es).

Locale code → URL prefix mapping

The Mintlify language code doesn't always match the URL prefix used in docs.json navigation:

Existing custom JS files are not served

The repo already has docs/nav-tabs-underline.js and docs/style.css, but both return 404 on the live site:

curl -sI "https://docs.openclaw.ai/nav-tabs-underline.js"   → 404
curl -sI "https://docs.openclaw.ai/style.css"               → 404

This means Mintlify does not automatically serve .js files from the docs root, contradicting their documentation that says "Mintlify includes any .js file inside your content directory on every page".

Why we couldn't fix it

We attempted two PRs (#73415, #73436) adding a docs/locale-path-preserve.js script that would intercept the dropdown click and navigate to the preserved path. Both were closed by @steipete because:

1. docs/docs.json has no custom-script configuration field
2. The existing custom JS files in the repo are not actually served by Mintlify
3. Locale config is generated by scripts/docs-sync-publish.mjs from GENERATED_LOCALES — a hardcoded list would drift from that source of truth
4. We couldn't verify the fix locally — npx mintlify dev hangs on this repo (possibly needs auth or the large docs.json causes issues)

We agree the approach of adding a standalone JS file is too fragile without understanding how Mintlify's custom-script integration actually works in this repo's publish pipeline.

Possible approaches

1. Mintlify-side fix: Report to Mintlify that their language switcher should preserve the current page path when switching locales. This is ultimately their responsibility.
2. Publish pipeline: If Mintlify supports custom scripts through a config mechanism, wire it through docs/docs.json and the sync pipeline so it's properly deployed.
3. Mintlify local dev: If there's a way to run mintlify dev against this repo (auth token? smaller config?), that would unblock local verification and future contributions.

Reproduction script (Puppeteer)

For anyone who wants to verify the DOM findings independently:

cd /tmp && npm install puppeteer-core

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.launch({
  headless: 'new',
  executablePath: '<your-chrome-binary>',
  args: ['--no-sandbox']
});
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 900 });
await page.goto('https://docs.openclaw.ai/start/getting-started', { waitUntil: 'networkidle2' });

// Click language trigger
const { x, y } = await page.evaluate(() => {
  const r = document.querySelector('#localization-select-trigger').getBoundingClientRect();
  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
});
await page.mouse.click(x, y);
await new Promise(r => setTimeout(r, 2000));

// Inspect dropdown items
const items = await page.evaluate(() =>
  Array.from(document.querySelectorAll('[role=menuitem]')).map(el => ({
    id: el.id, tag: el.tagName, href: el.getAttribute('href'),
    text: el.textContent.trim(), selected: el.dataset.selected
  }))
);
console.log(JSON.stringify(items, null, 2));
await browser.close();

Or in-browser: F12 → Console → expand language dropdown → run:

document.querySelectorAll('[role=menuitem]').forEach(el =>
  console.log(el.id, el.tagName, el.getAttribute('href'))
);