@master/internal-site 0.1.3 → 0.2.0

package/src/docs-shell/components/DocumentKeyList.astro

@@ -1,5 +1,7 @@
 ---
 import '@master/internal-site/styles/system/disclosure.css'
+import { siteOf } from '../../astro/site-context'
+const { t } = siteOf(Astro)
 
 interface Props {
   keys: string[]
@@ -11,12 +13,12 @@ const { keys, previewCount = keys.length } = Astro.props
 const lists = [keys.slice(0, previewCount), keys.slice(previewCount)]
 ---
 
-<ul aria-label="Utility keys">
+<ul aria-label={t('Utility keys')}>
   {lists[0].map(key => <li><code>{key}</code></li>)}
 </ul>
 {keys.length > previewCount && <details class="ui-disclosure">
-  <summary>Show {keys.length - previewCount} more keys</summary>
-  <ul aria-label="Utility keys">
+  <summary>{t('Show {count} more keys').replace('{count}', String(keys.length - previewCount))}</summary>
+  <ul aria-label={t('Utility keys')}>
     {lists[1].map(key => <li><code>{key}</code></li>)}
   </ul>
 </details>}

package/src/docs-shell/components/DocumentNamespaceTable.astro

@@ -1,6 +1,8 @@
 ---
 import '@master/internal-site/styles/system/table.css'
 import DocumentKeyList from '@master/internal-site/components/DocumentKeyList.astro'
+import { siteOf } from '../../astro/site-context'
+const { t } = siteOf(Astro)
 
 interface Props {
   rows: { namespace: string, consumers: string[] }[]
@@ -11,8 +13,8 @@ const { rows } = Astro.props
 ---
 
 {/* The table's narrow overflow region must be focusable for native keyboard scrolling. */}
-<div class="ui-table" data-variant="lookup" role="region" aria-label="Namespace consumers" tabindex="0"><table>
-  <thead><tr><th scope="col">Namespace</th><th scope="col">Consumers</th></tr></thead>
+<div class="ui-table" data-variant="lookup" role="region" aria-label={t('Namespace consumers')} tabindex="0"><table>
+  <thead><tr><th scope="col">{t('Namespace')}</th><th scope="col">{t('Consumers')}</th></tr></thead>
   <tbody>{rows.map(({ namespace, consumers }) => <tr>
     <th scope="row"><code>{namespace}-*</code></th>
     <td><DocumentKeyList keys={consumers} previewCount={6} /></td>

package/src/docs-shell/components/DocumentOptions.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '../../astro/site-context'
+const { t } = siteOf(Astro)
 import RenderNode from '@master/internal-site/components/RenderNode.astro'
 import DocumentOptionEntry from '@master/internal-site/components/DocumentOptionEntry.astro'
 import DocumentOptionList from '@master/internal-site/components/DocumentOptionList.astro'
@@ -16,7 +18,7 @@ const { label, options } = Astro.props
 
 <DocumentOptionList label={label}>
   {options.map(option => <DocumentOptionEntry name={option.name}>
-    {option.defaultValue !== undefined && <small>Default <code>{option.defaultValue}</code></small>}
+    {option.defaultValue !== undefined && <small>{t('Default')} <code>{option.defaultValue}</code></small>}
     <p><RenderNode node={option.description} /></p>
   </DocumentOptionEntry>)}
 </DocumentOptionList>

package/src/docs-shell/components/DocumentationIndex.svelte

@@ -26,7 +26,6 @@
   } = $props()
 
   const { locale, t } = getSite()
-  const tw = locale === 'tw'
   let alphabetical = $state(false)
   const entries = $derived(sections.flatMap(section => section.groups.flatMap(group => group.entries)))
   const letters = $derived(Map.groupBy([...entries].sort((a, b) => a.title.localeCompare(b.title)), entry => /^[a-z]/i.test(entry.title) ? entry.title[0].toUpperCase() : '#'))
@@ -73,7 +72,7 @@
 
 <div class="documentation-index">
   <!-- A contents list, not a second catalog: each section by its number, name and size; the sibling index closes it. -->
-  <nav class="documentation-index-directory" aria-label={tw ? `${name === 'guide' ? 'Guide' : 'Reference'} 分區` : `${name === 'guide' ? 'Guide' : 'Reference'} sections`}>
+  <nav class="documentation-index-directory" aria-label={t('{name} sections').replace('{name}', t(name === 'guide' ? 'Guide' : 'Reference'))}>
     {#each sections as section, index (section.id)}
       <a href={`#${section.id}`} onclick={() => alphabetical = false}>
         <small>{ordinal(index)}</small>
@@ -89,9 +88,9 @@
   </nav>
 
   <div class="documentation-index-toolbar">
-    <p>{tw ? (name === 'guide' ? '所有教學' : '所有條目') : (name === 'guide' ? 'All guides' : 'All entries')} <span class="documentation-index-count">{entries.length}</span></p>
-    <div class="ui-segmented" data-variant="underline" role="group" aria-label={tw ? '索引顯示方式' : 'Index view'}>
-      <button type="button" aria-pressed={!alphabetical} aria-controls={panelId('category')} onclick={() => alphabetical = false}>{tw ? '依分類' : 'By category'}</button>
+    <p>{t(name === 'guide' ? 'All guides' : 'All entries')} <span class="documentation-index-count">{entries.length}</span></p>
+    <div class="ui-segmented" data-variant="underline" role="group" aria-label={t('Index view')}>
+      <button type="button" aria-pressed={!alphabetical} aria-controls={panelId('category')} onclick={() => alphabetical = false}>{t('By category')}</button>
       <button type="button" aria-pressed={alphabetical} aria-controls={panelId('alphabetical')} onclick={() => alphabetical = true}>A–Z</button>
     </div>
   </div>
@@ -104,7 +103,7 @@
           <h2 id={section.id}>{section.title} <span class="documentation-index-count">{count(section)}</span></h2>
           <p>{section.description}</p>
           {#if section.groups.length > 1}
-            <nav class="documentation-index-groups" aria-label={tw ? `${section.title}分類` : `${section.title} categories`}>
+            <nav class="documentation-index-groups" aria-label={t('{name} categories').replace('{name}', section.title)}>
               {#each section.groups as group, index (groupId(section, index))}
                 <a href={`#${groupId(section, index)}`}>{group.title}</a>
               {/each}
@@ -128,7 +127,7 @@
   </div>
 
   <div id={panelId('alphabetical')} hidden={!alphabetical}>
-    <nav class="documentation-index-letters" aria-label={tw ? '依字母跳轉' : 'Jump to a letter'}>
+    <nav class="documentation-index-letters" aria-label={t('Jump to a letter')}>
       {#each [...letters.keys()] as letter (letter)}
         <a href={`#${letterId(letter)}`}>{letter}</a>
       {/each}

package/src/docs-shell/components/GeneratedCSS.astro

@@ -1,9 +1,11 @@
 ---
 import '@master/internal-site/styles/system/disclosure.css'
+import { siteOf } from '../../astro/site-context'
+const { t } = siteOf(Astro)
 /** A closed native disclosure keeps the complete output in the server HTML. */
 ---
 
 <details class="ui-disclosure" data-generated="">
-  <summary>Generated CSS</summary>
+  <summary>{t('Generated CSS')}</summary>
   <slot />
 </details>

package/src/docs-shell/components/Link.svelte

@@ -58,12 +58,13 @@
   const isHash = $derived(props.href?.startsWith('#'))
   const external = $derived(props.href?.startsWith('http'))
   const href: string = $derived.by(() => {
-    if (!props.href?.startsWith('/')) return props.href || ''
+    if (!props.href) return ''
     return localizePathname(props.href, {
       defaultLocale: i18n.defaultLocale,
       locale,
       locales: i18n.locales,
-      localizablePathnameRoots: i18n.localizablePathnameRoots
+      localizablePathnameRoots: i18n.localizablePathnameRoots,
+      localizableOrigins: i18n.localizableOrigins
     }) || ''
   })
   const canonicalHref = $derived(canonicalizeDefaultLocalePathname(href, i18n.defaultLocale))

package/src/docs-shell/components/NotFound.astro

@@ -8,8 +8,7 @@ import SearchButton from './SearchButton.svelte'
 import Link from './Link.svelte'
 import config from 'virtual:master-site/config'
 
-const { t: $, locale } = siteOf(Astro)
-const tw = locale === 'tw'
+const { t: $ } = siteOf(Astro)
 const guide = Boolean(config.sections.guide)
 ---
 
@@ -17,8 +16,8 @@ const guide = Boolean(config.sections.guide)
   <div class="ui-pagehead">
     <span class="ui-pagehead-kicker">404</span>
     <h1>{$('This page does not exist')}</h1>
-    <p>{guide ? (tw ? '試著搜尋文件，或返回 Guide 繼續閱讀。' : 'Try searching the documentation or return to the Guide.') : (tw ? '試著搜尋網站，或返回首頁。' : 'Try searching the site or return to the homepage.')}</p>
+    <p>{guide ? $('Try searching the documentation or return to the Guide.') : $('Try searching the site or return to the homepage.')}</p>
   </div>
   <SearchButton client:load class="ui-search-trigger" />
-  <Link href={guide ? "/guide" : "/"} class="ui-button" data-variant="quiet">{guide ? (tw ? '瀏覽 Guide' : 'Browse the Guide') : (tw ? '返回首頁' : 'Back to home')}<span aria-hidden="true">→</span></Link>
+  <Link href={guide ? "/guide" : "/"} class="ui-button" data-variant="quiet">{guide ? $('Browse the Guide') : $('Back to home')}<span aria-hidden="true">→</span></Link>
 </main>

package/src/docs-shell/components/PageNavs.astro

@@ -13,7 +13,6 @@ interface Props {
 /** The previous and next documents in the section's order, as a `ui-pager`. */
 const { pageCategories, metadata, locale, dictionaries } = Astro.props
 const $ = await createTranslation(locale, dictionaries)
-const tw = locale === 'tw'
 const unit = metadata?.pathname?.split('/')?.[1]
 const pages = (pageCategories?.flatMap((category: any) => category.pages) || [])
   .filter(({ pathname }: any) => pathname.split('/').length <= 3 && unit)
@@ -26,13 +25,13 @@ const navs = [
 ].filter(Boolean).map(({ direction, definedMetadata }: any) => ({
   direction,
   href: definedMetadata.pathname,
-  label: direction === 'prev' ? (tw ? '上一篇' : 'Previous') : (tw ? '下一篇' : 'Next'),
+  label: direction === 'prev' ? $('Previous') : $('Next'),
   title: $(definedMetadata.title.absolute || definedMetadata.title)
 }))
 ---
 
 {navs.length > 0 && (
-  <nav class="ui-pager" aria-label={tw ? '前後篇文件' : 'Previous and next documents'}>
+  <nav class="ui-pager" aria-label={$('Previous and next documents')}>
     {navs.map(({ direction, href, label, title }) => <Link {href} rel={direction} aria-label={`${label}: ${title}`}>
       <small>{label}</small>
       <b>{title}</b>

package/src/docs-shell/components/SearchDialog.svelte

@@ -38,7 +38,6 @@
 
   /** The page's single search dialog; search triggers in other islands open it by event (`contexts/search`). */
   const { t, locale } = getSite()
-  const tw = locale === 'tw'
   let opened = $state(false)
   let query = $state('')
   let shortcutModifier = $state('⌘')
@@ -130,10 +129,8 @@
     }
   }
 
-  const reasons: Record<string, string> | undefined = tw ? { Identifier: '識別字', Title: '名稱', Syntax: '語法與範例', Topic: '主題', Content: '內文' } : undefined
-  const kinds: Record<string, string> = tw
-    ? { utility: 'Utility', rule: '規則', tokens: 'Tokens', directive: '指令', tool: '工具', package: 'API' }
-    : { utility: 'Utility', rule: 'Rule', tokens: 'Tokens', directive: 'Directive', tool: 'Tool', package: 'API' }
+  const kinds: Record<string, string> = { utility: 'Utility', rule: 'Rule', tokens: 'Tokens', directive: 'Directive', tool: 'Tool', package: 'API' }
+
 </script>
 
 <svelte:window onkeydown={shortcut} />
@@ -147,33 +144,33 @@
 {/snippet}
 
 {#if opened}
-  <dialog bind:this={dialog} {@attach portal} {@attach closeOnBackdropClick} class="ui-dialog" data-variant="search" aria-label={tw ? '搜尋文件' : 'Search documentation'} oncancel={close}>
+  <dialog bind:this={dialog} {@attach portal} {@attach closeOnBackdropClick} class="ui-dialog" data-variant="search" aria-label={t('Search documentation')} oncancel={close}>
     <div class="ui-dialog-search">
       <IconSearch size={18} stroke={1.5} aria-hidden="true" />
-      <input bind:this={input} type="search" role="combobox" aria-autocomplete="list" aria-expanded={Boolean(query)} value={query} autocomplete="off" spellcheck={false} placeholder={tw ? '搜尋文件…' : 'Search documentation…'} aria-label={tw ? '搜尋文件' : 'Search documentation'} aria-controls="documentation-search-results" aria-activedescendant={results[selected] ? `documentation-result-${selected}` : undefined}
+      <input bind:this={input} type="search" role="combobox" aria-autocomplete="list" aria-expanded={Boolean(query)} value={query} autocomplete="off" spellcheck={false} placeholder={t('Search documentation…')} aria-label={t('Search documentation')} aria-controls="documentation-search-results" aria-activedescendant={results[selected] ? `documentation-result-${selected}` : undefined}
         oninput={event => selectQuery(event.currentTarget.value)}
         {onkeydown} />
-      {#if query}<button type="button" class="ui-button" data-variant="quiet" data-shape="icon" data-size="sm" onclick={() => selectQuery('')} aria-label={tw ? '清除搜尋' : 'Clear search'}><IconX size={16} stroke={1.5} aria-hidden="true" /></button>{/if}
-      <button type="button" class="ui-button ui-dialog-close" data-variant="quiet" data-size="sm" onclick={close} aria-label={tw ? '關閉搜尋' : 'Close search'}><span class="ui-kbd">esc</span><span>{tw ? '取消' : 'Cancel'}</span></button>
+      {#if query}<button type="button" class="ui-button" data-variant="quiet" data-shape="icon" data-size="sm" onclick={() => selectQuery('')} aria-label={t('Clear search')}><IconX size={16} stroke={1.5} aria-hidden="true" /></button>{/if}
+      <button type="button" class="ui-button ui-dialog-close" data-variant="quiet" data-size="sm" onclick={close} aria-label={t('Close search')}><span class="ui-kbd">esc</span><span>{t('Cancel')}</span></button>
     </div>
     <div class="ui-dialog-body" bind:this={scroll}>
-      <p class="ui-dialog-status" role="status">{loading ? (tw ? '正在載入文件…' : 'Loading documentation…') : error ? (tw ? '搜尋暫時無法載入。' : 'Search could not load.') : query ? `${results.length === 40 ? (tw ? '前 ' : 'Top ') : ''}${results.length} ${tw ? '筆結果' : results.length === 1 ? 'result' : 'results'}` : (tw ? '依名稱、別名或 CSS 屬性查找' : 'Find a name, alias or CSS property')}</p>
-      {#if error}<div class="ui-dialog-note"><p>{tw ? '請檢查連線，再試一次。' : 'Check your connection and try again.'}</p><button type="button" class="ui-button" data-size="sm" onclick={() => { retry += 1; input?.focus() }}>{tw ? '再試一次' : 'Try again'}</button></div>{/if}
+      <p class="ui-dialog-status" role="status">{loading ? (t('Loading documentation…')) : error ? (t('Search could not load.')) : query ? t(results.length === 40 ? 'Top {count} results' : '{count} results').replace('{count}', String(results.length)) : (t('Find a name, alias or CSS property'))}</p>
+      {#if error}<div class="ui-dialog-note"><p>{t('Check your connection and try again.')}</p><button type="button" class="ui-button" data-size="sm" onclick={() => { retry += 1; input?.focus() }}>{t('Try again')}</button></div>{/if}
       {#if !query && !error && !loading}<div class="ui-dialog-note">
-        <p>{tw ? '試試看' : 'Try searching'}</p>
+        <p>{t('Try searching')}</p>
         {#each ['padding', 'padding-inline-start:', 'fg-red:hover@sm'] as value (value)}<button type="button" class="ui-button" data-size="sm" onclick={() => selectQuery(value)}><code>{value}</code><IconCornerDownLeft size={14} stroke={1.5} aria-hidden="true" /></button>{/each}
       </div>{/if}
-      {#if query && !results.length && !error && !loading}<div class="ui-dialog-note" data-align="center"><IconSearch size={24} stroke={1.25} aria-hidden="true" /><b>{tw ? '找不到相符的文件' : 'No matching documents'}</b><p>{tw ? '試試屬性全名、token 名稱或其他關鍵字。' : 'Try a property name, a token name or a different keyword.'}</p></div>{/if}
-      <ol id="documentation-search-results" class="ui-results" role="listbox" aria-label={tw ? '搜尋結果' : 'Search results'} aria-busy={loading}>
+      {#if query && !results.length && !error && !loading}<div class="ui-dialog-note" data-align="center"><IconSearch size={24} stroke={1.25} aria-hidden="true" /><b>{t('No matching documents')}</b><p>{t('Try a property name, a token name or a different keyword.')}</p></div>{/if}
+      <ol id="documentation-search-results" class="ui-results" role="listbox" aria-label={t('Search results')} aria-busy={loading}>
         {#if !error}{#each results as result, index (result.page.url)}<li role="presentation">
           <Link id={`documentation-result-${index}`} role="option" tabindex={-1} aria-selected={selected === index} href={result.href} onclick={close} onpointermove={() => { selected = index }}>
-            <small>{t(result.page.category ?? '')} · {kinds[result.page.kind ?? ''] ?? (result.page.url.includes('/guide') ? 'Guide' : 'Page')} · {reasons?.[result.reason] ?? result.reason}</small>
+            <small>{t(result.page.category ?? '')} · {t(kinds[result.page.kind ?? ''] ?? (result.page.url.includes('/guide') ? 'Guide' : 'Page'))} · {t(result.reason)}</small>
             <b>{result.page.title}</b>
             <span>{@render excerpt(result.excerpt, query)}</span>
           </Link>
         </li>{/each}{/if}
       </ol>
     </div>
-    <div class="ui-dialog-foot" aria-hidden="true"><span><span class="ui-kbd"><IconArrowUp size={12} /></span><span class="ui-kbd"><IconArrowDown size={12} /></span>{tw ? '選擇' : 'Navigate'}</span><span><span class="ui-kbd"><IconCornerDownLeft size={12} /></span>{tw ? '開啟' : 'Open'}</span><span class="ui-search-shortcut">{tw ? '隨時搜尋' : 'Search anytime'}<kbd class="ui-kbd">{shortcutModifier}</kbd><kbd class="ui-kbd">K</kbd></span></div>
+    <div class="ui-dialog-foot" aria-hidden="true"><span><span class="ui-kbd"><IconArrowUp size={12} /></span><span class="ui-kbd"><IconArrowDown size={12} /></span>{t('Navigate')}</span><span><span class="ui-kbd"><IconCornerDownLeft size={12} /></span>{t('Open')}</span><span class="ui-search-shortcut">{t('Search anytime')}<kbd class="ui-kbd">{shortcutModifier}</kbd><kbd class="ui-kbd">K</kbd></span></div>
   </dialog>
 {/if}

package/src/docs-shell/components/TimeAgo.svelte

@@ -3,13 +3,13 @@
   import relativeTime from 'dayjs/plugin/relativeTime'
   import 'dayjs/locale/zh-tw'
   import 'dayjs/locale/en'
+  import 'dayjs/locale/ja'
+  import 'dayjs/locale/ko'
+  import 'dayjs/locale/zh-cn'
+  import { languageOf, formatDate } from '../common/locales'
 
   dayjs.extend(relativeTime)
 
-  const locales: Record<string, string> = {
-    tw: 'zh-tw',
-    en: 'en'
-  }
 </script>
 
 <script lang="ts">
@@ -21,8 +21,8 @@
   const { locale } = getSite()
   let hydrated = $state(false)
   const formattedDate = $derived(hydrated
-    ? dayjs(timestamp).locale(locales[locale]).fromNow()
-    : dayjs(timestamp).format('ddd, MMMM D YYYY'))
+    ? dayjs(timestamp).locale(languageOf(locale).toLowerCase()).fromNow()
+    : formatDate(timestamp, locale, { weekday: 'short' }))
 
   onMount(() => {
     hydrated = true

package/src/docs-shell/contexts/search.ts

@@ -13,6 +13,6 @@ export function searchLabels(translate: (text: string) => string, locale: string
     searchPlaceholder,
     /** The placeholder without its shortcut, which triggers show as a key. */
     searchText: searchPlaceholder.replace(/\s*⌘\s*K\s*…?$/u, ''),
-    searchLabel: locale === 'tw' ? '搜尋文件' : 'Search documentation',
+    searchLabel: translate('Search documentation'),
   }
 }

package/src/docs-shell/factories/Page.astro

@@ -1,7 +1,7 @@
 ---
 import type { AstroComponentFactory } from 'astro/runtime/server/index.js'
 import type { PageParams } from '../types/Props'
-import { resolveContent, type ContentModule } from './create-page'
+import { resolveDocument, resolveNavigation, type ContentModule } from './create-page'
 
 interface Props {
   params: PageParams
@@ -18,18 +18,23 @@ interface Props {
 }
 
 const { params, metadata, dictionaries, categories, content, Layout, noTOC = false, subtitle, ...options } = Astro.props
-const contentModule = content ? await resolveContent(params.locale, metadata, content) : undefined
+const document = await resolveDocument(params.locale, metadata, content)
+const contentModule = document.content
+const pageMetadata = document.metadata
+const pageCategories = resolveNavigation(params.locale, categories)
+const locals = Astro.locals as Record<string, any>
+locals.masterDocument = contentModule?.frontmatter ?? {}
 if (contentModule && !contentModule.default) throw new Error('Invalid content module')
 const Content = contentModule?.default
 const toc = contentModule?.toc
 ---
 
 {Layout
-  ? <Layout {...options} params={params} pageCategories={categories} dictionaries={dictionaries} metadata={metadata} toc={noTOC ? null : toc} subtitle={subtitle}>
-      {Content && <Content pageCategories={categories} />}
+  ? <Layout {...options} params={params} {pageCategories} dictionaries={dictionaries} metadata={pageMetadata} toc={noTOC ? null : toc} subtitle={subtitle}>
+      {Content && <Content {pageCategories} />}
       <slot />
     </Layout>
   : <Fragment>
-      {Content && <Content pageCategories={categories} />}
+      {Content && <Content {pageCategories} />}
       <slot />
     </Fragment>}

package/src/docs-shell/factories/create-page.ts

@@ -1,10 +1,14 @@
 import type { AstroComponentFactory } from 'astro/runtime/server/index.js'
 import type { Props } from '../types/Props'
 import generate from '../utils/generate-metadata'
+import config from 'virtual:master-site/config'
+import metadataByPathname from 'virtual:master-site/localized-metadata'
+import { localizedMetadata } from '../utils/localized-metadata'
 
 export interface ContentModule {
   default: AstroComponentFactory
   toc?: any
+  frontmatter?: Record<string, any>
 }
 
 /** Translated MDX lives beside its source as `content.<locale>.mdx`. */
@@ -20,12 +24,35 @@ export function createPageMetadata(metadata: any, dictionaries: Record<string, (
  * Astro collects a page's stylesheets from its module graph when the page module loads, before a pending dynamic import finishes in dev.
  */
 export async function resolveContent(locale: string, metadata: any, content: ContentModule) {
-  const directory = contentDirectoryOf(metadata)
-  return (directory ? await translatedContent[`/content/${directory}/content.${locale}.mdx`]?.() : undefined) ?? content
+  const propagated = await loadLocalizedContent(locale, metadata)
+  if (propagated) return await propagated.getMod()
+  if (locale !== config.i18n.defaultLocale) throw new Error(`Missing localized content: ${metadata.pathname ?? metadata.sourcePath} (${locale})`)
+  return content
 }
 
-function contentDirectoryOf(metadata: any) {
-  const sourcePath = metadata?.sourcePath
-  if (typeof sourcePath !== 'string') return
-  return sourcePath.match(/^site\/content\/(.+)\/content\.mdx$/)?.[1]
+/** The configured inventory owns content roots; metadata carries a canonical pathname. */
+export async function loadLocalizedContent(locale: string, metadata: any) {
+  const documents = translatedContent[metadata.pathname]
+  if (!documents) return
+  const load = documents[locale]
+  if (!load) throw new Error(`Missing localized content: ${metadata.pathname} (${locale})`)
+  return await load()
+}
+
+export function resolveMetadata(locale: string, metadata: any) {
+  const variants = metadataByPathname[metadata.pathname]
+  if (!variants) return { ...metadata, locale }
+  const frontmatter = variants[locale]
+  if (!frontmatter && locale !== config.i18n.defaultLocale) throw new Error(`Missing localized metadata: ${metadata.pathname} (${locale})`)
+  return localizedMetadata(metadata, frontmatter ?? {}, locale)
+}
+
+export async function resolveDocument(locale: string, metadata: any, content?: ContentModule) {
+  const module = content ? await resolveContent(locale, metadata, content) : await (await loadLocalizedContent(locale, metadata))?.getMod()
+  return { content: module, metadata: resolveMetadata(locale, metadata) }
+}
+
+/** Localized navigation reads lightweight frontmatter, without importing every MDX page. */
+export function resolveNavigation(locale: string, categories: any[] = []) {
+  return categories.map(category => ({ ...category, pages: category.pages.filter((page: any) => !metadataByPathname[page.pathname] || metadataByPathname[page.pathname][locale]).map((page: any) => resolveMetadata(locale, page)) }))
 }

package/src/docs-shell/layouts/BlogArticle.astro

@@ -2,7 +2,6 @@
 import '@master/internal-site/styles/docs-shell/prose.css'
 import '@master/internal-site/styles/blog-materials.css'
 import '@master/internal-site/styles/blog-article.css'
-import translations from 'virtual:master-site/translations'
 import Footer from '@master/internal-site/components/Footer.svelte'
 import PageContentBootstrap from '@master/internal-site/components/PageContentBootstrap.astro'
 import { siteOf } from '@master/internal-site/astro/site-context'
@@ -10,10 +9,6 @@ import BlogArticleMasthead from '@master/internal-site/blog/article/BlogArticleM
 import BlogArticleContents from '@master/internal-site/blog/article/BlogArticleContents.svelte'
 import BlogArticleEnd from '@master/internal-site/blog/article/BlogArticleEnd.astro'
 import { neighborsOf } from '@master/internal-site/blog/article/neighbors'
-import { contentLanguageOf } from '@master/internal-site/blog/article/language'
-
-/** Translated MDX lives beside its source as `content.<locale>.mdx` (see docs-shell/factories/create-page). */
-const translatedContent = new Set(Object.keys(translations))
 
 /**
  * A blog post, drawn with the homepage's drafting guides: the header, the reading column (the documentation's measure
@@ -22,11 +17,8 @@ const translatedContent = new Set(Object.keys(translations))
  * left margin.
  */
 const { metadata, toc, pageCategories: posts = [], footerProps = {} } = Astro.props
-const { t: $, i18n, locale } = siteOf(Astro)
-const { defaultLocale, hreflangOfLocale } = i18n
+const { t: $ } = siteOf(Astro)
 const { newer, older } = neighborsOf(metadata.sourcePath, posts)
-// A post not yet translated is shown in its own language; the body says so, for screen readers and Han type rules.
-const proseLanguage = contentLanguageOf(metadata.sourcePath, translatedContent, { locale, defaultLocale, hreflangOfLocale })
 const contents = (toc ?? []).filter((item: any) => item.level === 2 || item.level === 3).map(({ id, title, level }: any) => ({ id, title, level }))
 const hasSections = contents.some((item: any) => item.level === 2)
 // As on the blog index, a category every post shares says nothing about the next one.
@@ -39,9 +31,9 @@ const showCategory = posts.length > 1
       {/* The post's own header, so the title, date and authors belong to the article. */}
       <BlogArticleMasthead metadata={metadata} />
       {/* In the page's outer left margin, beside the text it lists. */}
-      {hasSections ? <BlogArticleContents client:idle={{ timeout: 500 }} items={contents} label={$('On this page')} lang={proseLanguage} /> : null}
+      {hasSections ? <BlogArticleContents client:idle={{ timeout: 500 }} items={contents} label={$('On this page')} /> : null}
       <div class="blog-article-body blog-rails blog-rails-rule">
-        <div class="blog-article-prose ui-prose" lang={proseLanguage}>
+        <div class="blog-article-prose ui-prose">
           <slot />
         </div>
       </div>

package/src/docs-shell/remark/slug-and-toc.js

@@ -1,16 +1,15 @@
-import Slugger from 'github-slugger'
 import { visit } from 'unist-util-visit'
-import resolveHeading from '../utils/resolve-heading.js'
+import { createHeadingResolver } from '../utils/resolve-heading.js'
 import { parse } from 'acorn'
 
 export default function remarkSlugAndTOC() {
   return (tree) => {
-    const slugs = new Slugger()
+    const resolveHeading = createHeadingResolver()
     const toc = []
 
     visit(tree, 'heading', (node) => {
       const depth = node.depth
-      if (depth !== 2 && depth !== 3) return
+      if (depth < 2 || depth > 6) return
 
       // Extract raw text from heading children
       const title = node.children
@@ -19,8 +18,7 @@ export default function remarkSlugAndTOC() {
         .join(' ')
         .trim()
 
-      const id = slugs.slug(title)
-      const resolved = resolveHeading(title, id)
+      const resolved = resolveHeading(title, depth)
       // Explicit IDs survive title edits and translations; they are not visible prose.
       const lastText = node.children.findLast((child) => child.type === 'text')
       if (lastText) lastText.value = lastText.value.replace(/\s+\{#[\w-]+\}$/, '')
@@ -29,7 +27,7 @@ export default function remarkSlugAndTOC() {
       node.data.id = resolved.id
       node.data.hProperties.id = resolved.id
 
-      toc.push({
+      if (depth === 2 || depth === 3) toc.push({
         id: resolved.id,
         title: resolved.title,
         level: depth

package/src/docs-shell/scripts/code.ts

@@ -1,4 +1,7 @@
 /** Code blocks render as static markup; these delegated handlers switch tabs and copy code. */
+import { readSiteContext } from '../site'
+
+const t = (text: string) => readSiteContext().translations[text] ?? text
 
 const tabChange = 'site-code-tabs:change'
 const resetTimers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>()
@@ -24,7 +27,7 @@ function selectTab(root: HTMLElement, name: string) {
   const copy = root.querySelector<HTMLButtonElement>('[data-code-copy]')
   if (copy) {
     copy.dataset.codeCopy = name
-    copy.ariaLabel = copy.title = `Copy ${name}`
+    copy.ariaLabel = copy.title = t('Copy {name}').replace('{name}', t(name))
   }
 }
 
@@ -55,7 +58,7 @@ function showCopyStatus(button: HTMLButtonElement, status: 'idle' | 'pending' |
   const element = button.closest('.ui-copy')?.querySelector<HTMLElement>('.ui-copy-status')
   const result = status === 'copied' ? 'success' : status === 'error' ? 'error' : undefined
   if (element) {
-    element.textContent = status === 'copied' ? `${name || 'Code'} copied` : status === 'error' ? 'Clipboard unavailable. Select the code to copy it.' : ''
+    element.textContent = status === 'copied' ? t('{name} copied').replace('{name}', t(name || 'Code')) : status === 'error' ? t('Clipboard unavailable. Select the code to copy it.') : ''
     if (result) element.dataset.result = result
     else delete element.dataset.result
   }

package/src/docs-shell/site.ts

@@ -15,6 +15,7 @@ export interface SiteI18n {
   defaultLocale: string
   locales: readonly string[]
   localizablePathnameRoots: string[]
+  localizableOrigins?: Record<string, readonly string[]>
   hreflangOfLocale: Record<string, string>
   nameOfLocale: Record<string, string>
 }
@@ -47,6 +48,7 @@ export function createSite(value: SiteContextValue): Site {
 }
 
 let clientSite: Site | undefined
+let clientContext: string | undefined
 
 /** Read the context Document.astro serializes for client islands. */
 export function readSiteContext(): SiteContextValue {
@@ -63,5 +65,11 @@ export function getSite(): Site {
   const value = getContext<SiteContextValue | undefined>(siteContextKey)
   if (value) return createSite(value)
   if (typeof document === 'undefined') throw new Error('getSite() must run inside a component rendered by the site')
-  return clientSite ??= createSite(readSiteContext())
+  const serialized = document.getElementById(siteContextElementId)?.textContent
+  if (!serialized) throw new Error(`Missing #${siteContextElementId}`)
+  if (serialized !== clientContext) {
+    clientContext = serialized
+    clientSite = createSite(JSON.parse(serialized))
+  }
+  return clientSite!
 }

package/src/docs-shell/utils/document-copy.d.ts

@@ -0,0 +1,2 @@
+/** Overlay prose fields only; executable source and technical identity stay shared. */
+export declare function demoCopy<T>(frontmatter: Record<string, any>, locale: string, key: string, original: T): T

package/src/docs-shell/utils/document-copy.js

@@ -0,0 +1,18 @@
+const proseFields = new Set(['title', 'description', 'caption', 'summary', 'label', 'note', 'lead', 'sourceLabel', 'resultLabel', 'alt'])
+
+/** Overlay article-owned prose without copying or changing executable examples. */
+export function demoCopy(frontmatter, locale, key, original) {
+  if (locale === 'en') return original
+  const copy = frontmatter.demos?.[key]
+  const walk = (value, translated, field, location) => {
+    if (typeof value === 'string') {
+      if (!proseFields.has(field) || !value.trim()) return value
+      if (typeof translated !== 'string' || !translated.trim()) throw new Error(`Missing localized demo copy: ${key}.${location} (${locale})`)
+      return translated
+    }
+    if (Array.isArray(value)) return value.map((item, index) => walk(item, translated?.[index], field, `${location}[${index}]`))
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, walk(item, translated?.[name], name, location ? `${location}.${name}` : name)]))
+    return value
+  }
+  return walk(original, copy, '', '')
+}

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

@@ -2,6 +2,7 @@ import { defu } from 'defu'
 import type { Metadata } from '../types/Metadata'
 import type { Props } from '../types/Props'
 import { createTranslation } from './i18n'
+import { resolveMetadata } from '../factories/create-page'
 
 export default async function generate(
   metadata: Metadata | Record<string, any>,
@@ -9,6 +10,7 @@ export default async function generate(
   dictionaries: Record<string, () => Promise<any>>
 ): Promise<Metadata> {
   const { locale } = params
+  metadata = resolveMetadata(locale, metadata)
   const $ = await createTranslation(locale, dictionaries)
   const description = $(metadata.description)
   const category = $(metadata.category)

package/src/docs-shell/utils/i18n-pathname.ts

@@ -6,6 +6,7 @@ export interface LocalizePathnameOptions {
   locales: readonly string[]
   localePrefixMode?: LocalePrefixMode
   localizablePathnameRoots?: readonly string[]
+  localizableOrigins?: Record<string, readonly string[]>
 }
 
 const nonPagePathnameRoots = new Set([
@@ -24,8 +25,18 @@ export function localizePathname(href: string, {
   locale,
   locales,
   localePrefixMode = 'canonical',
-  localizablePathnameRoots
-}: LocalizePathnameOptions) {
+  localizablePathnameRoots,
+  localizableOrigins
+}: LocalizePathnameOptions): string {
+  if (/^https?:\/\//i.test(href)) {
+    let url: URL
+    try { url = new URL(href) } catch { return href }
+    const roots = localizableOrigins?.[url.origin]
+    if (!roots) return href
+    return url.origin + localizePathname(url.pathname + url.search + url.hash, {
+      defaultLocale, locale, locales, localePrefixMode, localizablePathnameRoots: roots
+    })
+  }
   if (!href || !href.startsWith('/') || href.startsWith('//')) return href
 
   const parsedHref = parseLocalHref(href)

package/src/docs-shell/utils/i18n.ts

@@ -1,3 +1,5 @@
+import sharedTranslations from '../common/translations'
+
 export async function createTranslation(locale: string, dictionaries: Record<string, () => Promise<any>>): Promise<(text: any) => string> {
   const translations = await importTranslations(locale, dictionaries)
   return (text: any) => (translations)[text || ''] || text
@@ -8,5 +10,6 @@ export const importTranslations = async (locale: string, dictionaries: Record<st
     throw new Error('locale is required')
   }
   const load = dictionaries[locale as keyof typeof dictionaries]
-  return await load()
+  if (!load && !sharedTranslations[locale]) throw new Error(`Unsupported locale: ${locale}`)
+  return { ...sharedTranslations[locale], ...(load ? await load() : {}) }
 }