@master/internal-site 0.1.3 → 0.2.0

package/src/css/markdown.ts

@@ -6,6 +6,10 @@ 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 { parseFrontmatter } from '@astrojs/markdown-remark'
+import { headingAnchors } from '../scripts/localization'
+import { isSharedMdxSample } from '../scripts/mdx-sample'
+import { translateShell } from '../docs-shell/common/translations'
 import { generatePresetCSS } from '@master/internal-site/css/generate-preset-css.ts'
 import { selectedSpecimensMarkdown } from '@master/internal-site/css/foundation-data/specimen-content.ts'
 import { getVariableNamespacePublicKeys } from '@master/internal-site/css/manifest-utilities.ts'
@@ -33,7 +37,7 @@ export function syntaxMarkdown(rows: SyntaxRow[]) {
 }
 
 export function portableMarkdown(markdown: string) {
-  return markdown.split(/(```[\s\S]*?```)/g).map(part => part.startsWith('```') ? part : part.replace(/<!-- \/?reference-illustration(?::[\w-]+)? -->\n*/g, '').replace(/^(#{2,3}) (.+) \{#([\w-]+)\}$/gm, '<a id="$3"></a>\n\n$1 $2')).join('')
+  return markdown.split(/(```[\s\S]*?```)/g).map(part => part.startsWith('```') ? part : part.replace(/<!-- \/?reference-illustration(?::[\w-]+)? -->\n*/g, '').replace(/^(#{2,6}) (.+) \{#([\w-]+)\}$/gm, '<a id="$3"></a>\n\n$1 $2')).join('')
 }
 
 /** Resolve authored literals only. Never execute MDX expressions to extract documents. */
@@ -50,9 +54,11 @@ function literal(node: any, variables: Record<string, unknown>): unknown {
 }
 
 export interface MdxContentOptions {
+  /** Propagates through nested MDX includes and custom text adapters. */
+  locale?: string
   /** Reference Overview renders syntax rows; Guide Overview may be a local MDX include. */
   overview?: 'syntax' | 'include'
-  component?: (name: string, attributes: Record<string, any>, file: string, context: { expression: (source: string) => Promise<unknown> }) => string | undefined | Promise<string | undefined>
+  component?: (name: string, attributes: Record<string, any>, file: string, context: { expression: (source: string) => Promise<unknown>; locale: string }) => string | undefined | Promise<string | undefined>
 }
 
 /**
@@ -64,7 +70,18 @@ const expressionElement = /(<(Code|Class2CSS|DocumentDeclaration)\b(?:"[^"]*"|'[
 export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [], stack: string[] = [], options: MdxContentOptions = {}) {
   if (stack.includes(file)) throw new Error(`Recursive document include: ${file}`)
   const expressions: Record<string, string> = {}
-  const source = (await readFile(file, 'utf8')).split(/(```[\s\S]*?```)/g).map(part => part.startsWith('```') ? part : part.replace(/\{?<Demo\b[\s\S]*?<\/Demo>\}?/g, '').replace(expressionElement, (_, start, _name, expression, end) => { const key = `MCSS_EXPRESSION_${Object.keys(expressions).length}`; expressions[key] = expression; return `${start}\n${key}\n${end}` })).join('')
+  const locale = options.locale ?? file.match(/\.(tw|ja|ko|cn)\.mdx$/)?.[1] ?? 'en'
+  const t = (text: string) => translateShell(locale, text)
+  options = { ...options, locale }
+  const original = file.replace(/\.(tw|ja|ko|cn)\.mdx$/, '.mdx')
+  const canonical = parseFrontmatter(await readFile(original, 'utf8'))
+  if (canonical.frontmatter.draft === true || canonical.frontmatter.disabled === true) throw new Error(`Unpublished source MDX document: ${original}`)
+  const document = original === file ? canonical : parseFrontmatter(await readFile(file, 'utf8'))
+  if (document.frontmatter.draft === true || document.frontmatter.disabled === true) throw new Error(`Unpublished translated MDX document: ${file}`)
+  const source = document.content.split(/(```[\s\S]*?```)/g).map(part => part.startsWith('```') ? part : part.replace(/\{?<Demo\b[\s\S]*?<\/Demo>\}?/g, '').replace(expressionElement, (_, start, _name, expression, end) => { const key = `MCSS_EXPRESSION_${Object.keys(expressions).length}`; expressions[key] = expression; return `${start}\n${key}\n${end}` })).join('')
+  let sourceAnchors: string[]
+  try { sourceAnchors = headingAnchors(source) } catch (error) { throw new Error(`Cannot read headings in ${file}`, { cause: error }) }
+  const headingIds = new Map<any, string>()
   const examples: ReferenceExample[] = []
   const notes: string[] = []
   const variables: Record<string, unknown> = {}
@@ -75,6 +92,12 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
     extensions: [{ disable: { null: ['htmlFlow', 'htmlText', 'codeIndented'] } }, mdxjsEsm({ acorn, addResult: true }), mdxJsx({ acorn, addResult: true })],
     mdastExtensions: [mdxjsEsmFromMarkdown(), mdxJsxFromMarkdown()]
   }) } catch (error) { throw new Error(`Cannot parse ${file}`, { cause: error }) }
+  let headingIndex = 0
+  const collectHeadingIds = (node: any) => {
+    if (node.type === 'heading' && node.depth >= 2 && node.depth <= 6) headingIds.set(node, sourceAnchors[headingIndex++])
+    node.children?.forEach(collectHeadingIds)
+  }
+  collectHeadingIds(tree)
   const raw = (node: any) => source.slice(node.position.start.offset, node.position.end.offset)
   const collectEsm = (node: any) => {
     if (node.type === 'mdxjsEsm') {
@@ -135,7 +158,7 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
       const name = node.name ?? ''
       const attrs: Record<string, any> = Object.fromEntries((node.attributes ?? []).filter((a: any) => a.name).map((a: any) => [a.name, a.value]))
       const inner = (node.children ?? []).map(raw).join('\n')
-      const adapted = await options.component?.(name, attrs, file, { expression })
+      const adapted = await options.component?.(name, attrs, file, { expression, locale })
       if (adapted !== undefined) return adapted
       const attribute = (value: any) => value?.type === 'mdxJsxAttributeValueExpression' ? expression(value.value) : value
       if (name === 'DocumentPrompt') {
@@ -148,11 +171,11 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
         const result = await attribute(attrs.result)
         const diagnostic = await attribute(attrs.diagnostic)
         if (typeof source !== 'string' || typeof attrs.language !== 'string') throw new Error('DocumentCodeExample requires literal source and language')
-        const sourceLabel = attrs.sourceLabel ?? (result !== undefined && attrs.resultKind !== 'generated-css' ? 'Source' : undefined)
+        const sourceLabel = attrs.sourceLabel ?? (result !== undefined && attrs.resultKind !== 'generated-css' ? t('Source') : undefined)
         const parts = [`**${attrs.title}**`, ...(sourceLabel ? [`**${sourceLabel}**`] : []), `\`\`\`${attrs.language}\n${source}\n\`\`\``]
         if (result !== undefined) {
           if (typeof result !== 'string') throw new Error('DocumentCodeExample requires a literal result')
-          parts.push(`**${attrs.resultLabel ?? (attrs.resultKind === 'generated-css' ? 'Generated CSS' : 'Result')}**`, `\`\`\`${attrs.resultLanguage ?? attrs.language}\n${result}\n\`\`\``)
+          parts.push(`**${attrs.resultLabel ?? t(attrs.resultKind === 'generated-css' ? 'Generated CSS' : 'Result')}**`, `\`\`\`${attrs.resultLanguage ?? attrs.language}\n${result}\n\`\`\``)
         }
         if (diagnostic) parts.push(`${diagnostic.severity} (\`${diagnostic.rule}\`): ${diagnostic.message}`)
         return parts.join('\n\n')
@@ -160,7 +183,7 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
       if (['DocumentOptions', 'DocumentParameters'].includes(name)) {
         const values = await expression(attrs[name === 'DocumentOptions' ? 'options' : 'parameters'].value) as { name: string, type?: string, requirement?: string, defaultValue?: string, description: string }[]
         if (!Array.isArray(values) || values.some(value => typeof value.name !== 'string' || typeof value.description !== 'string')) throw new Error(`${name} requires literal names and descriptions`)
-        return values.map(value => `**\`${value.name}\`**${value.type ? ` — \`${value.type}\`` : ''}${value.requirement ? ` (${value.requirement})` : ''}\n\n${value.defaultValue !== undefined ? `Default: \`${value.defaultValue}\`. ` : ''}${value.description}`).join('\n\n')
+        return values.map(value => `**\`${value.name}\`**${value.type ? ` — \`${value.type}\`` : ''}${value.requirement ? ` (${value.requirement})` : ''}\n\n${value.defaultValue !== undefined ? `${t('Default')}: \`${value.defaultValue}\`. ` : ''}${value.description}`).join('\n\n')
       }
       if (name === 'DocumentAPIIndex') {
         const values = await expression(attrs.entries.value) as { name: string, href: string, description: string }[]
@@ -178,7 +201,7 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
         const rows = await expression(attrs.rows.value) as { syntax: string, css: string }[]
         if (!Array.isArray(rows) || rows.some(row => typeof row.syntax !== 'string' || typeof row.css !== 'string')) throw new Error('DocumentCodeTable requires literal syntax and CSS rows')
         const code = (value: string) => `\`${value.replaceAll('|', '\\|')}\``
-        return `| ${attrs.label ?? 'Syntax'} | CSS |\n| --- | --- |\n${rows.map(row => `| ${code(row.syntax)} | ${code(row.css)} |`).join('\n')}`
+        return `| ${attrs.label ?? t('Syntax')} | CSS |\n| --- | --- |\n${rows.map(row => `| ${code(row.syntax)} | ${code(row.css)} |`).join('\n')}`
       }
       if (name === 'DocumentFlow') {
         const steps = await expression(attrs.steps.value) as { title: string, description: string }[]
@@ -196,7 +219,7 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
         if (typeof attrs.title !== 'string' || typeof source !== 'string') throw new Error('StylesheetExample requires a literal title and source')
         return stylesheetExampleMarkdown(attrs.title, source)
       }
-      if (name === 'FoundationTokens') return selectedSpecimensMarkdown(attrs.namespace, await expression(attrs.keys.value) as string[])
+      if (name === 'FoundationTokens') return selectedSpecimensMarkdown(attrs.namespace, await expression(attrs.keys.value) as string[], t)
       if (name === 'DemoPageViewport') return `[Open the resizable ${attrs.title} example](${attrs.src}). The viewport slider also supports arrow keys.`
       if (name === 'DemoConfiguredExample') {
         const configuration = typeof attrs.source === 'string' ? attrs.source : await expression(attrs.source.value) as string
@@ -255,9 +278,20 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
       if (/^[A-Z]/.test(name)) {
         const imported = imports[name]
         const siteRoot = file.slice(0, file.lastIndexOf('/content/'))
-        const target = imported?.startsWith('~/site/') ? path.join(siteRoot, imported.slice(7))
+        let target = imported?.startsWith('~/site/') ? path.join(siteRoot, imported.slice(7))
           : imported?.startsWith('.') ? path.resolve(path.dirname(file), imported)
             : path.join(path.dirname(file), 'components', `${name}.mdx`)
+        target = target.replace(/\.(tw|ja|ko|cn)\.mdx$/, '.mdx')
+        if (target.endsWith('.mdx') && locale !== 'en') {
+          const original = await readFile(target, 'utf8').catch(() => '')
+          const metadata = parseFrontmatter(original).frontmatter
+          if (metadata.draft === true || metadata.disabled === true) throw new Error(`Unpublished source MDX document: ${target}`)
+          if (original.trim() && !isSharedMdxSample(target, original)) {
+            const translated = target.replace(/\.mdx$/, `.${locale}.mdx`)
+            if (await access(translated).then(() => true, () => false)) target = translated
+            else throw new Error(`Missing translated MDX include: ${translated}`)
+          }
+        }
         if (target.endsWith('.mdx') && await access(target).then(() => true, () => false)) {
           const result = await extractReferenceMdx(target, rows, [...stack, file], options)
           examples.push(...result.examples)
@@ -277,7 +311,14 @@ export async function extractReferenceMdx(file: string, rows: SyntaxRow[] = [],
       const end = child.position.end.offset - node.position.start.offset
       text = text.slice(0, start) + await render(child) + text.slice(end)
     }
-    return node.type === 'heading' ? text.replace(/\\([{}])/g, '$1') : text
+    if (node.type === 'heading') {
+      text = text.replace(/\\([{}])/g, '$1')
+      if (node.depth >= 2 && node.depth <= 6) {
+        const id = headingIds.get(node)
+        if (!/\s+\{#[\w-]+\}\s*$/.test(text)) text = text.replace(/\s+#+\s*$/, '') + ` {#${id}}`
+      }
+    }
+    return text
   }
   const parts: string[] = []
   for (const child of tree.children) parts.push(await render(child))

package/src/demo/Demo.svelte

@@ -36,6 +36,7 @@
 
   import '@master/internal-site/styles/demo.css'
   import { styleText } from './style'
+  import { getSite } from '@master/internal-site/site'
 
   /** One example is one tray: head, stage, source, caption. class and style belong to the stage; the chrome never joins the demonstrated layout. */
   let {
@@ -43,17 +44,18 @@
     frameClassName, class: className, style, children, ...props
   }: DemoProps = $props()
   const head = $derived(Boolean(title || description || controls))
+  const { t } = getSite()
 </script>
 
-{#snippet node(value: DemoNode)}{#if typeof value === 'function'}{@render value()}{:else}{value}{/if}{/snippet}
+{#snippet node(value: DemoNode, translate = false)}{#if typeof value === 'function'}{@render value()}{:else}{translate ? t(value) : value}{/if}{/snippet}
 
 <figure {...props} class={['ui-tray', frameClassName]}>{#if head}<figcaption class="ui-tray-head">
     {#if title || description}<div>
-      {#if title}<p class="ui-tray-title">{title}</p>{/if}
-      {#if description}<p class="ui-tray-description">{@render node(description)}</p>{/if}
+      {#if title}<p class="ui-tray-title">{t(title)}</p>{/if}
+      {#if description}<p class="ui-tray-description">{@render node(description, true)}</p>{/if}
     </div>{/if}
     {#if controls}<div class="ui-tray-tools">{@render node(controls)}</div>{/if}
   </figcaption>{/if}{#if frame === 'none'}{@render children?.()}{:else}<div class={['ui-stage', className]} style={styleText(style)}
     data-background={background === 'plain' ? undefined : background}
     data-padding={padding === 'lg' ? undefined : padding}
-    data-align={align === 'center' ? undefined : align}>{@render children?.()}</div>{/if}{#if source}{@render node(source)}{/if}{#if caption}{#if head}<div class="ui-tray-caption">{@render node(caption)}</div>{:else}<figcaption class="ui-tray-caption">{@render node(caption)}</figcaption>{/if}{/if}</figure>
+    data-align={align === 'center' ? undefined : align}>{@render children?.()}</div>{/if}{#if source}{@render node(source)}{/if}{#if caption}{#if head}<div class="ui-tray-caption">{@render node(caption, true)}</div>{:else}<figcaption class="ui-tray-caption">{@render node(caption, true)}</figcaption>{/if}{/if}</figure>

package/src/demo/DemoAsset.astro

@@ -4,6 +4,7 @@ import '@master/internal-site/styles/system/specimens.css'
 import IconDownload from '@tabler/icons-svelte-runes/icons/download'
 import Demo from './Demo.svelte'
 import Image from '@master/internal-site/components/Image.svelte'
+import { siteOf } from '../astro/site-context'
 
 export interface DemoAssetProps {
   title: string
@@ -23,17 +24,18 @@ type Props = DemoAssetProps
  * transparent artwork sits on a checkerboard. A demo container keeps the prose media perimeter off the artwork.
  */
 const { title, description, src, alt, width, height, format = 'SVG', surface = 'transparent' } = Astro.props
+const { t } = siteOf(Astro)
 ---
 
 <Demo title={title} description={description} background={surface === 'transparent' ? 'checkerboard' : 'plain'} class={surface === 'transparent' ? undefined : surface} data-asset={surface}>
   <Fragment slot="caption">
     <span class="flex flex-wrap items-center justify-between gap-sm">
       <span class="ui-badge" data-size="sm">{format}</span>
-      <a href={src} download class="ui-button" data-size="sm" aria-label={`Download ${title} (${format})`}>
+      <a href={src} download class="ui-button" data-size="sm" aria-label={t('Download {title} ({format})').replace('{title}', t(title)).replace('{format}', format)}>
         <IconDownload aria-hidden="true" />
-        Download {format}
+        {t('Download {format}').replace('{format}', format)}
       </a>
     </span>
   </Fragment>
-  <div class="grid (place-items:center) w-full" data-demo-container=""><Image src={src} alt={alt} width={width} height={height} class="block h-auto w-auto max-w-full (max-height:var(--spacing-4xl))" /></div>
+  <div class="grid (place-items:center) w-full" data-demo-container=""><Image src={src} alt={t(alt)} width={width} height={height} class="block h-auto w-auto max-w-full (max-height:var(--spacing-4xl))" /></div>
 </Demo>

package/src/demo/DemoAxes.svelte

@@ -1,11 +1,13 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/system/specimens.css'
   import type { Snippet } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'
   import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
 
   /** `inline` and `block` take text, or a snippet (a named slot from `.astro` and `.mdx`). */
-  let { inline = 'Main axis', block = 'Cross axis', children, class: className, style, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
+  let { inline = t('Main axis'), block = t('Cross axis'), children, class: className, style, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
     inline?: string | Snippet
     block?: string | Snippet
     style?: DemoStyle
@@ -13,7 +15,7 @@
   } = $props()
 </script>
 
-{#snippet node(value: string | Snippet)}{#if typeof value === 'function'}{@render value()}{:else}{value}{/if}{/snippet}
+{#snippet node(value: string | Snippet)}{#if typeof value === 'function'}{@render value()}{:else}{t(value)}{/if}{/snippet}
 
 <div {...props} class={['ui-axes', className]} style={styleText(style)}>
   <div class="ui-axes-inline"><span>{@render node(inline)}</span><span class="ui-axes-rule" aria-hidden="true"></span></div>

package/src/demo/DemoCatalog.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
 import '@master/internal-site/styles/system/disclosure.css'
 import '@master/internal-site/styles/demo.css'
 import RenderNode from '@master/internal-site/components/RenderNode.astro'
@@ -20,16 +22,16 @@ const { groups } = Astro.props
 ---
 
 <div class="ui-catalog">
-  <DemoIndex label="Utility recipe categories" groups={[{
-    title: 'Choose a behavior',
-    links: groups.map(group => ({ href: `#${group.id}`, label: `${group.title} · ${group.entries.length}` }))
+  <DemoIndex label={t('Utility recipe categories')} groups={[{
+    title: t('Choose a behavior'),
+    links: groups.map(group => ({ href: `#${group.id}`, label: `${t(group.title)} · ${group.entries.length}` }))
   }]} />
   {groups.map(group => <section aria-labelledby={group.id}>
-    <h3 id={group.id}>{group.title}<small>{group.entries.length} recipes</small></h3>
+    <h3 id={group.id}>{t(group.title)}<small>{t('{count} recipes').replace('{count}', String(group.entries.length))}</small></h3>
     {group.entries.map(entry => <details class="ui-disclosure" data-variant="rule">
-      <summary>{entry.title}<span class="ui-disclosure-meta">{entry.label}</span></summary>
+      <summary>{t(entry.title)}<span class="ui-disclosure-meta">{t(entry.label)}</span></summary>
       <div class="ui-catalog-entry">
-        {entry.href && <a href={entry.href}>Read related documentation ↗</a>}
+        {entry.href && <a href={entry.href}>{t('Read related documentation')} ↗</a>}
         <RenderNode node={entry.children} />
       </div>
     </details>)}

package/src/demo/DemoContainer.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/interface.css'
   import '@master/internal-site/styles/system/range.css'
 
@@ -38,12 +40,12 @@
 </script>
 
 {#snippet controls()}
-  <label class="ui-label" data-case="as-is" for={id}>Container</label>
+  <label class="ui-label" data-case="as-is" for={id}>{t('Container')}</label>
   <input {id} class="ui-range" type="range" min={minimumWidth} max={maxWidth} step="1" disabled={!ready} {value}
     style:--value={`${((value - minimumWidth) / range) * 100}%`} style:width="128px" style:max-width="100%"
     oninput={event => { width = Number(event.currentTarget.value) }} />
-  <button type="button" class="ui-button" data-size="sm" disabled={!ready} onclick={() => { width = undefined }}>Fit</button>
-  <output class="ui-label" data-case="as-is">{ready ? `${measured} px · viewport unchanged` : 'Measuring container…'}</output>
+  <button type="button" class="ui-button" data-size="sm" disabled={!ready} onclick={() => { width = undefined }}>{t('Fit')}</button>
+  <output class="ui-label" data-case="as-is">{ready ? t('{width} px · viewport unchanged').replace('{width}', String(measured)) : t('Measuring container…')}</output>
 {/snippet}
 
 <Demo {...props} {title} {caption} padding="sm" data-ready={ready} {controls}>

package/src/demo/DemoControls.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/system/segmented.css'
 
   import '@master/internal-site/styles/system/specimens.css'
@@ -15,4 +17,4 @@
   } = $props()
 </script>
 
-<div {...props} role="group" aria-label={label} class={[variant === 'segmented' ? 'ui-segmented' : 'flex flex-wrap items-center gap-xs', className]} style={styleText(style)}>{@render children?.()}</div>
+<div {...props} role="group" aria-label={t(label)} class={[variant === 'segmented' ? 'ui-segmented' : 'flex flex-wrap items-center gap-xs', className]} style={styleText(style)}>{@render children?.()}</div>

package/src/demo/DemoCopyButton.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/interface.css'
   import '@master/internal-site/styles/system/copy.css'
 
@@ -28,19 +30,19 @@
   async function copy() {
     if (busy) return
     busy = true
-    report('Copying…', undefined)
+    report(t('Copying…'), undefined)
     try {
       if (!window.isSecureContext || !navigator.clipboard?.writeText) throw new Error('Clipboard unavailable')
       await navigator.clipboard.writeText(value)
-      report(feedback === 'compact' ? 'Copied' : `Copied ${value}`, 'success')
+      report(feedback === 'compact' ? t('Copied') : t('Copied {value}').replace('{value}', value), 'success')
     } catch {
-      report(feedback === 'compact' ? 'Copy unavailable' : `Copy unavailable: ${value}`, 'error')
+      report(feedback === 'compact' ? t('Copy unavailable') : t('Copy unavailable: {value}').replace('{value}', value), 'error')
     } finally { busy = false }
   }
 </script>
 
 {#snippet button()}
-  <button data-size={className ? undefined : 'sm'} {...props} type="button" aria-label={label} class={className ?? 'ui-button'} style={styleText(style)} aria-busy={busy} onclick={copy}>
+  <button data-size={className ? undefined : 'sm'} {...props} type="button" aria-label={t(label)} class={className ?? 'ui-button'} style={styleText(style)} aria-busy={busy} onclick={copy}>
     {#if icon === undefined}<IconCopy aria-hidden="true" />{:else if icon}{@render icon()}{/if}{@render children?.()}
   </button>
 {/snippet}

package/src/demo/DemoCopyGroup.svelte

@@ -1,17 +1,19 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/system/copy.css'
 
   import type { Snippet } from 'svelte'
   import { setCopyFeedback, type CopyResult } from '@master/internal-site/demo/copy-feedback.ts'
 
   /** One status for a set of copy actions, such as a palette. The buttons must render in this group's Svelte tree. */
-  let { children, instruction = 'Select a swatch to copy its variable.' }: { children?: Snippet, instruction?: string } = $props()
+  let { children, instruction = t('Select a swatch to copy its variable.') }: { children?: Snippet, instruction?: string } = $props()
   let state = $state<{ instruction: string, message: string, result: CopyResult }>()
   const current = $derived(state?.instruction === instruction ? state : undefined)
   setCopyFeedback((message, result) => { state = { instruction, message, result } })
 </script>
 
 <div class="grid gap-sm">
-  <p class="m(0) ui-copy"><span class="ui-copy-status" role="status" data-result={current?.result}>{current?.message ?? instruction}</span></p>
+  <p class="m(0) ui-copy"><span class="ui-copy-status" role="status" data-result={current?.result}>{current?.message ?? t(instruction)}</span></p>
   {@render children?.()}
 </div>

package/src/demo/DemoExample.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
 import { referenceDemoSections } from '@master/internal-site/demo/reference/source.ts'
@@ -22,6 +24,6 @@ const printable = source.classes.some(value => value.includes('@media(print)'))
 ---
 
 <Demo title={source.title} frame="none" caption={scene.caption} data-demo-case={`${page}#${section}`}>
-  <DemoViewport client:idle={{ timeout: 500 }} title={`${page}: ${source.title}`} document={demoDocument(source, scene)} responsive={scene.responsive ?? responsive}
+  <DemoViewport client:idle={{ timeout: 500 }} title={`${page}: ${t(source.title)}`} document={demoDocument(source, scene)} responsive={scene.responsive ?? responsive}
     theme={scene.theme ?? themed} print={printable} motion={scene.motion} inspect={scene.inspect ?? (section === 'apply-conditionally' ? [page] : undefined)} height={scene.height} maxWidth={scene.maxWidth} sizing={scene.sizing} />
 </Demo>

package/src/demo/DemoFeatureSupport.svelte

@@ -2,6 +2,8 @@
   import '@master/internal-site/styles/system/inline-code.css'
 
   import '@master/internal-site/styles/system/specimens.css'
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import { onMount } from 'svelte'
 
   /** Reports syntax support only; the example still owns its native CSS behavior. */
@@ -15,6 +17,6 @@
 <p class="flex flex-wrap items-center gap-xs m(0)" data-supported={supported ?? 'unknown'}>
   <code class="ui-inline-code">{condition}</code>
   <span class="ui-badge" data-variant="dot" data-tone={supported ? 'green' : undefined}>
-    {supported === null ? 'Checking…' : supported ? 'Supported' : 'Not supported'}
+    {supported === null ? t('Checking…') : supported ? t('Supported') : t('Not supported')}
   </span>
 </p>

package/src/demo/DemoGeneratedCSS.svelte

@@ -2,9 +2,11 @@
   import '@master/internal-site/styles/system/disclosure.css'
 
   import type { Snippet } from 'svelte'
+  import { getSite } from '@master/internal-site/site'
 
   /** The complete generated stylesheet stays one native, closed disclosure under the source. */
   let { children }: { children?: Snippet } = $props()
+  const { t } = getSite()
 </script>
 
-<details class="ui-disclosure"><summary>Generated CSS</summary>{@render children?.()}</details>
+<details class="ui-disclosure"><summary>{t('Generated CSS')}</summary>{@render children?.()}</details>

package/src/demo/DemoIndex.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
 import '@master/internal-site/styles/interface.css'
 import '@master/internal-site/styles/system/specimens.css'
 
@@ -16,9 +18,9 @@ interface Props {
 const { label, groups } = Astro.props
 ---
 
-<nav class="grid gap-md" aria-label={label}>
+<nav class="grid gap-md" aria-label={t(label)}>
   {groups.map(group => <div class="grid gap-xs">
-    <p class="m(0) ui-label">{group.title}</p>
-    <ul class="flex flex-wrap gap-2xs m(0) p(0) (list-style:none)">{group.links.map(link => <li><a class="ui-button" data-size="sm" href={link.href}>{link.label}</a></li>)}</ul>
+    <p class="m(0) ui-label">{t(group.title)}</p>
+    <ul class="flex flex-wrap gap-2xs m(0) p(0) (list-style:none)">{group.links.map(link => <li><a class="ui-button" data-size="sm" href={link.href}>{t(link.label)}</a></li>)}</ul>
   </div>)}
 </nav>

package/src/demo/DemoLegend.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/system/specimens.css'
   import type { HTMLAttributes } from 'svelte/elements'
   import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
@@ -10,6 +12,6 @@
   } = $props()
 </script>
 
-<ul {...props} class={['ui-legend', className]} style={styleText(style)} aria-label="Legend">
+<ul {...props} class={['ui-legend', className]} style={styleText(style)} aria-label={t('Legend')}>
   {#each items as { label, tone: value } (label)}<li><i data-tone={tone(value)} aria-hidden="true"></i>{label}</li>{/each}
 </ul>

package/src/demo/DemoMeasure.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/system/specimens.css'
   import type { Snippet } from 'svelte'
 
@@ -20,8 +22,8 @@
 
 <div class="ui-measure">
   <div class="ui-measure-head">
-    <span>{label}</span>
-    <output aria-label={`${label} dimensions`}>{size ? `${size.width} × ${size.height} px` : 'Measuring…'}</output>
+    <span>{t(label)}</span>
+    <output aria-label={t('{label} dimensions').replace('{label}', t(label))}>{size ? `${size.width} × ${size.height} px` : t('Measuring…')}</output>
   </div>
   <div class="ui-measure-rule" aria-hidden="true"></div>
   <div bind:this={element}>{@render children?.()}</div>

package/src/demo/DemoMedia.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/system/specimens.css'
   import type { ClassValue } from 'svelte/elements'
   import type { SVGAttributes } from 'svelte/elements'
@@ -27,7 +29,7 @@
   {@const imageProps: SiteImageProps = { width: 320, height: 200, ...(props as Omit<ImageProps, 'src' | 'alt' | 'style'>), style: styleText(style), src, alt: alt! }}
   <Image {...imageProps} />
 {:else}
-  <svg viewBox="0 0 320 200" role="img" aria-label="Sun above two mountain ridges" {...props as SVGAttributes<SVGSVGElement>}
+  <svg viewBox="0 0 320 200" role="img" aria-label={t('Sun above two mountain ridges')} {...props as SVGAttributes<SVGSVGElement>}
     style={[`color:var(--ui-tone-${value})`, styleText(style)].filter(Boolean).join(';')}>
     <rect width="320" height="200" fill="var(--ui-surface-sheet)" />
     <path d="M0 175V158l92-93 113 110H0Z" fill="currentColor" opacity=".1" />

package/src/demo/DemoMotion.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/interface.css'
   import type { Snippet } from 'svelte'
   import { onMount } from 'svelte'
@@ -32,11 +34,11 @@
 
 <div class="grid gap-md w-full">
   <div bind:this={element} data-playback={playing ? 'playing' : 'paused'}>{@render children?.()}</div>
-  <div class="ui-player" role="group" aria-label="Animation controls" data-state={playing ? 'playing' : 'paused'}>
+  <div class="ui-player" role="group" aria-label={t('Animation controls')} data-state={playing ? 'playing' : 'paused'}>
     <button type="button" class="ui-button" data-size="sm" onclick={() => control(playing ? 'pause' : 'play')}>
-      {#if playing}<IconPlayerPause aria-hidden="true" />{:else}<IconPlayerPlay aria-hidden="true" />{/if}{playing ? 'Pause' : 'Play'}
+      {#if playing}<IconPlayerPause aria-hidden="true" />{:else}<IconPlayerPlay aria-hidden="true" />{/if}{playing ? t('Pause') : t('Play')}
     </button>
-    <button type="button" class="ui-button" data-size="sm" data-variant="quiet" onclick={() => control('restart')}><IconRefresh aria-hidden="true" />Replay</button>
+    <button type="button" class="ui-button" data-size="sm" data-variant="quiet" onclick={() => control('restart')}><IconRefresh aria-hidden="true" />{t('Replay')}</button>
     <span class="ui-player-time"><output>{playing ? 'Playing' : 'Paused'}</output></span>
   </div>
 </div>

package/src/demo/DemoPaletteGroups.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
   import '@master/internal-site/styles/system/specimens.css'
   import DemoCopyButton from '@master/internal-site/demo/DemoCopyButton.svelte'
   import DemoCopyGroup from '@master/internal-site/demo/DemoCopyGroup.svelte'
@@ -8,8 +10,8 @@
 </script>
 
 <div class="w-full"><DemoCopyGroup><div class="ui-palette">
-  {#each groups as { family, colors } (family)}<div class="ui-palette-row" role="group" aria-label={`${family} palette`}>
+  {#each groups as { family, colors } (family)}<div class="ui-palette-row" role="group" aria-label={t('{family} palette').replace('{family}', family)}>
     <span>{family}</span>
-    {#each colors as { name, value } (name)}<DemoCopyButton value={`var(--${name})`} label={`Copy ${name}`} icon={null} class="ui-palette-chip" style={`background-color:${value}`} title={`${name}: ${value}`} />{/each}
+    {#each colors as { name, value } (name)}<DemoCopyButton value={`var(--${name})`} label={t('Copy {name}').replace('{name}', name)} icon={null} class="ui-palette-chip" style={`background-color:${value}`} title={`${name}: ${value}`} />{/each}
   </div>{/each}
 </div></DemoCopyGroup></div>

package/src/demo/DemoStyleComparison.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context'
+const { t } = siteOf(Astro)
 import '@master/internal-site/styles/system/compare.css'
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
@@ -18,9 +20,9 @@ const { html, css, height = 320, sizing = 'viewport', caption } = Astro.props
 const document = (styles: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><style>${styles.replaceAll('</style', '<\\/style')}</style></head><body>${html}</body></html>`
 ---
 
-<Demo title="Browser defaults and author CSS" description="The same HTML in two documents" frame="none" caption={caption}>
+<Demo title={t("Browser defaults and author CSS")} description={t("The same HTML in two documents")} frame="none" caption={caption}>
   <div class="ui-compare">
-    <figure><figcaption>Browser defaults</figcaption><DemoViewport client:idle={{ timeout: 500 }} title="Browser defaults" document={document('')} height={height} sizing={sizing} /></figure>
-    <figure><figcaption>CSS applied</figcaption><DemoViewport client:idle={{ timeout: 500 }} title="CSS applied" document={document(css)} height={height} sizing={sizing} /></figure>
+    <figure><figcaption>{t("Browser defaults")}</figcaption><DemoViewport client:idle={{ timeout: 500 }} title={t("Browser defaults")} document={document('')} height={height} sizing={sizing} /></figure>
+    <figure><figcaption>{t("CSS applied")}</figcaption><DemoViewport client:idle={{ timeout: 500 }} title={t("CSS applied")} document={document(css)} height={height} sizing={sizing} /></figure>
   </div>
 </Demo>

package/src/demo/DemoThemeComparison.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
 import '@master/internal-site/styles/system/compare.css'
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
@@ -24,8 +26,8 @@ const document = (mode: 'light' | 'dark') => demoDocument({ page: 'foundations',
 <Demo title={title} frame="none" caption={caption} data-foundation-paint={name}>
   <div class="ui-compare">
     {(['light', 'dark'] as const).map(mode => <figure data-theme-specimen={mode}>
-      <figcaption>{mode === 'light' ? 'Light' : 'Dark'}</figcaption>
-      <DemoViewport client:idle={{ timeout: 500 }} title={`${title} · ${mode}`} document={document(mode)} initialTheme={mode} print={print} height={height} sizing="content" />
+      <figcaption>{mode === 'light' ? t('Light') : t('Dark')}</figcaption>
+      <DemoViewport client:idle={{ timeout: 500 }} title={`${t(title)} · ${mode === 'light' ? t('Light') : t('Dark')}`} document={document(mode)} initialTheme={mode} print={print} height={height} sizing="content" />
     </figure>)}
   </div>
 </Demo>

package/src/demo/DemoTokenTable.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
 import '@master/internal-site/styles/system/table.css'
 import InlineCode from '@master/internal-site/components/InlineCode.astro'
 import RenderNode from '@master/internal-site/components/RenderNode.astro'
@@ -22,8 +24,8 @@ const { rows, descriptionTitle = 'Role' } = Astro.props
 ---
 
 {/* Narrow token inventories need native keyboard scrolling. */}
-<div class="ui-table" role="region" aria-label={`${descriptionTitle} token table`} tabindex="0"><table>
-  <thead><tr><th scope="col">Token / class</th><th scope="col" class="(min-width:12rem)">{descriptionTitle}</th></tr></thead>
+<div class="ui-table" role="region" aria-label={t('{label} token table').replace('{label}', t(descriptionTitle))} tabindex="0"><table>
+  <thead><tr><th scope="col">{t('Token / class')}</th><th scope="col" class="(min-width:12rem)">{t(descriptionTitle)}</th></tr></thead>
   <tbody>{rows.map(({ token, utilities, value, description, preview }) => <tr>
     <td>
       <div class="whitespace-nowrap">{preview != null && <RenderNode node={preview} />}<code>{token}</code></div>

package/src/demo/DemoViewTransition.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context'
+const { t } = siteOf(Astro)
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
 
@@ -14,5 +16,5 @@ const title = articles ? 'From collection to article' : 'A change of view'
 
 <Demo title={title} frame="none" data-view-transition={example}
   caption={articles ? 'Open an article, then return to its card. Each image and title keeps a unique snapshot name. Keyboard focus follows the view change.' : 'Choose a view. The panel and heading use named snapshots; unsupported browsers and reduced motion use the same immediate update.'}>
-  <DemoViewport client:idle={{ timeout: 500 }} title={title} src={origin + (articles ? '/examples/article-transitions' : '/examples/view-transitions')} height={articles ? 640 : 340} sizing="viewport" />
+  <DemoViewport client:idle={{ timeout: 500 }} title={t(title)} src={origin + (articles ? '/examples/article-transitions' : '/examples/view-transitions')} height={articles ? 640 : 340} sizing="viewport" />
 </Demo>