@master/internal-site 0.1.3 → 0.2.0

package/src/docs-shell/utils/localized-metadata.ts

@@ -0,0 +1,22 @@
+/** Prose can vary by locale; publication identity and technical configuration stay with the source. */
+export function localizedMetadata(metadata: Record<string, any>, frontmatter: Record<string, any>, locale: string) {
+  const localized: Record<string, any> = { ...metadata, locale }
+  for (const key of ['description', 'subtitle']) if (typeof frontmatter[key] === 'string') localized[key] = frontmatter[key]
+  if (typeof frontmatter.title === 'string') {
+    localized.title = metadata.title && typeof metadata.title === 'object'
+      ? { ...metadata.title, ...('absolute' in metadata.title ? { absolute: frontmatter.title } : { default: frontmatter.title }) }
+      : frontmatter.title
+  }
+  if (metadata.cover && typeof frontmatter.cover?.alt === 'string') localized.cover = { ...metadata.cover, alt: frontmatter.cover.alt }
+  for (const channel of ['openGraph', 'twitter']) {
+    const authored = frontmatter[channel]
+    if (metadata[channel] || authored) {
+      const prose = Object.fromEntries(['title', 'description'].flatMap(key => {
+        const text = authored?.[key] ?? (locale !== 'en' ? frontmatter[key] : undefined)
+        return typeof text === 'string' ? [[key, text]] : []
+      }))
+      localized[channel] = { ...metadata[channel], ...prose }
+    }
+  }
+  return localized
+}

package/src/docs-shell/utils/markdown-links.ts

@@ -0,0 +1,61 @@
+import { markdownTree } from './markdown-tree'
+
+interface LinkNode {
+  type: string
+  url?: string
+  children?: LinkNode[]
+  position?: { start: { offset: number }; end: { offset: number } }
+}
+
+function destination(source: string, node: LinkNode): { start: number; end: number; angled: boolean } {
+  const { start, end } = node.position!
+  let at = start.offset
+  if (node.type === 'definition') {
+    for (; at < end.offset; at++) {
+      if (source[at] === '\\') { at++; continue }
+      if (source[at] === ']' && source[at + 1] === ':') { at += 2; break }
+    }
+  } else if (source[at] === '[') {
+    // Child positions include inline-code and nested formatting in the label.
+    at = node.children?.at(-1)?.position?.end.offset ?? at + 1
+    at = source.indexOf('](', at) + 2
+    if (at < 2) throw new Error(`Missing Markdown link destination: ${node.url}`)
+  } else {
+    // GFM bare links and CommonMark angle autolinks have no bracketed label.
+    const angled = source[at] === '<'
+    return { start: at + Number(angled), end: end.offset - Number(angled), angled }
+  }
+  while (/\s/.test(source[at] ?? '') && at < end.offset) at++
+  const angled = source[at] === '<'
+  const begin = at + Number(angled)
+  at = begin
+  let depth = 0
+  for (; at < end.offset; at++) {
+    const character = source[at]
+    if (character === '\\') { at++; continue }
+    if (angled ? character === '>' : /\s/.test(character) || (character === ')' && depth === 0)) break
+    if (!angled && character === '(') depth++
+    else if (!angled && character === ')') depth--
+  }
+  return { start: begin, end: at, angled }
+}
+
+/** Edit actual Markdown link/definition URLs without reserializing prose or code. */
+export function transformMarkdownLinks(markdown: string, mapper: (url: string) => string): string {
+  const edits: { start: number; end: number; value: string }[] = []
+  function visit(node: LinkNode) {
+    if ((node.type === 'link' || node.type === 'definition') && node.position && typeof node.url === 'string') {
+      const mapped = mapper(node.url)
+      if (mapped !== node.url) {
+        const range = destination(markdown, node)
+        const escaped = mapped.replace(/([\\<>])/g, '\\$1')
+        const value = range.angled ? escaped : /\s/.test(mapped) ? `<${escaped}>` : escaped.replace(/([()])/g, '\\$1')
+        edits.push({ ...range, value })
+      }
+    }
+    node.children?.forEach(visit)
+  }
+  visit(markdownTree(markdown) as LinkNode)
+  for (const edit of edits.sort((a, b) => b.start - a.start)) markdown = markdown.slice(0, edit.start) + edit.value + markdown.slice(edit.end)
+  return markdown
+}

package/src/docs-shell/utils/markdown-tree.ts

@@ -1,19 +1,32 @@
 import { remark } from 'remark'
 import gfm from 'remark-gfm'
-import Slugger from 'github-slugger'
-import resolveHeading from './resolve-heading'
+import resolveHeading, { createHeadingResolver } from './resolve-heading'
 
 const parser = remark().use(gfm)
-export const markdownTree = (source: string) => parser.parse(source)
+export function markdownTree(source: string) {
+  const tree = parser.parse(source)
+  const resolveHeading = createHeadingResolver()
+  function visit(node: any) {
+    if (node.type === 'heading' && node.depth >= 2 && node.depth <= 6) {
+      const title = node.children.filter((child: any) => child.type === 'text' || child.type === 'inlineCode').map((child: any) => child.value).join(' ').trim()
+      const resolved = resolveHeading(title, node.depth)
+      node.data ??= {}
+      node.data.id = resolved.id
+      node.data.hProperties = { ...node.data.hProperties, id: resolved.id }
+    }
+    node.children?.forEach(visit)
+  }
+  visit(tree)
+  return tree
+}
 
 export function markdownHeadings(source: string) {
-  const slugger = new Slugger()
   const headings: { id: string; title: string; depth: number }[] = []
   function visit(node: any) {
     if (node.type === 'heading' && (node.depth === 2 || node.depth === 3)) {
       const title = node.children.filter((child: any) => child.type === 'text' || child.type === 'inlineCode').map((child: any) => child.value).join(' ').trim()
-      const resolved = resolveHeading(title, slugger.slug(title))
-      headings.push({ id: resolved.id!, title: resolved.title, depth: node.depth })
+      const resolved = resolveHeading(title, node.data.hProperties.id)
+      headings.push({ id: node.data.hProperties.id, title: resolved.title, depth: node.depth })
     }
     node.children?.forEach(visit)
   }

package/src/docs-shell/utils/resolve-heading.d.ts

@@ -1 +1,2 @@
 export default function resolveHeading(title: string, id?: string): { title: string; id?: string; className?: string }
+export function createHeadingResolver(): (title: string, depth: number) => { title: string; id?: string; className?: string; explicit: boolean }

package/src/docs-shell/utils/resolve-heading.js

@@ -1,3 +1,5 @@
+import Slugger from 'github-slugger'
+
 export default function resolveHeading(title, id) {
   const explicit = typeof title === 'string' && title.match(/\s+\{#([\w-]+)\}$/)
   if (explicit) {
@@ -17,3 +19,22 @@ export default function resolveHeading(title, id) {
   }
   return { title, id }
 }
+
+/** Section counters stay stable when a detail heading is inserted between them. */
+export function createHeadingResolver() {
+  const sections = new Slugger()
+  const details = new Slugger()
+  const assigned = new Set()
+  return (title, depth) => {
+    const explicit = /\s+\{#[\w-]+\}$/.test(title)
+    let heading
+    if (explicit) heading = resolveHeading(title)
+    else {
+      const slugs = depth === 2 || depth === 3 ? sections : details
+      do { heading = resolveHeading(title, slugs.slug(title)) }
+      while (heading.id && assigned.has(heading.id))
+    }
+    if (heading.id) assigned.add(heading.id)
+    return { ...heading, explicit }
+  }
+}

package/src/docs-shell/utils/search-pages.ts

@@ -1,15 +1,29 @@
 import FastGlob from 'fast-glob'
-import Slugger from 'github-slugger'
 import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { fromMarkdown } from 'mdast-util-from-markdown'
+import { remark } from 'remark'
+import gfm from 'remark-gfm'
 import { mdxjsEsm } from 'micromark-extension-mdxjs-esm'
+import { mdxJsx } from 'micromark-extension-mdx-jsx'
+import { mdxJsxFromMarkdown } from 'mdast-util-mdx-jsx'
 import { mdxjsEsmFromMarkdown } from 'mdast-util-mdxjs-esm'
 import * as acorn from 'acorn'
-import resolveHeading from './resolve-heading.js'
+import { createHeadingResolver } from './resolve-heading.js'
 import { writeIfChangedSync } from '../../scripts/write-if-changed'
 import { localizePathname, type LocalePrefixMode } from './i18n-pathname.js'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
+import { localizedMetadata } from './localized-metadata'
+
+// Parse complete MDX boundaries so imports in example props are not mistaken for article ESM.
+const markdownParser = remark().use(gfm)
+const searchParser = remark().use(gfm).use(function mdxSearchSyntax() {
+  const data = this.data()
+  ;(data.micromarkExtensions ??= []).push({ disable: { null: ['htmlFlow', 'htmlText', 'codeIndented'] } }, mdxjsEsm({ acorn, addResult: true }), mdxJsx({ acorn, addResult: true }))
+  // Consumers may resolve another mdast type version through remark-parse.
+  const extensions = [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
+  ;(data.fromMarkdownExtensions ??= []).push(...extensions as unknown as NonNullable<typeof data.fromMarkdownExtensions>)
+})
 
 const DEFAULT_METADATA_GLOB = './content/**/*metadata.ts'
 
@@ -63,6 +77,7 @@ interface MdxNode {
   depth?: number
   type: string
   value?: string
+  explicitId?: string
 }
 
 export async function generateSearchPages({
@@ -82,6 +97,12 @@ export async function generateSearchPages({
     const translations = loadDictionaryTranslations(dictionariesDir, locale)
     const translate = createDictionaryTranslate(translations)
     const pages = entries
+      .filter(entry => {
+        if (entry.metadata.draft) return false
+        const content = locale === defaultLocale ? entry.content : entry.localizedContent?.[locale]
+        if (locale !== defaultLocale && entry.content && !content) return false
+        return parseFrontmatter(content ?? '').frontmatter.draft !== true
+      })
       .map((entry) => createSearchPage({ defaultLocale, entry, locale, translate }))
       .sort((a, b) => a.url.localeCompare(b.url))
     result[locale] = pages
@@ -102,7 +123,7 @@ export async function loadSearchPageEntries({
     .filter((metadataPath) => (existsSync(resolve(cwd, dirname(metadataPath), 'page.astro')) || existsSync(resolve(cwd, dirname(metadataPath), 'content.mdx'))))
     .sort()
 
-  return await Promise.all(metadataPaths.map(async (metadataPath) => {
+  return (await Promise.all(metadataPaths.map(async (metadataPath) => {
     const metadataModule = await import(pathToFileURL(resolve(cwd, metadataPath)).href)
     const contentPath = resolve(cwd, dirname(metadataPath), 'content.mdx')
     const contentDir = resolve(cwd, dirname(metadataPath))
@@ -112,7 +133,7 @@ export async function loadSearchPageEntries({
       metadata: metadataModule.default,
       metadataPath
     }
-  }))
+  }))).filter(entry => !entry.metadata.draft && !parseFrontmatter(entry.content ?? '').frontmatter.draft)
 }
 
 export function createSearchPage({
@@ -121,11 +142,15 @@ export function createSearchPage({
   locale,
   translate = (text) => text
 }: CreateSearchPageOptions): SearchPage {
-  const { metadata } = entry
+  const source = locale === defaultLocale ? entry.content : entry.localizedContent?.[locale]
+  if (locale !== defaultLocale && entry.content && !source) throw new Error(`Missing search translation: ${entry.metadata.pathname} (${locale})`)
+  const parsed = source === undefined ? undefined : parseFrontmatter(source)
+  if (parsed?.frontmatter.draft) throw new Error(`Draft translation cannot be indexed: ${entry.metadata.pathname} (${locale})`)
+  const metadata = localizedMetadata(entry.metadata, parsed?.frontmatter ?? {}, locale)
   const title = translate(resolveMetadataString(metadata.title))
   const description = translate(resolveMetadataString(metadata.description))
   const category = translate(resolveMetadataString(metadata.category))
-  const content = entry.localizedContent?.[locale] ?? entry.content
+  const content = parsed?.content
   const page: SearchPage = {
     category,
     description,
@@ -170,26 +195,50 @@ export function createLocalizedPathname(pathname: string, locale: string, defaul
 }
 
 export function extractSearchNodesFromMdx(source: string): SearchNode[] {
-  const tree = fromMarkdown(source, {
-    extensions: [mdxjsEsm({ acorn, addResult: true })],
-    mdastExtensions: [mdxjsEsmFromMarkdown()]
-  }) as MdxNode
+  const tree = searchParser.parse(parseFrontmatter(source).content) as MdxNode
+  return searchNodesFromTree(tree)
+}
+
+/** Portable exports are Markdown and may include native HTML comments or type notation. */
+export function extractSearchNodesFromMarkdown(source: string): SearchNode[] {
+  const tree = markdownParser.parse(parseFrontmatter(source).content) as MdxNode
+  function resolvePortableAnchors(parent: MdxNode) {
+    let pendingId: string | undefined
+    for (const node of parent.children ?? []) {
+      const markup = node.type === 'html' ? node.value : node.type === 'paragraph'
+        && node.children?.every(child => child.type === 'html' || (child.type === 'text' && !child.value?.trim()))
+        ? node.children.map(child => child.value ?? '').join('') : undefined
+      const anchors = [...(markup ?? '').matchAll(/<a\s+id="([^"]+)"\s*><\/a>/g)]
+      if (anchors.length && !markup!.replace(/<a\s+id="([^"]+)"\s*><\/a>/g, '').trim()) {
+        pendingId = anchors.at(-1)![1]
+        continue
+      }
+      if (node.type === 'heading' && pendingId) node.explicitId = pendingId
+      pendingId = undefined
+      if (node.children) resolvePortableAnchors(node)
+    }
+  }
+  resolvePortableAnchors(tree)
+  return searchNodesFromTree(tree)
+}
+
+function searchNodesFromTree(tree: MdxNode): SearchNode[] {
   const nodes: SearchNode[] = []
-  const slugger = new Slugger()
-  appendSearchNodes(tree.children ?? [], nodes, slugger)
+  const resolveHeading = createHeadingResolver()
+  appendSearchNodes(tree.children ?? [], nodes, resolveHeading)
   return nodes
 }
 
-function appendSearchNodes(children: MdxNode[], nodes: SearchNode[], slugger: Slugger) {
+function appendSearchNodes(children: MdxNode[], nodes: SearchNode[], resolveHeading: ReturnType<typeof createHeadingResolver>) {
   for (const child of children) {
-    appendSearchNode(child, nodes, slugger)
+    appendSearchNode(child, nodes, resolveHeading)
   }
 }
 
-function appendSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger) {
+function appendSearchNode(node: MdxNode, nodes: SearchNode[], resolveHeading: ReturnType<typeof createHeadingResolver>) {
   switch (node.type) {
     case 'heading':
-      appendHeadingSearchNode(node, nodes, slugger)
+      appendHeadingSearchNode(node, nodes, resolveHeading)
       return
     case 'paragraph':
       appendTextSearchNode(nodes, collectText(node), 'p')
@@ -202,8 +251,11 @@ function appendSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger)
         appendTextSearchNode(nodes, collectText(child), 'li')
       }
       return
+    case 'table':
+      for (const row of node.children ?? []) appendTextSearchNode(nodes, (row.children ?? []).map(collectText).join(' | '), 'tr')
+      return
     case 'blockquote':
-      appendSearchNodes(node.children ?? [], nodes, slugger)
+      appendSearchNodes(node.children ?? [], nodes, resolveHeading)
       return
     case 'mdxjsEsm':
     case 'html':
@@ -212,18 +264,19 @@ function appendSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger)
       return
     default:
       if (node.children?.length) {
-        appendSearchNodes(node.children, nodes, slugger)
+        appendSearchNodes(node.children, nodes, resolveHeading)
       }
   }
 }
 
-function appendHeadingSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger) {
+function appendHeadingSearchNode(node: MdxNode, nodes: SearchNode[], resolveHeading: ReturnType<typeof createHeadingResolver>) {
   const text = normalizeSearchText((node.children ?? []).filter(child => child.type === 'text' || child.type === 'inlineCode').map(child => child.value).join(' '))
   if (!text) return
 
   const tag = node.depth ? `h${node.depth}` : 'h'
-  if (node.depth === 2 || node.depth === 3) {
-    const resolved = resolveHeading(text, slugger.slug(text))
+  if (node.depth && node.depth >= 2 && node.depth <= 6) {
+    const title = node.explicitId && !/\{#[\w-]+\}/.test(text) ? `${text} {#${node.explicitId}}` : text
+    const resolved = resolveHeading(title, node.depth)
     appendTextSearchNode(nodes, resolved.title, tag, resolved.id)
     return
   }

package/src/home/hero.css

@@ -238,6 +238,11 @@
     color: var(--home-text);
     text-wrap: balance;
     overflow-wrap: anywhere;
+
+    /* Keep Japanese phrases and Korean words intact; very narrow enlarged text can still wrap in an emergency. */
+    &:is(:lang(ja), :lang(ko)) {
+      word-break: keep-all;
+    }
   }
 
   .home-display-line {

package/src/layouts/Document.astro

@@ -50,7 +50,7 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
     <script is:inline blocking="render" set:html={themeScript}></script>
     <link blocking="render" rel="preload" as="font" href="/fonts/GeistVariable.woff2" crossorigin="anonymous" />
     <link blocking="render" rel="preload" as="font" href="/fonts/IBMPlexMono-Regular.woff2" crossorigin="anonymous" />
-    {(site.locale === 'tw' || basePathname === '/brand') && <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+TC:wght@100..900&display=swap" rel="stylesheet" />}
+    {(site.locale !== 'en' || basePathname === '/brand') && <link href={`https://fonts.googleapis.com/css2?family=Noto+Sans+${({ ja: 'JP', ko: 'KR', cn: 'SC' } as Record<string, string>)[site.locale] ?? 'TC'}:wght@100..900&display=swap`} rel="stylesheet" />}
     <style is:inline blocking="render" set:html={fontCSS}></style>
     {/* client:load islands can hydrate while a streamed body is still parsing.
         Their request-local context must already exist, even with cached CSS/JS. */}

package/src/scripts/localization.ts

@@ -0,0 +1,239 @@
+import { createHash } from 'node:crypto'
+import { readFile, readdir } from 'node:fs/promises'
+import { basename, dirname, join, relative, resolve, extname, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { mdxjsEsm } from 'micromark-extension-mdxjs-esm'
+import { mdxjsEsmFromMarkdown } from 'mdast-util-mdxjs-esm'
+import { mdxJsx } from 'micromark-extension-mdx-jsx'
+import { mdxJsxFromMarkdown } from 'mdast-util-mdx-jsx'
+import * as acorn from 'acorn'
+import { createHeadingResolver } from '../docs-shell/utils/resolve-heading.js'
+import { locales as supportedLocales, defaultLocale as sourceLocale } from '../docs-shell/common/locales.js'
+import { localizedMetadata } from '../docs-shell/utils/localized-metadata.ts'
+import { isSharedMdxSample } from './mdx-sample'
+export { localizedMetadata } from '../docs-shell/utils/localized-metadata.ts'
+
+export interface TranslationResource {
+  id: string
+  source: string
+  translations: Record<string, string | undefined>
+  /** Source-only data or metadata whose changes require another translation review. */
+  dependencies?: Record<string, string>
+  locales?: readonly string[]
+  draft?: boolean
+  checkAnchors?: boolean
+  requireMetadata?: boolean
+}
+export interface TranslationReview { sourceHash: string; translationHash: string }
+export interface TranslationReviews { version: 1; resources: Record<string, Record<string, TranslationReview>> }
+export interface LocalizationOptions { locales?: readonly string[]; defaultLocale?: string }
+export interface TranslationDiagnostic { id: string; locale: string; reason: 'missing' | 'unreviewed' | 'source-changed' | 'translation-changed' | 'anchors' | 'metadata'; message: string }
+
+export const emptyReviews = (): TranslationReviews => ({ version: 1, resources: {} })
+const hash = (value: string) => createHash('sha256').update(value.replaceAll('\r\n', '\n')).digest('hex')
+const sourceHash = (resource: TranslationResource) => hash(JSON.stringify([resource.source, Object.entries(resource.dependencies ?? {}).sort(([a], [b]) => a.localeCompare(b))]))
+
+/** Explicit review operation. Preparation and production builds never call this function. */
+export function reviewTranslation(resource: TranslationResource, locale: string): TranslationReview {
+  const translation = resource.translations[locale]
+  if (!translation?.trim()) throw new Error(`Missing translation: ${resource.id} (${locale})`)
+  return { sourceHash: sourceHash(resource), translationHash: hash(translation) }
+}
+
+export function auditTranslations(resources: readonly TranslationResource[], reviews: TranslationReviews, { locales = supportedLocales, defaultLocale = sourceLocale }: LocalizationOptions = {}): TranslationDiagnostic[] {
+  if (reviews.version !== 1 || !reviews.resources) throw new Error('Unsupported translation review index; expected version 1')
+  const diagnostics: TranslationDiagnostic[] = []
+  const ids = new Set<string>()
+  for (const resource of resources) {
+    if (ids.has(resource.id)) throw new Error(`Duplicate translation resource: ${resource.id}`)
+    ids.add(resource.id)
+    if (resource.draft) continue
+    for (const locale of resource.locales ?? locales) {
+      if (locale === defaultLocale) continue
+      const report = (reason: TranslationDiagnostic['reason'], message: string) => diagnostics.push({ id: resource.id, locale, reason, message })
+      const translation = resource.translations[locale]
+      if (!translation?.trim()) { report('missing', 'Translation is missing'); continue }
+      if (parseFrontmatter(translation).frontmatter.draft === true) { report('missing', 'Translation is a draft and is not available for publication'); continue }
+      const review = reviews.resources[resource.id]?.[locale]
+      if (!review) report('unreviewed', 'Translation has not been reviewed')
+      else {
+        if (review.sourceHash !== sourceHash(resource)) report('source-changed', 'English source changed after translation review')
+        if (review.translationHash !== hash(translation)) report('translation-changed', 'Translation changed after review')
+      }
+      if (resource.checkAnchors) {
+        const expected = headingAnchors(resource.source)
+        const actual = headingAnchors(translation)
+        if (new Set(actual).size !== actual.length || JSON.stringify(expected) !== JSON.stringify(actual)) report('anchors', 'Translated heading IDs must preserve source IDs and order')
+      }
+      if (resource.requireMetadata) {
+        const { frontmatter } = parseFrontmatter(translation)
+        if (typeof frontmatter.title !== 'string' || !frontmatter.title.trim() || typeof frontmatter.description !== 'string' || !frontmatter.description.trim()) report('metadata', 'Localized MDX requires title and description frontmatter')
+      }
+    }
+  }
+  return diagnostics
+}
+
+export function assertTranslations(resources: readonly TranslationResource[], reviews: TranslationReviews, options: LocalizationOptions = {}) {
+  const diagnostics = auditTranslations(resources, reviews, options)
+  if (diagnostics.length) throw new Error(`Translation completeness check failed (${diagnostics.length}):\n${diagnostics.map(issue => `${issue.id} [${issue.locale}] ${issue.reason}: ${issue.message}`).join('\n')}`)
+}
+
+/** Shared Astro build gate, also usable by a consumer's explicit audit command. */
+export async function validateSiteTranslations({ validation, ...options }: LocalizationOptions & { validation?: { reviews: URL; resources: URL } }) {
+  const locales = options.locales ?? supportedLocales
+  if (!validation) {
+    if (locales.some(locale => locale !== (options.defaultLocale ?? sourceLocale))) throw new Error('Multilingual production builds require i18n.validation resources and reviews')
+    return
+  }
+  const [{ default: load }, raw] = await Promise.all([import(validation.resources.href), readFile(validation.reviews, 'utf8')])
+  const resources: TranslationResource[] = typeof load === 'function' ? await load() : load
+  if (!Array.isArray(resources) || resources.length === 0) throw new Error('Translation resource loader must return a nonempty resource inventory')
+  assertTranslations(resources, JSON.parse(raw), options)
+}
+
+export async function readLocalizedDocument({ sourceFile, locale, defaultLocale = sourceLocale, metadata = {} }: { sourceFile: string; locale: string; defaultLocale?: string; metadata?: Record<string, any> }) {
+  const original = sourceFile.replace(/\.([a-z]{2})\.mdx$/, '.mdx')
+  const file = locale === defaultLocale ? original : original.replace(/\.mdx$/, `.${locale}.mdx`)
+  let source: string
+  try { source = await readFile(file, 'utf8') }
+  catch (cause) { throw new Error(`Missing localized document: ${file} (${locale})`, { cause }) }
+  const { content, frontmatter } = parseFrontmatter(source)
+  return { file, content, frontmatter, metadata: localizedMetadata(metadata, frontmatter, locale) }
+}
+
+async function filesOf(directory: string): Promise<string[]> {
+  const files: string[] = []
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue
+    const file = join(directory, entry.name)
+    if (entry.isDirectory()) { if (entry.name !== 'drafts') files.push(...await filesOf(file)) }
+    else files.push(file)
+  }
+  return files.sort()
+}
+
+/** Filesystem inventory, with no page imports, component execution or generated source writes. */
+export async function discoverDocumentResources({ contentRoot, locales = supportedLocales, defaultLocale = sourceLocale, exclude = [], siteRoot = dirname(contentRoot) }: { contentRoot: string; siteRoot?: string; exclude?: readonly string[] } & LocalizationOptions): Promise<TranslationResource[]> {
+  const files = new Set(await filesOf(contentRoot))
+  const resources: TranslationResource[] = []
+  for (const file of files) {
+    if (!file.endsWith('.mdx') || /\.[a-z]{2}\.mdx$/.test(file)) continue
+    const source = await readFile(file, 'utf8')
+    const id = relative(contentRoot, file).replaceAll('\\', '/')
+    if (!source.trim() || exclude.includes(id)) continue
+    // Imported examples remain part of the owner's source dependency digest.
+    if (isSharedMdxSample(file, source)) continue
+    const metadata = join(dirname(file), 'metadata.ts')
+    const sourceMetadata = files.has(metadata) ? await readFile(metadata, 'utf8') : undefined
+    const dependencies = await collectSourceDependencies([file, ...(sourceMetadata ? [metadata] : [])], { siteRoot })
+    delete dependencies[relative(siteRoot, file).replaceAll('\\', '/')]
+    const translations: Record<string, string> = {}
+    for (const locale of locales) {
+      if (locale === defaultLocale) continue
+      const translatedFile = file.replace(/\.mdx$/, `.${locale}.mdx`)
+      if (files.has(translatedFile)) translations[locale] = await readFile(translatedFile, 'utf8')
+    }
+    resources.push({ id, source, translations, dependencies, checkAnchors: true, requireMetadata: basename(file) === 'content.mdx', draft: parseFrontmatter(source).frontmatter.draft === true || /\bdraft\s*:\s*true\b/.test(sourceMetadata ?? '') })
+  }
+  return resources
+}
+
+/** Literal interface requests must exist even when a newly added control has no dictionary entry yet. */
+export async function sharedInterfaceKeys(sourceRoot = join(dirname(fileURLToPath(import.meta.resolve('@master/internal-site/package.json'))), 'src')): Promise<string[]> {
+  const keys = new Set<string>()
+  const visit = async (directory: string) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const file = join(directory, entry.name)
+      if (entry.isDirectory()) await visit(file)
+      else if (/\.(?:astro|svelte|ts|js)$/.test(entry.name) && !/\.(?:test|spec)\./.test(entry.name)) {
+        const source = await readFile(file, 'utf8')
+        for (const match of source.matchAll(/\bt\s*\(\s*(?=['"`])/g)) {
+          const expression = acorn.parseExpressionAt(source, match.index! + match[0].length, { ecmaVersion: 'latest' }) as any
+          const value = expression.type === 'Literal' ? expression.value : expression.type === 'TemplateLiteral' && !expression.expressions.length ? expression.quasis[0].value.cooked : undefined
+          if (typeof value === 'string' && value.trim()) keys.add(value)
+        }
+      }
+    }
+  }
+  await visit(sourceRoot)
+  return [...keys].sort()
+}
+
+/** Follow local prose/data modules without executing them or importing product compiler code. */
+export async function collectSourceDependencies(files: readonly string[], { siteRoot }: { siteRoot: string }): Promise<Record<string, string>> {
+  const root = resolve(siteRoot)
+  const sharedRoot = dirname(fileURLToPath(import.meta.resolve('@master/internal-site/package.json')))
+  const collected: Record<string, string> = {}
+  const seen = new Set<string>()
+  const visit = async (file: string) => {
+    file = resolve(file).replace(/\.(tw|ja|ko|cn)\.mdx$/, '.mdx')
+    if ((!file.startsWith(root + sep) && !file.startsWith(sharedRoot + sep)) || seen.has(file)) return
+    // Localized dictionaries have their own review resource. Their translations
+    // must not masquerade as a change to every article's English source.
+    if (file.startsWith(sharedRoot + sep) && /\/common\/(?:translations|locales)\.[jt]s$/.test(file.replaceAll('\\', '/'))) return
+    seen.add(file)
+    const source = await readFile(file, 'utf8').catch(() => undefined)
+    if (source === undefined) return
+    const key = file.startsWith(sharedRoot + sep) ? `@master/internal-site/${relative(sharedRoot, file)}` : relative(root, file)
+    collected[key.replaceAll('\\', '/')] = source
+    const imports = source.matchAll(/(?:\bfrom\s*|\bimport\s*(?:\(\s*)?)(['"])([^'"\n]+)\1/g)
+    for (const [, , specifier] of imports) {
+      if (!specifier.startsWith('.') && !specifier.startsWith('~/site/') && !specifier.startsWith('@master/internal-site/')) continue
+      let target: string
+      try {
+        target = specifier.startsWith('@master/internal-site/') ? fileURLToPath(import.meta.resolve(specifier.split('?')[0]))
+          : specifier.startsWith('~/site/') ? resolve(root, specifier.slice(7)) : resolve(dirname(file), specifier.split('?')[0])
+      } catch { continue }
+      if (extname(target) && !/\.(?:[cm]?[jt]s|[jt]sx|mdx|astro|svelte)$/.test(target)) continue
+      const candidates = extname(target) ? [target, ...(/\.js$/.test(target) ? [target.replace(/\.js$/, '.ts')] : [])] : ['', '.ts', '.js', '.mdx', '.astro', '.svelte', '/index.ts', '/index.js'].map(suffix => target + suffix)
+      for (const candidate of candidates) {
+        const before = Object.keys(collected).length
+        await visit(candidate)
+        if (Object.keys(collected).length > before) break
+      }
+    }
+  }
+  for (const file of files) await visit(file)
+  return Object.fromEntries(Object.entries(collected).sort(([a], [b]) => a.localeCompare(b)))
+}
+
+function headings(source: string) {
+  const parsed = parseFrontmatter(source)
+  const offset = source.indexOf(parsed.content, parsed.rawFrontmatter ? parsed.rawFrontmatter.length : 0)
+  const tree = fromMarkdown(parsed.content, {
+    extensions: [{ disable: { null: ['htmlFlow', 'htmlText', 'codeIndented'] } }, mdxjsEsm({ acorn, addResult: true }), mdxJsx({ acorn, addResult: true })],
+    mdastExtensions: [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
+  })
+  const resolveHeading = createHeadingResolver()
+  const found: { id: string; explicit: boolean; offset: number }[] = []
+  const visit = (node: any) => {
+    if (node.type === 'heading' && node.depth >= 2 && node.depth <= 6) {
+      const title = node.children.filter((child: any) => child.type === 'text' || child.type === 'inlineCode').map((child: any) => child.value).join(' ').trim()
+      const resolved = resolveHeading(title, node.depth)
+      const raw = parsed.content.slice(node.position.start.offset, node.position.end.offset)
+      const end = raw.includes('\n') ? node.position.start.offset + raw.indexOf('\n') : node.position.end.offset
+      found.push({ id: resolved.id ?? '', explicit: resolved.explicit, offset: Math.max(0, offset) + end })
+    }
+    node.children?.forEach(visit)
+  }
+  visit(tree)
+  return found
+}
+
+export function headingAnchors(source: string): string[] { return headings(source).map(heading => heading.id) }
+
+/** Pin the existing automatic English IDs before translation, without modifying fenced examples. */
+export function stabilizeHeadingAnchors(source: string): string {
+  for (const heading of headings(source).reverse()) {
+    if (heading.explicit || !heading.id) continue
+    // Closing ATX hashes are syntax; the ID belongs before them.
+    const before = source.slice(0, heading.offset)
+    const closing = before.match(/[ \t]+#+[ \t]*$/)?.[0] ?? ''
+    const at = heading.offset - closing.length
+    source = source.slice(0, at) + ` \\{#${heading.id}\\}` + source.slice(at)
+  }
+  return source
+}

package/src/scripts/mdx-sample.ts

@@ -0,0 +1,12 @@
+import { basename } from 'node:path'
+import { parseFrontmatter } from '@astrojs/markdown-remark'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+
+/** Only prose-free companion examples share one source across editions. */
+export function isSharedMdxSample(file: string, source: string): boolean {
+  if (['content.mdx', 'contract.mdx'].includes(basename(file))) return false
+  const { content, frontmatter } = parseFrontmatter(source)
+  if (Object.keys(frontmatter).length) return false
+  const nodes = fromMarkdown(content).children
+  return nodes.length > 0 && nodes.every(node => node.type === 'code')
+}