mdorigin 0.5.0 → 0.5.1

package/README.md

@@ -23,7 +23,7 @@ That means `mdorigin` should own content semantics, while page rendering remains
 - extensionless routes render human-friendly HTML from the same files
 - `README.md`, `index.md`, and `SKILL.md` all fit into one routing model
 - the same core works in local preview and Cloudflare Workers
-- optional search is powered by [`indexbind`](https://github.com/jolestar/indexbind)
+- optional search is powered by [`indexbind`](https://github.com/holon-run/indexbind)
 
 ## Install
 
@@ -87,7 +87,7 @@ The intended boundary is:
 
 ## Optional Search
 
-`mdorigin` can build a local retrieval bundle through the optional [`indexbind`](https://github.com/jolestar/indexbind) package. For the retrieval engine itself, see the `indexbind` docs: <https://indexbind.jolestar.workers.dev>.
+`mdorigin` can build a local retrieval bundle through the optional [`indexbind`](https://github.com/holon-run/indexbind) package. For the retrieval engine itself, see the `indexbind` docs: <https://indexbind.jolestar.workers.dev>.
 
 ```bash
 npm install indexbind
@@ -127,7 +127,7 @@ Runtime endpoints:
 
 ## Docs
 
-- Docs site: <https://mdorigin.jolestar.workers.dev>
+- Docs site: <https://mdorigin.holon.run>
 - Getting started: [`docs/site/guides/getting-started.md`](docs/site/guides/getting-started.md)
 - Routing model: [`docs/site/concepts/routing.md`](docs/site/concepts/routing.md)
 - Directory indexes: [`docs/site/concepts/directory-indexes.md`](docs/site/concepts/directory-indexes.md)
@@ -136,4 +136,4 @@ Runtime endpoints:
 - Search setup: [`docs/site/guides/getting-started.md`](docs/site/guides/getting-started.md#quick-start)
 - Cloudflare deployment: [`docs/site/guides/cloudflare.md`](docs/site/guides/cloudflare.md)
 
-The docs site at <https://mdorigin.jolestar.workers.dev> is deployed automatically from `main` with GitHub Actions.
+The docs site at <https://mdorigin.holon.run> is deployed automatically from `main` with GitHub Actions.

package/dist/adapters/cloudflare.js

@@ -48,6 +48,8 @@ export function createCloudflareWorker(manifest, options = {}) {
                 siteConfig: manifest.siteConfig ?? {
                     siteTitle: 'mdorigin',
                     siteUrl: undefined,
+                    locale: 'en',
+                    messages: {},
                     favicon: undefined,
                     logo: undefined,
                     showDate: true,

package/dist/cli/build-index.js

@@ -23,6 +23,9 @@ export async function runBuildIndexCommand(argv) {
         rootDir,
         dir,
         plugins: loadedConfig.plugins,
+        excludedDirectories: (loadedConfig.siteConfig.locales ?? [])
+            .filter((locale) => locale.contentBase !== '')
+            .map((locale) => locale.contentBase),
     });
     console.log(`updated ${result.updatedFiles.length} index file(s)`);
     if (result.skippedDirectories.length > 0) {

package/dist/core/extensions.d.ts

@@ -8,10 +8,23 @@ export interface IndexTransformContext {
     sourcePath?: string;
     siteConfig?: ResolvedSiteConfig;
 }
+export interface PageLanguage {
+    code: string;
+    label: string;
+    /** Root-relative href for this language: the translated page when available, otherwise the language home. */
+    href: string;
+    current: boolean;
+    /** Whether a page-level translation exists for this language. */
+    translated: boolean;
+}
 export interface PageRenderModel {
     kind: 'page' | 'listing';
     requestPath: string;
     sourcePath: string;
+    /** Effective UI locale for this request (frontmatter overrides not applied). */
+    locale: string;
+    /** Language switcher entries; empty for single-language sites. */
+    languages: PageLanguage[];
     siteTitle: string;
     siteDescription?: string;
     siteUrl?: string;

package/dist/core/request-handler.js

@@ -6,11 +6,17 @@ import { extractManagedIndexEntries, getDocumentSummary, getDocumentTitle as get
 import { ensureTrailingSlash, trimLeadingSlash } from './site-url.js';
 import { applyIndexTransforms, renderFooterOverride, renderHeaderOverride, renderPageWithPlugins, transformHtmlWithPlugins, } from './extensions.js';
 import { handleApiRoute } from './api.js';
-import { normalizeRequestPath, resolveRequest } from './router.js';
+import { matchRequestLocale, normalizeRequestPath, resolveRequest } from './router.js';
 import { escapeHtml, renderListingArticleItems, renderDocument, } from '../html/template.js';
+import { formatSiteMessage, resolveSiteMessages, } from '../i18n/messages.js';
 export async function handleSiteRequest(store, pathname, options) {
     const plugins = options.plugins ?? [];
     const searchEnabled = options.searchApi !== undefined;
+    const requestLocale = matchRequestLocale(pathname, options.siteConfig.locales);
+    const defaultLocale = options.siteConfig.locales?.find((locale) => locale.isDefault);
+    if (defaultLocale !== undefined && defaultLocale.pathPrefix !== '' && pathname === '/') {
+        return redirect(`${defaultLocale.pathPrefix}/`);
+    }
     const apiRoute = await handleApiRoute(pathname, options.searchParams, {
         searchApi: options.searchApi,
         siteConfig: options.siteConfig,
@@ -23,7 +29,14 @@ export async function handleSiteRequest(store, pathname, options) {
         return renderSitemap(store, options);
     }
     if (pathname === '/feed.xml') {
-        return renderRssFeed(store, options);
+        return renderRssFeed(store, options, defaultLocale ?? null);
+    }
+    if (options.siteConfig.locales !== undefined && requestLocale !== null) {
+        for (const locale of options.siteConfig.locales) {
+            if (locale.pathPrefix !== '' && pathname === `${locale.pathPrefix}/feed.xml`) {
+                return renderRssFeed(store, options, locale);
+            }
+        }
     }
     const resolved = resolveRequest(pathname);
     const listingFragmentRequest = getListingFragmentRequest(options.searchParams);
@@ -58,20 +71,20 @@ export async function handleSiteRequest(store, pathname, options) {
             if (directoryIndexResponse !== null) {
                 return directoryIndexResponse;
             }
-            return renderDirectoryListing(store, resolved.requestPath, options.siteConfig, searchEnabled);
+            return renderDirectoryListing(store, resolved.requestPath, options.siteConfig, searchEnabled, requestLocale);
         }
-        return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown);
+        return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown, requestLocale);
     }
     if (resolved.kind === 'asset') {
         return serveAsset(entry);
     }
     if (entry.kind !== 'text' || entry.text === undefined) {
-        return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown);
+        return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown, requestLocale);
     }
     if (resolved.kind === 'markdown' || negotiatedMarkdown) {
         const parsed = await parseMarkdownDocument(resolved.sourcePath, entry.text);
         if (parsed.meta.draft === true && options.draftMode === 'exclude') {
-            return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown);
+            return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown, requestLocale);
         }
         return {
             status: 200,
@@ -83,7 +96,7 @@ export async function handleSiteRequest(store, pathname, options) {
     }
     const parsed = await parseMarkdownDocument(resolved.sourcePath, entry.text);
     if (parsed.meta.draft === true && options.draftMode === 'exclude') {
-        return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown);
+        return renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown, requestLocale);
     }
     const navigation = await resolveTopNav(store, options.siteConfig);
     const renderedBody = isRootHomeRequest(resolved.requestPath) && !options.siteConfig.showHomeIndex
@@ -114,6 +127,9 @@ export async function handleSiteRequest(store, pathname, options) {
         listingEntries,
         searchEnabled,
         plugins,
+        store,
+        requestLocale,
+        draftMode: options.draftMode,
         varyOnAccept: shouldVaryOnAccept(resolved),
     });
 }
@@ -148,6 +164,8 @@ function buildPageRenderModel(options) {
         kind: options.listingEntries.length > 0 ? 'listing' : 'page',
         requestPath: options.resolvedRequestPath,
         sourcePath: options.sourcePath,
+        locale: options.locale,
+        languages: options.languages,
         siteTitle: options.siteConfig.siteTitle,
         siteDescription: options.siteConfig.siteDescription,
         siteUrl: options.siteConfig.siteUrl,
@@ -180,9 +198,18 @@ function buildPageRenderModel(options) {
     };
 }
 async function renderStructuredPage(options) {
+    const localeConfig = options.requestLocale;
+    const localeCode = localeConfig?.code ?? options.siteConfig.locale;
+    const messages = getEffectiveLocaleMessages(options.siteConfig, localeConfig);
+    const htmlLang = getFrontmatterLocale(options.parsed.meta) ?? localeCode;
+    const languages = await buildLanguageOptions(options.store, { sourcePath: options.sourcePath }, localeConfig, options.siteConfig, options.draftMode);
+    const hreflangAlternates = buildHreflangAlternates(languages, options.siteConfig);
+    const searchLocaleFilter = buildSearchLocaleFilter(options.siteConfig, localeConfig);
     const page = buildPageRenderModel({
         resolvedRequestPath: options.requestPath,
         sourcePath: options.sourcePath,
+        locale: localeCode,
+        languages,
         renderedBodyHtml: options.renderedParsed.html,
         parsed: options.parsed,
         siteConfig: options.siteConfig,
@@ -204,6 +231,8 @@ async function renderStructuredPage(options) {
         return renderDocument({
             siteTitle: currentPage.siteTitle,
             siteDescription: currentPage.siteDescription,
+            locale: htmlLang,
+            messages,
             siteUrl: currentPage.siteUrl,
             favicon: currentPage.favicon,
             socialImage: currentPage.socialImage,
@@ -222,12 +251,15 @@ async function renderStructuredPage(options) {
             stylesheetContent: currentPage.stylesheetContent,
             canonicalPath: currentPage.canonicalPath,
             alternateMarkdownPath: currentPage.alternateMarkdownPath,
-            rssFeedUrl: getRssFeedUrl(currentPage.siteUrl, options.siteConfig),
+            rssFeedUrl: getRssFeedUrl(currentPage.siteUrl, options.siteConfig, localeConfig),
             listingEntries: currentPage.listingEntries,
             listingRequestPath: currentPage.listingRequestPath,
             listingInitialPostCount: currentPage.listingInitialPostCount,
             listingLoadMoreStep: currentPage.listingLoadMoreStep,
             searchEnabled: currentPage.searchEnabled,
+            languages: currentPage.languages,
+            hreflangAlternates,
+            searchLocaleFilter,
             headerHtml,
             footerHtml,
         });
@@ -292,20 +324,26 @@ function notFound() {
 }
 async function renderNotFoundForRequest(store, pathname, options) {
     const resolved = resolveRequest(pathname);
-    return renderNotFoundForResolvedRequest(store, resolved, options, false);
+    return renderNotFoundForResolvedRequest(store, resolved, options, false, matchRequestLocale(pathname, options.siteConfig.locales));
 }
-async function renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown) {
+async function renderNotFoundForResolvedRequest(store, resolved, options, negotiatedMarkdown, requestLocale) {
     const varyOnAccept = shouldVaryOnAccept(resolved);
     if (resolved.kind !== 'html' || negotiatedMarkdown) {
         return withNotFoundVary(varyOnAccept);
     }
-    return renderHtmlNotFound(store, resolved.requestPath, options, varyOnAccept);
+    return renderHtmlNotFound(store, resolved.requestPath, options, varyOnAccept, requestLocale);
 }
-async function renderHtmlNotFound(store, requestPath, options, varyOnAccept) {
+async function renderHtmlNotFound(store, requestPath, options, varyOnAccept, requestLocale) {
     const navigation = await resolveTopNav(store, options.siteConfig);
+    const localeConfig = requestLocale;
+    const locale = localeConfig?.code ?? options.siteConfig.locale;
+    const messages = getEffectiveLocaleMessages(options.siteConfig, localeConfig);
+    const languages = await buildLanguageOptions(store, {}, localeConfig, options.siteConfig, options.draftMode);
     const body = [
-        '<h1>Not Found</h1>',
-        `<p>No page was published at <code>${escapeHtml(requestPath)}</code>.</p>`,
+        `<h1>${escapeHtml(messages['error.notFoundTitle'])}</h1>`,
+        `<p>${formatSiteMessage(messages['error.notFoundBody'], {
+            path: escapeHtml(requestPath),
+        })}</p>`,
     ].join('');
     return {
         status: 404,
@@ -319,8 +357,11 @@ async function renderHtmlNotFound(store, requestPath, options, varyOnAccept) {
             favicon: options.siteConfig.favicon,
             socialImage: options.siteConfig.socialImage,
             logo: options.siteConfig.logo,
-            title: 'Not Found',
+            title: messages['error.notFoundTitle'],
             body,
+            locale,
+            messages,
+            languages,
             showSummary: false,
             showDate: false,
             topNav: navigation.items,
@@ -328,7 +369,7 @@ async function renderHtmlNotFound(store, requestPath, options, varyOnAccept) {
             footerText: options.siteConfig.footerText,
             socialLinks: options.siteConfig.socialLinks,
             stylesheetContent: options.siteConfig.stylesheetContent,
-            rssFeedUrl: getRssFeedUrl(options.siteConfig.siteUrl, options.siteConfig),
+            rssFeedUrl: getRssFeedUrl(options.siteConfig.siteUrl, options.siteConfig, localeConfig),
             searchEnabled: options.searchApi !== undefined,
         }),
     };
@@ -352,6 +393,127 @@ function redirect(location) {
         },
     };
 }
+function getEffectiveLocaleMessages(siteConfig, localeConfig) {
+    if (localeConfig === null) {
+        return resolveSiteMessages(siteConfig.locale, siteConfig.messages);
+    }
+    return resolveSiteMessages(localeConfig.code, {
+        ...siteConfig.messages,
+        ...localeConfig.messages,
+    });
+}
+function getFrontmatterLocale(meta) {
+    if (typeof meta.lang !== 'string') {
+        return null;
+    }
+    const trimmed = meta.lang.trim();
+    return trimmed === '' ? null : trimmed;
+}
+async function buildLanguageOptions(store, target, currentLocale, siteConfig, draftMode) {
+    const locales = siteConfig.locales;
+    if (locales === undefined || locales.length === 0) {
+        return [];
+    }
+    const languages = [];
+    for (const locale of locales) {
+        const translated = await localeHasContent(store, target, currentLocale, locale, draftMode);
+        languages.push({
+            code: locale.code,
+            label: locale.label,
+            href: translated === null
+                ? getLocaleHomePath(locale)
+                : getCanonicalHtmlPathForContentPath(translated),
+            current: locale === currentLocale,
+            translated: translated !== null,
+        });
+    }
+    return languages;
+}
+async function localeHasContent(store, target, currentLocale, locale, draftMode) {
+    if (locale === currentLocale) {
+        return target.sourcePath
+            ? target.sourcePath
+            : target.directoryPath === ''
+                ? 'index.md'
+                : `${target.directoryPath}/index.md`;
+    }
+    const candidates = [];
+    if (target.sourcePath !== undefined) {
+        candidates.push(mapContentPathForLocale(target.sourcePath, currentLocale, locale));
+    }
+    else {
+        const directoryPath = target.directoryPath ?? '';
+        for (const candidate of getDirectoryIndexCandidates(mapContentPathForLocale(directoryPath, currentLocale, locale))) {
+            candidates.push(candidate);
+        }
+    }
+    for (const candidate of candidates) {
+        if (await hasPublishedContent(store, candidate, draftMode)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function mapContentPathForLocale(contentPath, from, to) {
+    if (from === null || from.contentBase === '') {
+        return to.contentBase === '' ? contentPath : `${to.contentBase}/${contentPath}`;
+    }
+    if (!contentPath.startsWith(`${from.contentBase}/`)) {
+        return contentPath;
+    }
+    const rest = contentPath.slice(from.contentBase.length + 1);
+    return to.contentBase === '' ? rest : `${to.contentBase}/${rest}`;
+}
+function getLocaleHomePath(locale) {
+    return locale.pathPrefix === '' ? '/' : `${locale.pathPrefix}/`;
+}
+async function hasPublishedContent(store, contentPath, draftMode) {
+    const entry = await store.get(contentPath);
+    if (entry === null || entry.kind !== 'text' || entry.text === undefined) {
+        return false;
+    }
+    if (draftMode === 'exclude') {
+        const parsed = await parseMarkdownDocument(contentPath, entry.text);
+        if (parsed.meta.draft === true) {
+            return false;
+        }
+    }
+    return true;
+}
+function buildHreflangAlternates(languages, siteConfig) {
+    if (languages.length === 0 || siteConfig.siteUrl === undefined) {
+        return [];
+    }
+    const base = ensureTrailingSlash(siteConfig.siteUrl);
+    const alternates = languages
+        .filter((language) => language.translated)
+        .map((language) => ({
+        hreflang: language.code,
+        href: new URL(trimLeadingSlash(language.href), base).toString(),
+    }));
+    const defaultLocale = siteConfig.locales?.find((locale) => locale.isDefault);
+    const defaultLanguage = defaultLocale
+        ? languages.find((language) => language.code === defaultLocale.code)
+        : undefined;
+    if (defaultLanguage?.translated) {
+        alternates.push({
+            hreflang: 'x-default',
+            href: new URL(trimLeadingSlash(defaultLanguage.href), base).toString(),
+        });
+    }
+    return alternates;
+}
+function buildSearchLocaleFilter(siteConfig, localeConfig) {
+    if (siteConfig.locales === undefined || localeConfig === null) {
+        return undefined;
+    }
+    return {
+        include: localeConfig.contentBase === '' ? '' : `${localeConfig.contentBase}/`,
+        exclude: siteConfig.locales
+            .filter((locale) => locale !== localeConfig && locale.contentBase !== '')
+            .map((locale) => `${locale.contentBase}/`),
+    };
+}
 async function renderSitemap(store, options) {
     if (!options.siteConfig.siteUrl) {
         return {
@@ -380,13 +542,16 @@ async function renderSitemap(store, options) {
         body,
     };
 }
-async function renderRssFeed(store, options) {
+async function renderRssFeed(store, options, locale) {
     if (!isRssEnabled(options.siteConfig) || !options.siteConfig.siteUrl) {
         return notFound();
     }
-    const items = await collectRssFeedItems(store, '', options);
+    const excludedLocaleDirectories = new Set((options.siteConfig.locales ?? [])
+        .filter((entry) => entry.contentBase !== '' && entry !== locale)
+        .map((entry) => entry.contentBase));
+    const items = await collectRssFeedItems(store, locale?.contentBase ?? '', options, excludedLocaleDirectories);
     const limitedItems = items.slice(0, options.siteConfig.rss?.maxItems ?? 20);
-    const rssFeedUrl = getRssFeedUrl(options.siteConfig.siteUrl, options.siteConfig);
+    const rssFeedUrl = getRssFeedUrl(options.siteConfig.siteUrl, options.siteConfig, locale);
     const title = options.siteConfig.rss?.title ?? options.siteConfig.siteTitle;
     const description = options.siteConfig.rss?.description ?? options.siteConfig.siteDescription;
     const lastBuildDate = limitedItems[0]?.pubDate.toUTCString();
@@ -503,7 +668,7 @@ function dedupeSitemapEntries(entries) {
     }
     return Array.from(deduped.values());
 }
-async function collectRssFeedItems(store, directoryPath, options) {
+async function collectRssFeedItems(store, directoryPath, options, excludedDirectories) {
     const entries = await store.listDirectory(directoryPath);
     if (entries === null) {
         return [];
@@ -512,7 +677,10 @@ async function collectRssFeedItems(store, directoryPath, options) {
     const directoryShape = inspectDirectoryShapeEntries(entries);
     for (const entry of entries) {
         if (entry.kind === 'directory') {
-            feedItems.push(...(await collectRssFeedItems(store, entry.path, options)));
+            if (excludedDirectories.has(entry.path)) {
+                continue;
+            }
+            feedItems.push(...(await collectRssFeedItems(store, entry.path, options, excludedDirectories)));
             continue;
         }
         if (!isMarkdownEntry(entry)) {
@@ -571,7 +739,7 @@ function parseFeedDate(value) {
     const parsed = new Date(value);
     return Number.isNaN(parsed.getTime()) ? null : parsed;
 }
-async function renderDirectoryListing(store, requestPath, siteConfig, searchEnabled) {
+async function renderDirectoryListing(store, requestPath, siteConfig, searchEnabled, requestLocale) {
     const directoryPath = requestPath === '/' ? '' : requestPath.slice(1).replace(/\/$/, '');
     const entries = await store.listDirectory(directoryPath);
     if (entries === null) {
@@ -579,12 +747,17 @@ async function renderDirectoryListing(store, requestPath, siteConfig, searchEnab
     }
     const visibleEntries = entries.filter(isVisibleDirectoryEntry);
     const navigation = await resolveTopNav(store, siteConfig);
+    const locale = requestLocale?.code ?? siteConfig.locale;
+    const messages = getEffectiveLocaleMessages(siteConfig, requestLocale);
+    const languages = await buildLanguageOptions(store, { directoryPath }, requestLocale, siteConfig, 'exclude');
     const listItems = visibleEntries
         .map((entry) => `<li><a href="${getDirectoryEntryHref(requestPath, entry)}">${escapeHtml(getDirectoryEntryLabel(entry))}</a></li>`)
         .join('');
     const body = [
         `<h1>${escapeHtml(getDirectoryTitle(requestPath))}</h1>`,
-        visibleEntries.length > 0 ? `<ul>${listItems}</ul>` : '<p>This directory is empty.</p>',
+        visibleEntries.length > 0
+            ? `<ul>${listItems}</ul>`
+            : `<p>${escapeHtml(messages['listing.emptyDirectory'])}</p>`,
     ].join('');
     return {
         status: 200,
@@ -594,6 +767,9 @@ async function renderDirectoryListing(store, requestPath, siteConfig, searchEnab
         body: renderDocument({
             siteTitle: siteConfig.siteTitle,
             siteDescription: siteConfig.siteDescription,
+            locale,
+            messages,
+            languages,
             siteUrl: siteConfig.siteUrl,
             favicon: siteConfig.favicon,
             logo: siteConfig.logo,
@@ -608,7 +784,7 @@ async function renderDirectoryListing(store, requestPath, siteConfig, searchEnab
             stylesheetContent: siteConfig.stylesheetContent,
             canonicalPath: requestPath,
             alternateMarkdownPath: getMarkdownRequestPathForContentPath(getDirectoryIndexContentPathForRequestPath(requestPath)),
-            rssFeedUrl: getRssFeedUrl(siteConfig.siteUrl, siteConfig),
+            rssFeedUrl: getRssFeedUrl(siteConfig.siteUrl, siteConfig, requestLocale),
             searchEnabled,
         }),
     };
@@ -684,6 +860,9 @@ async function tryRenderAlternateDirectoryIndex(store, requestPath, options) {
             listingEntries,
             searchEnabled: options.searchApi !== undefined,
             plugins,
+            store,
+            requestLocale: matchRequestLocale(requestPath, options.siteConfig.locales),
+            draftMode: options.draftMode,
         });
     }
     return null;
@@ -859,11 +1038,14 @@ function getCanonicalHtmlPathForContentPath(contentPath) {
 function isRssEnabled(siteConfig) {
     return Boolean(siteConfig.siteUrl) && (siteConfig.rss?.enabled ?? true);
 }
-function getRssFeedUrl(siteUrl, siteConfig) {
+function getRssFeedUrl(siteUrl, siteConfig, locale) {
     if (!siteUrl || !isRssEnabled(siteConfig)) {
         return undefined;
     }
-    return new URL('feed.xml', ensureTrailingSlash(siteUrl)).toString();
+    const feedPath = locale !== null && locale.pathPrefix !== ''
+        ? `${locale.pathPrefix.slice(1)}/feed.xml`
+        : 'feed.xml';
+    return new URL(feedPath, ensureTrailingSlash(siteUrl)).toString();
 }
 function getEditLinkHref(siteConfig, sourcePath) {
     if (!siteConfig.editLink || !sourcePath) {
@@ -886,9 +1068,15 @@ async function resolveTopNav(store, siteConfig) {
         };
     }
     const directories = rootEntries.filter((entry) => entry.kind === 'directory');
+    const localeDirectoryNames = new Set((siteConfig.locales ?? [])
+        .filter((locale) => locale.contentBase !== '')
+        .map((locale) => locale.contentBase));
     const navItems = [];
     const orderedNavItems = [];
     for (const entry of directories) {
+        if (localeDirectoryNames.has(entry.name)) {
+            continue;
+        }
         const resolved = await resolveDirectoryNav(store, entry);
         if (resolved.type !== 'page') {
             continue;

package/dist/core/router.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedLocaleConfig } from './site-config.js';
 export type ResolvedRequestKind = 'markdown' | 'html' | 'asset' | 'not-found';
 export interface ResolvedRequest {
     kind: ResolvedRequestKind;
@@ -6,3 +7,11 @@ export interface ResolvedRequest {
 }
 export declare function resolveRequest(pathname: string): ResolvedRequest;
 export declare function normalizeRequestPath(pathname: string): string | null;
+/**
+ * Attributes a request path to a configured content locale. Locale URL
+ * prefixes map 1:1 to top-level `{code}` content directories, so attribution
+ * never rewrites content resolution: a path that matches a locale prefix keeps
+ * resolving to that locale's directory, and any other path belongs to the
+ * default locale (whose content lives at the content root when unprefixed).
+ */
+export declare function matchRequestLocale(pathname: string, locales: readonly ResolvedLocaleConfig[] | undefined): ResolvedLocaleConfig | null;

package/dist/core/router.js

@@ -80,3 +80,29 @@ export function normalizeRequestPath(pathname) {
         return null;
     }
 }
+/**
+ * Attributes a request path to a configured content locale. Locale URL
+ * prefixes map 1:1 to top-level `{code}` content directories, so attribution
+ * never rewrites content resolution: a path that matches a locale prefix keeps
+ * resolving to that locale's directory, and any other path belongs to the
+ * default locale (whose content lives at the content root when unprefixed).
+ */
+export function matchRequestLocale(pathname, locales) {
+    if (locales === undefined || locales.length === 0) {
+        return null;
+    }
+    const normalized = normalizeRequestPath(pathname);
+    if (normalized === null) {
+        return null;
+    }
+    const prefixed = locales
+        .filter((locale) => locale.pathPrefix !== '')
+        .sort((left, right) => right.pathPrefix.length - left.pathPrefix.length);
+    for (const locale of prefixed) {
+        if (normalized === locale.pathPrefix ||
+            normalized.startsWith(`${locale.pathPrefix}/`)) {
+            return locale;
+        }
+    }
+    return locales.find((locale) => locale.isDefault) ?? null;
+}

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;
@@ -64,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;
@@ -88,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;
@@ -119,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>;