mdorigin 0.5.0 → 0.5.1

package/dist/core/site-config.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 import { tsImport } from 'tsx/esm/api';
 import { getDirectoryIndexCandidates } from './directory-index.js';
 import { parseMarkdownDocument } from './markdown.js';
+import { DEFAULT_SITE_LOCALE, validateSiteMessages, } from '../i18n/messages.js';
 export async function loadSiteConfig(options = {}) {
     return (await loadUserSiteConfig(options)).siteConfig;
 }
@@ -15,6 +16,8 @@ export async function loadUserSiteConfig(options = {}) {
         : await resolveDefaultConfigPath(cwd, rootDir);
     const parsedConfig = await loadConfigSource(configFilePath);
     const legacyConfig = parsedConfig;
+    const messageOverrides = resolveMessageOverrides(parsedConfig.messages, configFilePath);
+    const locales = resolveLocalesConfig(parsedConfig, configFilePath);
     const stylesheetPath = parsedConfig.stylesheet
         ? path.resolve(path.dirname(configFilePath), parsedConfig.stylesheet)
         : null;
@@ -29,6 +32,10 @@ export async function loadUserSiteConfig(options = {}) {
             parsedConfig.siteDescription !== ''
             ? parsedConfig.siteDescription
             : undefined,
+        locale: locales?.find((locale) => locale.isDefault)?.code ??
+            normalizeSiteLocale(parsedConfig.locale),
+        messages: messageOverrides,
+        locales,
         siteUrl: normalizeSiteUrl(parsedConfig.siteUrl),
         favicon: normalizeSiteHref(parsedConfig.favicon),
         socialImage: normalizeSiteHref(parsedConfig.socialImage),
@@ -88,6 +95,95 @@ export async function applySiteConfigFrontmatterDefaults(store, siteConfig) {
     }
     return siteConfig;
 }
+function resolveMessageOverrides(value, configFilePath) {
+    if (value === undefined) {
+        return {};
+    }
+    const { messages, unknownKeys } = validateSiteMessages(value);
+    if (unknownKeys.length > 0) {
+        throw new Error(`[mdorigin] ${configFilePath}: "messages" contains unknown keys: ${unknownKeys.join(', ')}`);
+    }
+    return messages;
+}
+function normalizeSiteLocale(value) {
+    if (typeof value !== 'string') {
+        return DEFAULT_SITE_LOCALE;
+    }
+    const trimmed = value.trim();
+    return trimmed === '' ? DEFAULT_SITE_LOCALE : trimmed;
+}
+const LOCALE_CODE_PATTERN = /^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/;
+function resolveLocalesConfig(parsedConfig, configFilePath) {
+    const input = parsedConfig.locales;
+    if (input === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(input) || input.length === 0) {
+        throw new Error(`[mdorigin] ${configFilePath}: "locales" must be a non-empty array when configured`);
+    }
+    const seenCodes = new Set();
+    const parsed = [];
+    for (const entry of input) {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`[mdorigin] ${configFilePath}: every "locales" entry must be an object`);
+        }
+        const locale = entry;
+        const code = typeof locale.code === 'string' ? locale.code.trim() : '';
+        if (code === '' || !LOCALE_CODE_PATTERN.test(code)) {
+            throw new Error(`[mdorigin] ${configFilePath}: "locales[].code" must be a BCP 47 style code like "en" or "zh-CN"`);
+        }
+        const normalizedCodeKey = code.toLowerCase();
+        if (seenCodes.has(normalizedCodeKey)) {
+            throw new Error(`[mdorigin] ${configFilePath}: duplicate "locales" code: ${code}`);
+        }
+        seenCodes.add(normalizedCodeKey);
+        const isDefault = locale.default === true;
+        const pathPrefix = resolveLocalePathPrefix(locale, isDefault, configFilePath);
+        const { messages, unknownKeys } = validateSiteMessages(locale.messages);
+        if (unknownKeys.length > 0) {
+            throw new Error(`[mdorigin] ${configFilePath}: "locales[${code}].messages" contains unknown keys: ${unknownKeys.join(', ')}`);
+        }
+        parsed.push({
+            code,
+            label: typeof locale.label === 'string' && locale.label.trim() !== ''
+                ? locale.label.trim()
+                : code,
+            pathPrefix,
+            isDefault,
+            messages,
+        });
+    }
+    const defaultCount = parsed.filter((locale) => locale.isDefault).length;
+    if (defaultCount !== 1) {
+        throw new Error(`[mdorigin] ${configFilePath}: "locales" must mark exactly one locale with "default": true (found ${defaultCount})`);
+    }
+    const defaultLocale = parsed.find((locale) => locale.isDefault);
+    const configuredLocale = typeof parsedConfig.locale === 'string' ? parsedConfig.locale.trim() : '';
+    if (configuredLocale !== '' &&
+        configuredLocale.toLowerCase() !== defaultLocale?.code.toLowerCase()) {
+        throw new Error(`[mdorigin] ${configFilePath}: "locale" (${configuredLocale}) conflicts with the default "locales" entry (${defaultLocale?.code}); remove "locale" or align it with the default locale`);
+    }
+    return parsed.map((locale) => ({
+        ...locale,
+        contentBase: locale.pathPrefix === '' ? '' : locale.code,
+    }));
+}
+function resolveLocalePathPrefix(locale, isDefault, configFilePath) {
+    if (locale.pathPrefix === undefined) {
+        return isDefault ? '' : `/${locale.code}`;
+    }
+    const prefix = locale.pathPrefix;
+    if (prefix === '') {
+        if (!isDefault) {
+            throw new Error(`[mdorigin] ${configFilePath}: "locales[${locale.code}].pathPrefix" can only be empty for the default locale`);
+        }
+        return '';
+    }
+    if (prefix !== `/${locale.code}`) {
+        throw new Error(`[mdorigin] ${configFilePath}: "locales[${locale.code}].pathPrefix" must be "/${locale.code}" or "" (default locales only); got "${prefix}"`);
+    }
+    return prefix;
+}
 async function resolveDefaultConfigPath(cwd, rootDir) {
     const rootConfigPath = rootDir ? await findConfigPath(rootDir) : null;
     if (rootConfigPath) {

package/dist/html/template.d.ts

@@ -1,8 +1,12 @@
 import type { SiteLogo, SiteNavItem, SiteSocialLink } from '../core/site-config.js';
+import type { PageLanguage } from '../core/extensions.js';
 import type { ManagedIndexEntry } from '../core/markdown.js';
+import { type SiteMessages } from '../i18n/messages.js';
 export interface RenderDocumentOptions {
     siteTitle: string;
     siteDescription?: string;
+    locale?: string;
+    messages?: SiteMessages;
     siteUrl?: string;
     favicon?: string;
     socialImage?: string;
@@ -27,6 +31,18 @@ export interface RenderDocumentOptions {
     listingInitialPostCount?: number;
     listingLoadMoreStep?: number;
     searchEnabled?: boolean;
+    /** Language switcher entries; rendered in the header when more than one is present. */
+    languages?: PageLanguage[];
+    /** hreflang alternates with absolute URLs, including x-default when applicable. */
+    hreflangAlternates?: Array<{
+        hreflang: string;
+        href: string;
+    }>;
+    /** Locale content filter handed to the search client script. */
+    searchLocaleFilter?: {
+        include: string;
+        exclude: string[];
+    };
     headerHtml?: string;
     footerHtml?: string;
 }

package/dist/html/template.js

@@ -1,5 +1,8 @@
+import { DEFAULT_SITE_LOCALE, resolveSiteMessages, serializeMessagesForScript, } from '../i18n/messages.js';
 import { getDefaultThemeStyles } from './theme.js';
 export function renderDocument(options) {
+    const locale = options.locale ?? DEFAULT_SITE_LOCALE;
+    const messages = options.messages ?? resolveSiteMessages(locale);
     const title = escapeHtml(options.title);
     const siteTitle = escapeHtml(options.siteTitle);
     const siteDescription = options.siteDescription
@@ -28,6 +31,11 @@ export function renderDocument(options) {
     const rssMeta = options.rssFeedUrl
         ? `<link rel="alternate" type="application/rss+xml" title="${siteTitle}" href="${escapeHtml(options.rssFeedUrl)}">`
         : '';
+    const hreflangMeta = options.hreflangAlternates && options.hreflangAlternates.length > 0
+        ? options.hreflangAlternates
+            .map((alternate) => `<link rel="alternate" hreflang="${escapeHtml(alternate.hreflang)}" href="${escapeHtml(alternate.href)}">`)
+            .join('')
+        : '';
     const stylesheetBlock = `<style>${getDefaultThemeStyles()}${options.stylesheetContent ? `\n${options.stylesheetContent}` : ''}</style>`;
     const navBlock = options.topNav && options.topNav.length > 0
         ? `<nav class="site-nav"><ul>${options.topNav
@@ -37,21 +45,26 @@ export function renderDocument(options) {
     const searchToggleBlock = options.searchEnabled
         ? [
             '<div class="site-search" data-site-search>',
-            '<button type="button" class="site-search__toggle" aria-expanded="false" aria-controls="site-search-panel">Search</button>',
+            `<button type="button" class="site-search__toggle" aria-expanded="false" aria-controls="site-search-panel">${escapeHtml(messages['search.toggle'])}</button>`,
             '<div id="site-search-panel" class="site-search__panel" hidden>',
             '<form class="site-search__form" role="search" action="/api/search" method="get">',
-            '<label class="site-search__label" for="site-search-input">Search site</label>',
+            `<label class="site-search__label" for="site-search-input">${escapeHtml(messages['search.label'])}</label>`,
             '<div class="site-search__controls">',
-            '<input id="site-search-input" class="site-search__input" type="search" name="q" placeholder="Search docs and skills" autocomplete="off">',
-            '<button type="submit" class="site-search__submit">Go</button>',
+            `<input id="site-search-input" class="site-search__input" type="search" name="q" placeholder="${escapeHtml(messages['search.placeholder'])}" autocomplete="off">`,
+            `<button type="submit" class="site-search__submit">${escapeHtml(messages['search.go'])}</button>`,
             '</div>',
-            '<p class="site-search__hint">Search is powered by <code>/api/search</code>.</p>',
+            `<p class="site-search__hint">${messages['search.hint']}</p>`,
             '</form>',
             '<div class="site-search__results" data-site-search-results></div>',
             '</div>',
             '</div>',
         ].join('')
         : '';
+    const languagesBlock = options.languages && options.languages.length > 1
+        ? `<nav class="site-languages" aria-label="${escapeHtml(messages['languages.ariaLabel'])}"><ul>${options.languages
+            .map((language) => `<li><a href="${escapeHtml(language.href)}" hreflang="${escapeHtml(language.code)}"${language.current ? ' aria-current="page"' : ''}>${escapeHtml(language.label)}</a></li>`)
+            .join('')}</ul></nav>`
+        : '';
     const footerNavBlock = options.footerNav && options.footerNav.length > 0
         ? `<nav class="site-footer__nav"><ul>${options.footerNav
             .map((item) => `<li><a href="${escapeHtml(item.href)}">${escapeHtml(item.label)}</a></li>`)
@@ -70,10 +83,10 @@ export function renderDocument(options) {
         : '';
     const brandHref = escapeHtml(options.logo?.href ?? '/');
     const editLinkBlock = options.editLinkHref
-        ? `<a class="site-footer__edit-link" href="${escapeHtml(options.editLinkHref)}">Edit this page</a>`
+        ? `<a class="site-footer__edit-link" href="${escapeHtml(options.editLinkHref)}">${escapeHtml(messages['footer.editPage'])}</a>`
         : '';
     const markdownViewBlock = options.alternateMarkdownPath
-        ? `<a class="site-footer__markdown-link" href="${escapeHtml(options.alternateMarkdownPath)}" aria-label="View Markdown source">MD View</a>`
+        ? `<a class="site-footer__markdown-link" href="${escapeHtml(options.alternateMarkdownPath)}" aria-label="${escapeHtml(messages['footer.markdownViewAria'])}">${escapeHtml(messages['footer.markdownView'])}</a>`
         : '';
     const footerActionsBlock = markdownViewBlock || editLinkBlock
         ? `<div class="site-footer__actions">${markdownViewBlock}${editLinkBlock}</div>`
@@ -92,15 +105,17 @@ export function renderDocument(options) {
             requestPath: options.listingRequestPath ?? '/',
             initialPostCount: options.listingInitialPostCount ?? 10,
             loadMoreStep: options.listingLoadMoreStep ?? 10,
-        })
+        }, messages)
         : options.body;
-    const searchScript = options.searchEnabled ? renderSearchScript() : '';
+    const searchScript = options.searchEnabled
+        ? renderSearchScript(messages, options.searchLocaleFilter)
+        : '';
     const headerBlock = options.headerHtml ??
-        `<header class="site-header"><div class="site-header__inner"><div class="site-header__brand"><p class="site-header__title"><a href="${brandHref}">${logoBlock}<span>${siteTitle}</span></a></p>${siteDescriptionBlock}</div><div class="site-header__actions">${navBlock}${searchToggleBlock}</div></div></header>`;
+        `<header class="site-header"><div class="site-header__inner"><div class="site-header__brand"><p class="site-header__title"><a href="${brandHref}">${logoBlock}<span>${siteTitle}</span></a></p>${siteDescriptionBlock}</div><div class="site-header__actions">${navBlock}${languagesBlock}${searchToggleBlock}</div></div></header>`;
     const renderedFooterBlock = options.footerHtml ?? footerBlock;
     return [
         '<!doctype html>',
-        '<html lang="en">',
+        `<html lang="${escapeHtml(locale)}">`,
         '<head>',
         '<meta charset="utf-8">',
         '<meta name="viewport" content="width=device-width, initial-scale=1">',
@@ -111,6 +126,7 @@ export function renderDocument(options) {
         socialImageMeta,
         alternateMarkdownMeta,
         rssMeta,
+        hreflangMeta,
         stylesheetBlock,
         '</head>',
         '<body>',
@@ -163,7 +179,7 @@ function renderSocialIcon(icon) {
 function iconSvg(pathData) {
     return `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="${pathData}"></path></svg>`;
 }
-function renderListingArticle(body, entries, options) {
+function renderListingArticle(body, entries, options, messages) {
     if (entries.length === 0) {
         return body;
     }
@@ -174,26 +190,26 @@ function renderListingArticle(body, entries, options) {
     const shouldLoadMore = articles.length > visibleArticles.length;
     return [
         `<div class="catalog-page__body">${body}</div>`,
-        '<section class="catalog-page" aria-label="Content listing">',
-        directories.length > 0 ? renderListingDirectories(directories) : '',
+        `<section class="catalog-page" aria-label="${escapeHtml(messages['listing.ariaLabel'])}">`,
+        directories.length > 0 ? renderListingDirectories(directories, messages) : '',
         articles.length > 0
             ? renderListingArticles(visibleArticles, {
                 requestPath: options.requestPath,
                 nextOffset: visibleArticles.length,
                 loadMoreStep: options.loadMoreStep,
                 hasMore: shouldLoadMore,
-            })
+            }, messages)
             : '',
         '</section>',
-        shouldLoadMore ? renderListingLoadMoreScript() : '',
+        shouldLoadMore ? renderListingLoadMoreScript(messages) : '',
     ].join('');
 }
-function renderListingDirectories(entries) {
+function renderListingDirectories(entries, messages) {
     return [
         '<div class="catalog-list catalog-list--directories">',
         ...entries.map((entry) => `<a class="catalog-item catalog-item--directory" href="${escapeHtml(entry.href)}"><strong class="catalog-item__title">${escapeHtml(entry.title)}</strong>${entry.detail
             ? `<span class="catalog-item__detail">${escapeHtml(entry.detail)}</span>`
-            : '<span class="catalog-item__detail">Browse this section.</span>'}</a>`),
+            : `<span class="catalog-item__detail">${escapeHtml(messages['listing.browseSection'])}</span>`}</a>`),
         '</div>',
     ].join('');
 }
@@ -204,17 +220,17 @@ export function renderListingArticleItems(entries) {
         : ''}</a>`)
         .join('');
 }
-function renderListingArticles(entries, options) {
+function renderListingArticles(entries, options, messages) {
     return [
         '<div class="catalog-list" data-listing-articles>',
         renderListingArticleItems(entries),
         '</div>',
         options.hasMore
-            ? `<div class="catalog-load-more"><button type="button" class="catalog-load-more__button" data-listing-load-more data-request-path="${escapeHtml(options.requestPath)}" data-next-offset="${escapeHtml(String(options.nextOffset))}" data-load-more-step="${escapeHtml(String(options.loadMoreStep))}">Load more</button></div>`
+            ? `<div class="catalog-load-more"><button type="button" class="catalog-load-more__button" data-listing-load-more data-request-path="${escapeHtml(options.requestPath)}" data-next-offset="${escapeHtml(String(options.nextOffset))}" data-load-more-step="${escapeHtml(String(options.loadMoreStep))}">${escapeHtml(messages['listing.loadMore'])}</button></div>`
             : '',
     ].join('');
 }
-function renderListingLoadMoreScript() {
+function renderListingLoadMoreScript(messages) {
     return `<script>
 (() => {
   const button = document.querySelector('[data-listing-load-more]');
@@ -223,6 +239,11 @@ function renderListingLoadMoreScript() {
     return;
   }
 
+  const M = ${serializeMessagesForScript({
+        loadMore: messages['listing.loadMore'],
+        loading: messages['listing.loading'],
+    })};
+
   const loadMore = async () => {
     const requestPath = button.dataset.requestPath;
     const nextOffset = button.dataset.nextOffset;
@@ -233,7 +254,7 @@ function renderListingLoadMoreScript() {
 
     button.disabled = true;
     const previousLabel = button.textContent;
-    button.textContent = 'Loading...';
+    button.textContent = M.loading;
 
     try {
       const url = new URL(requestPath, window.location.origin);
@@ -256,14 +277,14 @@ function renderListingLoadMoreScript() {
       if (payload.hasMore === true && typeof payload.nextOffset === 'number') {
         button.dataset.nextOffset = String(payload.nextOffset);
         button.disabled = false;
-        button.textContent = previousLabel ?? 'Load more';
+        button.textContent = previousLabel ?? M.loadMore;
         return;
       }
 
       button.remove();
     } catch {
       button.disabled = false;
-      button.textContent = previousLabel ?? 'Load more';
+      button.textContent = previousLabel ?? M.loadMore;
     }
   };
 
@@ -273,7 +294,7 @@ function renderListingLoadMoreScript() {
 })();
 </script>`;
 }
-function renderSearchScript() {
+function renderSearchScript(messages, localeFilter) {
     return [
         '<script>',
         '(function () {',
@@ -285,41 +306,59 @@ function renderSearchScript() {
         '  const input = root.querySelector(".site-search__input");',
         '  const results = root.querySelector("[data-site-search-results]");',
         '  if (!toggle || !panel || !form || !input || !results) return;',
+        `  const M = ${serializeMessagesForScript({
+            resultsEmpty: messages['search.resultsEmpty'],
+            searching: messages['search.searching'],
+            failed: messages['search.failed'],
+            failedWithStatus: messages['search.failedWithStatus'],
+            enterQuery: messages['search.enterQuery'],
+            initialHint: messages['search.initialHint'],
+            untitled: messages['search.untitled'],
+        })};`,
+        `  const F = ${localeFilter === undefined ? 'null' : serializeMessagesForScript(localeFilter)};`,
         '  let controller = null;',
         '  function renderMessage(message) {',
         '    results.innerHTML = `<p class="site-search__message">${escapeHtmlForScript(message)}</p>`;',
         '  }',
         '  function renderHits(hits) {',
         '    if (!Array.isArray(hits) || hits.length === 0) {',
-        '      renderMessage("No results.");',
+        '      renderMessage(M.resultsEmpty);',
         '      return;',
         '    }',
         '    results.innerHTML = hits.map((hit) => {',
         '      const href = escapeHtmlForScript(hit.canonicalUrl || hit.docId || "#");',
-        '      const title = escapeHtmlForScript(hit.title || hit.relativePath || "Untitled");',
+        '      const title = escapeHtmlForScript(hit.title || hit.relativePath || M.untitled);',
         '      const summary = typeof hit.summary === "string" ? `<span class="site-search__item-summary">${escapeHtmlForScript(hit.summary)}</span>` : "";',
         '      const excerpt = hit.bestMatch && typeof hit.bestMatch.excerpt === "string" ? `<span class="site-search__item-excerpt">${escapeHtmlForScript(hit.bestMatch.excerpt)}</span>` : "";',
         '      return `<a class="site-search__item" href="${href}"><strong class="site-search__item-title">${title}</strong>${summary}${excerpt}</a>`;',
         '    }).join("");',
         '  }',
+        '  function filterHits(hits) {',
+        '    if (!F || !Array.isArray(hits)) return hits;',
+        '    return hits.filter((hit) => {',
+        '      if (typeof hit.relativePath !== "string") return false;',
+        '      if (F.include !== "" && !hit.relativePath.startsWith(F.include)) return false;',
+        '      return !F.exclude.some((prefix) => hit.relativePath.startsWith(prefix));',
+        '    });',
+        '  }',
         '  async function runSearch(query) {',
         '    if (controller) controller.abort();',
         '    controller = new AbortController();',
-        '    renderMessage("Searching...");',
+        '    renderMessage(M.searching);',
         '    try {',
         '      const url = new URL("/api/search", window.location.origin);',
         '      url.searchParams.set("q", query);',
         '      url.searchParams.set("topK", "8");',
         '      const response = await fetch(url, { signal: controller.signal });',
         '      if (!response.ok) {',
-        '        renderMessage(`Search failed (${response.status}).`);',
+        '        renderMessage(M.failedWithStatus.replaceAll("{status}", String(response.status)));',
         '        return;',
         '      }',
         '      const payload = await response.json();',
-        '      renderHits(payload.hits);',
+        '      renderHits(filterHits(payload.hits));',
         '    } catch (error) {',
         '      if (error && typeof error === "object" && "name" in error && error.name === "AbortError") return;',
-        '      renderMessage("Search failed.");',
+        '      renderMessage(M.failed);',
         '    }',
         '  }',
         '  function setOpen(open) {',
@@ -327,7 +366,7 @@ function renderSearchScript() {
         '    panel.hidden = !open;',
         '    if (open) {',
         '      input.focus();',
-        '      if (!results.innerHTML) renderMessage("Search docs, guides, and skills.");',
+        '      if (!results.innerHTML) renderMessage(M.initialHint);',
         '    }',
         '  }',
         '  toggle.addEventListener("click", () => setOpen(panel.hidden));',
@@ -335,7 +374,7 @@ function renderSearchScript() {
         '    event.preventDefault();',
         '    const query = input.value.trim();',
         '    if (!query) {',
-        '      renderMessage("Enter a search query.");',
+        '      renderMessage(M.enterQuery);',
         '      return;',
         '    }',
         '    void runSearch(query);',

package/dist/html/theme.js

@@ -219,6 +219,35 @@ a:hover { color: var(--link-hover); text-decoration: underline; }
   white-space: nowrap;
 }
 .site-nav a:hover { color: var(--link-hover); }
+.site-languages ul {
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.6rem;
+  margin: 0;
+  padding: 0;
+  align-items: center;
+}
+.site-languages li {
+  display: flex;
+  align-items: center;
+}
+.site-languages a {
+  color: var(--muted);
+  font-size: 0.85rem;
+  display: inline-flex;
+  align-items: center;
+  min-height: 2.25rem;
+  padding: 0 0.05rem;
+  white-space: nowrap;
+}
+.site-languages a:hover { color: var(--link-hover); }
+.site-languages a[aria-current='page'] {
+  color: inherit;
+  font-weight: 700;
+  text-decoration: underline;
+  text-underline-offset: 0.25em;
+}
 main {
   max-width: calc(var(--max) + 4rem);
   margin: 0 auto;

package/dist/i18n/messages.d.ts

@@ -0,0 +1,45 @@
+export interface SiteMessages {
+    'search.toggle': string;
+    'search.label': string;
+    'search.placeholder': string;
+    'search.go': string;
+    'search.hint': string;
+    'search.resultsEmpty': string;
+    'search.searching': string;
+    'search.failed': string;
+    'search.failedWithStatus': string;
+    'search.enterQuery': string;
+    'search.initialHint': string;
+    'search.untitled': string;
+    'footer.editPage': string;
+    'footer.markdownView': string;
+    'footer.markdownViewAria': string;
+    'languages.ariaLabel': string;
+    'listing.browseSection': string;
+    'listing.loadMore': string;
+    'listing.loading': string;
+    'listing.ariaLabel': string;
+    'listing.emptyDirectory': string;
+    'error.notFoundTitle': string;
+    'error.notFoundBody': string;
+}
+export type SiteMessageKey = keyof SiteMessages;
+export declare const DEFAULT_SITE_LOCALE = "en";
+export declare function isKnownSiteLocale(locale: string): boolean;
+/**
+ * Resolves the effective message set for a locale: built-in English catalog,
+ * overlaid with the built-in catalog for the locale (when available, unknown
+ * locales fall back to English), overlaid with user overrides.
+ */
+export declare function resolveSiteMessages(locale: string | undefined, overrides?: Partial<SiteMessages>): SiteMessages;
+export declare function formatSiteMessage(message: string, params: Record<string, string>): string;
+/**
+ * Serializes messages for embedding inside an inline `<script>` element. `<`
+ * is escaped so that a message containing `</script>` cannot terminate the
+ * script block early.
+ */
+export declare function serializeMessagesForScript(value: Record<string, unknown>): string;
+export declare function validateSiteMessages(value: unknown): {
+    messages: Partial<SiteMessages>;
+    unknownKeys: string[];
+};

package/dist/i18n/messages.js

@@ -0,0 +1,104 @@
+export const DEFAULT_SITE_LOCALE = 'en';
+/**
+ * Built-in message catalogs. Messages are trusted template fragments: they may
+ * contain inline HTML markup such as `<code>` and `{placeholder}` parameters.
+ */
+const enMessages = {
+    'search.toggle': 'Search',
+    'search.label': 'Search site',
+    'search.placeholder': 'Search docs and skills',
+    'search.go': 'Go',
+    'search.hint': 'Search is powered by <code>/api/search</code>.',
+    'search.resultsEmpty': 'No results.',
+    'search.searching': 'Searching...',
+    'search.failed': 'Search failed.',
+    'search.failedWithStatus': 'Search failed ({status}).',
+    'search.enterQuery': 'Enter a search query.',
+    'search.initialHint': 'Search docs, guides, and skills.',
+    'search.untitled': 'Untitled',
+    'footer.editPage': 'Edit this page',
+    'footer.markdownView': 'MD View',
+    'footer.markdownViewAria': 'View Markdown source',
+    'languages.ariaLabel': 'Languages',
+    'listing.browseSection': 'Browse this section.',
+    'listing.loadMore': 'Load more',
+    'listing.loading': 'Loading...',
+    'listing.ariaLabel': 'Content listing',
+    'listing.emptyDirectory': 'This directory is empty.',
+    'error.notFoundTitle': 'Not Found',
+    'error.notFoundBody': 'No page was published at <code>{path}</code>.',
+};
+const zhCnMessages = {
+    'search.toggle': '搜索',
+    'search.label': '搜索站点',
+    'search.placeholder': '搜索文档与技能',
+    'search.go': '搜索',
+    'search.hint': '搜索由 <code>/api/search</code> 提供支持。',
+    'search.resultsEmpty': '没有找到结果。',
+    'search.searching': '搜索中...',
+    'search.failed': '搜索失败。',
+    'search.failedWithStatus': '搜索失败（{status}）。',
+    'search.enterQuery': '请输入搜索关键词。',
+    'search.initialHint': '搜索文档、指南与技能。',
+    'search.untitled': '无标题',
+    'footer.editPage': '编辑此页',
+    'footer.markdownView': 'MD 视图',
+    'footer.markdownViewAria': '查看 Markdown 源文件',
+    'languages.ariaLabel': '语言',
+    'listing.browseSection': '浏览此章节。',
+    'listing.loadMore': '加载更多',
+    'listing.loading': '加载中...',
+    'listing.ariaLabel': '内容列表',
+    'listing.emptyDirectory': '此目录为空。',
+    'error.notFoundTitle': '未找到',
+    'error.notFoundBody': '没有页面发布在 <code>{path}</code>。',
+};
+const messageCatalogs = {
+    en: enMessages,
+    'zh-CN': zhCnMessages,
+};
+const catalogKeys = new Map(Object.keys(messageCatalogs).map((key) => [key.toLowerCase(), key]));
+export function isKnownSiteLocale(locale) {
+    return messageCatalogs[locale] !== undefined;
+}
+/**
+ * Resolves the effective message set for a locale: built-in English catalog,
+ * overlaid with the built-in catalog for the locale (when available, unknown
+ * locales fall back to English), overlaid with user overrides.
+ */
+export function resolveSiteMessages(locale, overrides) {
+    const catalogKey = locale === undefined ? undefined : catalogKeys.get(locale.toLowerCase());
+    const catalog = catalogKey === undefined ? undefined : messageCatalogs[catalogKey];
+    if (catalog === undefined || catalogKey === 'en') {
+        return { ...enMessages, ...(overrides ?? {}) };
+    }
+    return { ...enMessages, ...catalog, ...(overrides ?? {}) };
+}
+export function formatSiteMessage(message, params) {
+    return Object.entries(params).reduce((text, [key, value]) => text.replaceAll(`{${key}}`, value), message);
+}
+/**
+ * Serializes messages for embedding inside an inline `<script>` element. `<`
+ * is escaped so that a message containing `</script>` cannot terminate the
+ * script block early.
+ */
+export function serializeMessagesForScript(value) {
+    return JSON.stringify(value).replaceAll('<', '\\u003c');
+}
+export function validateSiteMessages(value) {
+    const messages = {};
+    const unknownKeys = [];
+    if (typeof value !== 'object' || value === null) {
+        return { messages, unknownKeys };
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        if (!(key in enMessages)) {
+            unknownKeys.push(key);
+            continue;
+        }
+        if (typeof entry === 'string' && entry !== '') {
+            messages[key] = entry;
+        }
+    }
+    return { messages, unknownKeys };
+}

package/dist/index-builder.d.ts

@@ -3,13 +3,15 @@ export interface BuildIndexOptions {
     rootDir?: string;
     dir?: string;
     plugins?: MdoPlugin[];
+    /** Top-level directory names (locale content bases) kept out of managed indexes. */
+    excludedDirectories?: string[];
 }
 export interface BuildIndexResult {
     updatedFiles: string[];
     skippedDirectories: string[];
 }
 export declare function buildDirectoryIndexes(options: BuildIndexOptions): Promise<BuildIndexResult>;
-export declare function buildManagedIndexBlock(directoryPath: string, plugins?: MdoPlugin[]): Promise<string>;
+export declare function buildManagedIndexBlock(directoryPath: string, plugins?: MdoPlugin[], excludedDirectories?: string[]): Promise<string>;
 export declare function upsertManagedIndexBlock(source: string, block: string, options?: {
     directoryPath?: string;
 }): string;