JA localization prep: <NT> marker, .mdx renames, and duplicate API sidebar labels

[matenadasdi]

Infrastructure prep split out of #140, so the risky parts of that PR can be reviewed on their own. No user-visible change except three corrected API reference sidebar labels.

#140 bundles three separable things: infrastructure, the translation pipeline (scripts + 3 workflows), and content (i18n/ja/ + one translated page). This is the first — the pieces that are inert on their own, are prerequisites for everything else, and carry the build risk worth isolating.

What's here

<NT> do-not-translate marker (src/components/NT) — renders a bare <span translate="no">. Nothing is tagged yet; this lands the component so the tagging pass (~17k wraps across ~500 files) can be reviewed on its own, against a repo that already builds with NT in place.

Two supporting changes it depends on:

• NT added to ALLOWED in docusaurus.config.ts. The preprocessor escapes any JSX tag not on that list, so without this every <NT> would render as literal escaped text.
• scripts/check-links-source.js now strips JSX/MDX tags before slugifying headings. Docusaurus renders a heading's element tree to plain text first, so ## The <NT>Dashboards</NT> page anchors at the-dashboards-page. Without the strip, the tag delimiters are dropped by the punctuation pass but the tag name survives as word characters (the-ntdashboardsnt-page), and the checker would flag every tagged heading as a broken anchor.

83 .md → .mdx renames. add_notranslate_tags.py globs **/*.mdx only, so these pages would be silently skipped by the tagging pass. Content is byte-identical; routes are unaffected (every page carries an explicit slug:), so no redirects are needed. The real change is that docusaurus.config.ts's preprocessor is gated on .mdx, so these pages now go through expandListPartials and the JSX escaper and are parsed as MDX rather than CommonMark. That surfaced two unclosed <br> tags, fixed in a follow-up commit.

MCP sync kept in step (scripts/sync_mcp_docs.py). Two problems the rename creates, both fixed at the source since these files are generated and hand-edits don't survive a sync:

• The script wrote each page under the source repo's own .md filename. With those eight pages now .mdx, the next sync would write a second .md copy of each — two files with the same explicit slug, a duplicate route.
• <br> → <br/> is now applied as a sync-time transform, so the fix above isn't reverted by the next run.

Duplicate API sidebar labels (scripts/patch-api-info.js). Three generated operations share a summary with another operation. Docusaurus derives i18n translation keys from sidebar labels, so a duplicate breaks docusaurus write-translations outright — which is how these surfaced. The specs are themselves synced/generated and the plugin regenerates the pages on every run, so the fix goes in the existing patch script as an explicit keyed map. Both the page frontmatter and the separate label in the generated sidebar.ts need patching; sidebar.ts is what Docusaurus actually reads.

CLAUDE.md records the rule. The old guidance — use .md when a page has no JSX, rename only when adding a partial or <Tabs> — is now backwards: <NT> is JSX, so a .md page physically cannot carry one, and the tagging pass globs **/*.mdx, meaning a stray .md page is skipped with no error. Rewritten as an .mdx-only rule, with the two consequences that turned up as real build failures here (MDX parsing, and the preprocessor being gated on the extension) and the requirement that scripts writing pages pin the extension too. Also fixes the stale index.md topichead reference and the layout table's page row.

Verified

• npm run build — green for both en and ja. Only warnings are pre-existing and unrelated (two unreadable _paligo SVGs, docusaurus-plugin-llms description length).
• node scripts/check-links-source.js — clean, 631 files.
• node scripts/patch-api-info.js re-run over the patched tree — no diff, idempotent.
• python3 scripts/sync_mcp_docs.py against a real sync — reapplies both <br/>, produces no stray .md files.
• <NT> end-to-end. Temporarily tagged one page in the four placements most likely to break, built, then reverted. All render as <span translate="no">, none leak as escaped literals, and — the one that mattered — a heading anchor is unchanged: ## Changing your <NT>project settings</NT> still emits id="changing-your-project-settings", confirming the check-links-source.js fix matches Docusaurus's real behavior.
  • plain body text ✅
  • inside a heading (anchor generation) ✅
  • inside an admonition title (:::note[First <NT>workspace</NT>]) ✅
  • wrapping an existing <GlossTerm> ✅

Deliberately not here

• The locale dropdown and its navbar CSS. The CSS exists to make the dropdown readable on the purple header, so it's dead on its own — and adding the dropdown makes /ja/ discoverable while ~440 of its pages are still English. Both belong with the locale-switch work.
• The tagging pass itself. ~17k wraps; its own PR.
• Scripts, workflows, localization/, i18n/ja/. The pipeline PR.

Follow-up found while testing (out of scope, separate PR)

sync_mcp_docs.py's rewrite_internal_links() still emits /en/-prefixed targets, so a sync run reintroduces eight links that 51f565b stripped repo-wide. Those break under any non-default locale (/ja/en/...). Pre-existing on main and unrelated to the rename, so left alone here.

🤖 Generated with Claude Code

[github-actions]

Preview: https://ja-infra-prep.bitrise-docs.pages.dev