mdorigin 0.4.1 → 0.5.1

package/dist/core/site-config.d.ts

@@ -1,5 +1,6 @@
 import type { ContentStore } from './content-store.js';
 import type { MdoPlugin } from './extensions.js';
+import { type SiteMessages } from '../i18n/messages.js';
 export interface SiteNavItem {
     label: string;
     href: string;
@@ -17,6 +18,19 @@ export interface SiteSocialLink {
 export interface EditLinkConfig {
     baseUrl: string;
 }
+export interface SiteRssConfigInput {
+    title?: string;
+    description?: string;
+    author?: string;
+    maxItems?: number;
+}
+export interface SiteRssConfig {
+    enabled: boolean;
+    title?: string;
+    description?: string;
+    author?: string;
+    maxItems: number;
+}
 export interface SiteSearchRerankerConfig {
     kind?: 'embedding-v1' | 'heuristic-v1';
     candidatePoolSize?: number;
@@ -51,6 +65,16 @@ export interface SiteSearchConfig {
 export interface SiteConfig {
     siteTitle?: string;
     siteDescription?: string;
+    /** Site UI locale (BCP 47) used for built-in chrome messages. Defaults to 'en'. */
+    locale?: string;
+    /** Flat overrides for built-in UI messages; keys are typed via SiteMessages. */
+    messages?: Partial<SiteMessages>;
+    /**
+     * Content locales for a multilingual site. Each non-default locale keeps its
+     * content under a top-level `{code}/` directory that maps 1:1 to its URL
+     * path prefix. Omit for single-language sites.
+     */
+    locales?: LocaleConfigInput[];
     siteUrl?: string;
     favicon?: string;
     socialImage?: string;
@@ -63,6 +87,7 @@ export interface SiteConfig {
     footerText?: string;
     socialLinks?: SiteSocialLink[];
     editLink?: EditLinkConfig;
+    rss?: false | SiteRssConfigInput;
     showHomeIndex?: boolean;
     listingInitialPostCount?: number;
     listingLoadMoreStep?: number;
@@ -74,6 +99,9 @@ export interface UserSiteConfig extends SiteConfig {
 export interface ResolvedSiteConfig {
     siteTitle: string;
     siteDescription?: string;
+    locale: string;
+    messages: Partial<SiteMessages>;
+    locales?: ResolvedLocaleConfig[];
     siteUrl?: string;
     favicon?: string;
     socialImage?: string;
@@ -85,6 +113,7 @@ export interface ResolvedSiteConfig {
     footerText?: string;
     socialLinks: SiteSocialLink[];
     editLink?: EditLinkConfig;
+    rss?: SiteRssConfig;
     showHomeIndex: boolean;
     listingInitialPostCount: number;
     listingLoadMoreStep: number;
@@ -104,6 +133,30 @@ export interface LoadedSiteConfig {
     configFilePath: string;
     configModulePath?: string;
 }
+export interface LocaleConfigInput {
+    /** BCP 47 locale code, e.g. 'en' or 'zh-CN'. Also the content directory name. */
+    code: string;
+    /** Switcher display label. Defaults to the code. */
+    label?: string;
+    /**
+     * URL path prefix. Must be '' (only allowed for the default locale) or
+     * '/{code}'. Defaults to '' for the default locale and '/{code}' otherwise.
+     */
+    pathPrefix?: string;
+    /** Mark exactly one locale as default. */
+    default?: boolean;
+    /** UI message overrides for this locale; win over global `messages`. */
+    messages?: Partial<SiteMessages>;
+}
+export interface ResolvedLocaleConfig {
+    code: string;
+    label: string;
+    pathPrefix: string;
+    isDefault: boolean;
+    /** Content base directory: '' (content root) for an unprefixed default locale, otherwise `{code}`. */
+    contentBase: string;
+    messages: Partial<SiteMessages>;
+}
 export declare function loadSiteConfig(options?: LoadSiteConfigOptions): Promise<ResolvedSiteConfig>;
 export declare function loadUserSiteConfig(options?: LoadSiteConfigOptions): Promise<LoadedSiteConfig>;
 export declare function applySiteConfigFrontmatterDefaults(store: ContentStore, siteConfig: ResolvedSiteConfig): Promise<ResolvedSiteConfig>;

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),
@@ -42,6 +49,7 @@ export async function loadUserSiteConfig(options = {}) {
             : undefined,
         socialLinks: normalizeSocialLinks(parsedConfig.socialLinks),
         editLink: normalizeEditLink(parsedConfig.editLink),
+        rss: normalizeRssConfig(parsedConfig.rss),
         showHomeIndex: typeof parsedConfig.showHomeIndex === 'boolean'
             ? parsedConfig.showHomeIndex
             : normalizeTopNav(parsedConfig.topNav).length === 0,
@@ -87,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) {
@@ -222,6 +319,36 @@ function normalizeOptionalNumber(value) {
     }
     return undefined;
 }
+function normalizeRssConfig(value) {
+    if (value === false) {
+        return {
+            enabled: false,
+            title: undefined,
+            description: undefined,
+            author: undefined,
+            maxItems: 20,
+        };
+    }
+    if (typeof value !== 'object' || value === null) {
+        return {
+            enabled: true,
+            title: undefined,
+            description: undefined,
+            author: undefined,
+            maxItems: 20,
+        };
+    }
+    const rss = value;
+    return {
+        enabled: true,
+        title: typeof rss.title === 'string' && rss.title !== '' ? rss.title : undefined,
+        description: typeof rss.description === 'string' && rss.description !== ''
+            ? rss.description
+            : undefined,
+        author: typeof rss.author === 'string' && rss.author !== '' ? rss.author : undefined,
+        maxItems: normalizePositiveInteger(rss.maxItems, 20),
+    };
+}
 function normalizeSearchConfig(value, configFilePath) {
     if (typeof value !== 'object' || value === null) {
         return undefined;

package/dist/core/site-url.d.ts

@@ -0,0 +1,2 @@
+export declare function trimLeadingSlash(value: string): string;
+export declare function ensureTrailingSlash(value: string): string;

package/dist/core/site-url.js

@@ -0,0 +1,6 @@
+export function trimLeadingSlash(value) {
+    return value.startsWith('/') ? value.slice(1) : value;
+}
+export function ensureTrailingSlash(value) {
+    return value.endsWith('/') ? value : `${value}/`;
+}

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;
@@ -21,11 +25,24 @@ export interface RenderDocumentOptions {
     stylesheetContent?: string;
     canonicalPath?: string;
     alternateMarkdownPath?: string;
+    rssFeedUrl?: string;
     listingEntries?: ManagedIndexEntry[];
     listingRequestPath?: string;
     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
@@ -25,6 +28,14 @@ export function renderDocument(options) {
     const alternateMarkdownMeta = options.alternateMarkdownPath
         ? `<link rel="alternate" type="text/markdown" href="${escapeHtml(options.alternateMarkdownPath)}">`
         : '';
+    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
@@ -34,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>`)
@@ -67,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>`
@@ -89,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">',
@@ -107,6 +125,8 @@ export function renderDocument(options) {
         faviconMeta,
         socialImageMeta,
         alternateMarkdownMeta,
+        rssMeta,
+        hreflangMeta,
         stylesheetBlock,
         '</head>',
         '<body>',
@@ -159,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;
     }
@@ -170,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('');
 }
@@ -200,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]');
@@ -219,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;
@@ -229,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);
@@ -252,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;
     }
   };
 
@@ -269,7 +294,7 @@ function renderListingLoadMoreScript() {
 })();
 </script>`;
 }
-function renderSearchScript() {
+function renderSearchScript(messages, localeFilter) {
     return [
         '<script>',
         '(function () {',
@@ -281,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) {',
@@ -323,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));',
@@ -331,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;