meowpress 0.3.0-alpha.4 → 0.3.0-alpha.6

package/README.md

@@ -3,6 +3,11 @@
 Meowpress builds a static blog from Markdown and MDX, with a built-in Journal-based theme for posts, short notes
 and public skills. A project can supply its own theme or page map through `meowpress/build`.
 
+The built-in theme renders functional icons as inline SVG through Meowtail's Lucide-backed
+`Icon`, not font glyphs. Custom pages can use `Icon` or `IconSource` from `meowtail/icons`
+and the full Lucide set from `meowtail/icons/lucide`; brand artwork such as `GithubIcon`
+stays separate. Icons render at build time and need no browser script or icon font.
+
 ## Build and preview a site
 
 Use Bun and install this version of `meowpress` with compatible `meowcss` and `meowjsx` peers.
@@ -65,6 +70,140 @@ owns `dist/`, set `outputDirectory` to a separate directory and reserve it for g
 to choose the root for those skills. Set `notFound: false` to omit the built-in `404.html`, or
 supply `notFound: { title, message, homeLabel }` to change its copy.
 
+## Site URL and time zone
+
+`site.url` is the public origin of the site, without a path, such as `https://example.com`. It is
+validated and stored without a trailing slash; the build does not use it for output yet. `site.timeZone`
+is an IANA time zone, `Asia/Shanghai` by default. It decides the day key and the `HH:mm` label of a
+post or thought whose date has no calendar date in its text (a date from the file's modified time,
+or text such as `September 1, 2026 23:30 UTC`). A date written as `2026-09-01` or as an ISO
+timestamp keeps its written day. An invalid value fails when the config is resolved.
+
+## Languages
+
+Without `locales`, a site has one locale, English, unprefixed routes and no catalogs. Setting
+`locales` publishes the theme and the content in more languages.
+
+```ts
+export default meowSite({
+  locales: {
+    source: "en",
+    targets: { fr: { label: "Français" } },
+    untranslated: "link",
+    stale: "notice",
+    disclosure: true,
+  },
+});
+```
+
+- `source` is the language the content and the site-owned copy are written in. It keeps today's
+  unprefixed routes. Each `targets` tag is published under `/<tag>/`, with the tag in lower case
+  (`zh-Hant` becomes `/zh-hant/`); `<html lang>` keeps the canonical tag, and `dir="rtl"` is added
+  for right-to-left scripts. `label` is the language's own name. A target equal to the source, an
+  invalid tag, or two tags that are the same after canonicalisation fail when the config is
+  resolved.
+- The theme's own sentences are written in English and declared in one table, exported as
+  `themeMessages`. Every locale other than English takes them from `locales/<tag>.json`, a flat
+  object from the English sentence to its translation (a sentence with a `context` maps to an
+  object from context to translation). `localesDirectory` changes the directory, which resolves
+  against the project directory. `locales.catalogs.<tag>` supplies the same format inline and wins
+  over the file. A missing file is an empty catalog; invalid JSON, or a file that is not an object
+  of strings, fails the build and names the file. The source locale needs a catalog too when it is
+  not English.
+- A sentence with no translation shows its English text. After the build, one line per locale
+  reports how many sentences fell back and which file to fill. A site without `locales` prints
+  nothing.
+- Site-owned copy is translated through the same catalogs, keyed by the text as written in
+  `source`: `site.name`, `site.description`, `site.about.heading`, `paragraphs`, `linksHeading` and
+  each link `label`, and the three `notFound` strings. The source tree prints them as written.
+  `agentGuide` is not translated.
+- Each target gets `/<tag>/` (home), `/<tag>/about/`, `/<tag>/posts/`, `/<tag>/thoughts/`,
+  `/<tag>/404.html` (a host decides whether it serves the file) and a page for every content item
+  written in that language. Dates follow the page locale. Every internal link goes through one
+  helper that points a route that exists only in the source tree, such as skills, to its source
+  URL. Skills pages exist once, in the source locale.
+- With more than one locale the header shows a script-free language switch that points to the same
+  page where the translation exists and to that locale's home otherwise. With `site.url`, pages
+  also carry `<link rel="canonical">`, one `<link rel="alternate" hreflang>` per version and
+  `x-default` for the source; without `site.url` neither is emitted and the build says so once.
+- A target's tag may not equal a top-level route, content asset directory, slug prefix or
+  consumer page path; the build fails and names the tag. A `pages` provider still owns the whole
+  site map: no locale tree is written for it, and it receives the resolved `locales` in its
+  context.
+
+### Translated content
+
+A file name may carry a locale suffix. `content/posts/first.fr.md` is the French translation of
+`content/posts/first.md`; `only-fr.fr.md` without a `only-fr.md` is an original written in French.
+The suffix is read only for a configured locale, so `notes.v2.md` keeps its slug, and it uses the
+canonical tag in lower case. Files that share a kind and slug are one translation set; the member
+in the source locale is the original, and a set without one is a set of originals, one per
+language. `first.md` next to `first.en.md` is an error, because both claim the same slug in the
+source locale.
+
+A translation records what it was translated from:
+
+```yaml
+---
+title: Premier billet
+translation:
+  source: 3f9a1c2e
+  reviewed: false
+---
+```
+
+`translation.source` is the first 12 hex characters of SHA-256 over the original's resolved title,
+a newline and its body with line endings normalised to LF. `reviewed: true` marks a translation a
+person has checked. Both fields are optional; a translation without a recorded hash counts as
+stale. From that the build knows three states without anyone maintaining them: **current** (the
+recorded hash matches the original), **stale** (the original changed since) and **missing**.
+
+- A current or stale translation is published under `/<tag>/<kind>s/<slug>/`.
+- A stale translation is still published, with a notice that the original has changed and a link
+  to it. `stale: "fail"` makes it a build error instead, for a site that would rather not publish
+  it.
+- A translation without `reviewed: true` carries a quiet line saying it is a translation and
+  linking the original; `disclosure: false` removes that line.
+- A missing translation produces no page. In the target's timeline and archives the original is
+  listed with its language marked and `lang` on the entry, linking the original's URL;
+  `untranslated: "omit"` leaves it out instead.
+- A translation inherits `date`, `tags` and `category` from its original unless it sets them. A
+  file whose name used to be its slug (`notes.fr.md` used to publish at `/posts/notes.fr/`) now
+  reads as a suffix, and the build reports the URL that changed.
+
+### The work list
+
+```sh
+meowpress locales                    # one line per missing or stale item
+meowpress locales --json             # the same list as a contract
+meowpress locales stamp content/posts/first.fr.md
+```
+
+The report holds, for each target locale, the interface messages the audit finds missing, unused
+or invalid (theme sentences and site copy), and the content items that are missing or stale with
+the original's file, URL and current hash, the target file and, for a stale item, the hash it was
+translated from. `stamp` writes the original's current hash into a translation's frontmatter after
+it has been written or revised, and adds frontmatter to a file that has none. The loop for "add
+French to this blog" is: configure the locale, run `locales`, write what it names, stamp, run
+`locales` again until it is empty, then build. A site without `locales` refuses both commands.
+
+### Agents as readers
+
+`/translations.json` is published when `locales` is configured and is reserved like `agents.md`:
+it is the same report the work list prints, so an agent can read one file to know what exists and
+what to trust. The root `/llms.txt`, `/llm.txt` and `/agents.md` index the originals, each in its
+own language with that language marked, then link each target's index. A target tree gets
+`/<tag>/llms.txt`, `/<tag>/llm.txt` and `/<tag>/agents.md` next to its pages; they list that tree's
+pages and the originals it shows untranslated, marked with their language and linked to the source
+URL. A `pages` provider that sets `locale` and `original` on a `SitePage` enters the manifest and
+the per-locale index; its Markdown copy starts with `<!-- lang: fr; original: /guides/ -->`.
+
+A right-to-left target is laid out in that direction: the theme's chrome and Meowtail's prose
+mirror through logical properties, dates follow the page locale, and code blocks stay
+left-to-right. Inline code inside right-to-left prose is still subject to the Unicode bidi
+algorithm, as on any site. The default faces cover Latin, Cyrillic and Greek; other scripts use
+system fonts unless the site lists faces in `fonts`.
+
 ## Build from code
 
 `meowSite()` resolves configuration and `buildSite()` writes the site. Both are exported from
@@ -95,6 +234,9 @@ export default meowSite({
 
 - `pages` is a provider of complete HTML documents. A path that resolves above the site root is
   refused rather than clamped.
+- `SitePageContext` carries the resolved `locales` and `pageLocale(tag)`, the locale instance the
+  built-in pages use, with the site's catalogs, time zone and missing-message reporting. A page
+  that sets `locale` and `original` enters `/translations.json` and the per-locale index.
 - A page's optional `markdown` is the same page for agents. It is published next to the route
   (`components/button.md` for `/components/button/`, `index.md` for the root), and `llms.txt`,
   `llm.txt` and `agents.md` link it instead of the HTML. `llms.txt` follows the

package/dist/src/build.d.ts

@@ -1,6 +1,7 @@
 import { type ThemeDefinition } from "meowcss";
 import { type SiteFont } from "./fonts.js";
 import { type SiteIdentity, type SiteNotFound } from "./identity.js";
+import { type ResolvedLocales, type SiteLocales } from "./locales.js";
 import { type ContentSourceInput, type MdxComponent } from "./content.js";
 import { type SitePageProvider } from "./pages.js";
 export { sitePageMarkdownFile } from "./pages.js";
@@ -8,6 +9,7 @@ export type { SitePage, SitePageContext, SitePageProvider } from "./pages.js";
 export type { ContentItem, ContentSource, ContentSourceInput } from "./content.js";
 export type { SiteFont } from "./fonts.js";
 export type { SiteIdentity, SiteNotFound } from "./identity.js";
+export type { ResolvedLocaleTarget, ResolvedLocales, SiteLocales } from "./locales.js";
 export interface SiteConfig {
     /** Roots containing posts, thoughts and optional assets. Defaults to `content/`. */
     content?: ContentSourceInput | readonly ContentSourceInput[];
@@ -41,6 +43,17 @@ export interface SiteConfig {
      * for the default Blog theme and to none for any other theme.
      */
     fonts?: readonly SiteFont[];
+    /**
+     * Languages the site publishes. The source locale keeps today's unprefixed routes and each
+     * target is published under `/<tag>/`. Without it the site has one locale, English, and its
+     * output does not change.
+     */
+    locales?: SiteLocales | ResolvedLocales;
+    /**
+     * Directory of `<tag>.json` interface catalogs, one per configured locale, resolved against the
+     * project directory. Defaults to `locales/`.
+     */
+    localesDirectory?: string;
 }
 export interface ResolvedSiteConfig {
     content: readonly ContentSourceInput[];
@@ -56,6 +69,8 @@ export interface ResolvedSiteConfig {
     mdxComponents: Record<string, MdxComponent>;
     themeStylesheet: string;
     fonts: readonly SiteFont[];
+    locales?: ResolvedLocales;
+    localesDirectory: string;
 }
 /** Define a site config in the app package without taking on the build pipeline. */
 export declare function meowSite(config?: SiteConfig): ResolvedSiteConfig;

package/dist/src/build.js

@@ -1,16 +1,49 @@
 import { removeLegacyIsFallbacks } from "meowcss/bundle";
 import { blogFonts, blogTheme } from "./theme.js";
 import { FONT_EXTERNAL, publishFonts } from "./fonts.js";
-import { DEFAULT_SITE } from "./identity.js";
+import { DEFAULT_SITE, DEFAULT_TIME_ZONE } from "./identity.js";
+import { createPageLocale, localePath } from "./locale.js";
+import { assertNoRouteCollisions, firstSegment, loadLocaleCatalogs, localeSegment, RESERVED_SEGMENTS, resolveLocales, } from "./locales.js";
 import { constants } from "node:fs";
 import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { collectContentAssets, isDraftAsset, loadSection, normalizeContentSources, } from "./content.js";
+import { collectContentAssets, isDraftAsset, loadSection, localizedItems, normalizeContentSources, treeItems, } from "./content.js";
 import { aboutPage, agentMarkdown, DEFAULT_THEME_STYLESHEET, homePage, listPage, llmFullText, llmText, notFoundPage, postPage, skillPage, skillsIndexPage, thoughtPage, } from "./site.js";
 import { loadSkills } from "./skills.js";
+import { contentRoute, reportedPath, translationReport } from "./translations.js";
 import { sitePageFile, sitePageMarkdownFile } from "./pages.js";
 import { publishSite, validateBuildDestination, validateOutputDirectory } from "./output.js";
 export { sitePageMarkdownFile } from "./pages.js";
+/** Validate the origin of `site.url` and store it without a trailing slash. */
+function resolveSiteUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`site.url must be an origin such as https://example.com: ${value}`);
+    }
+    if ((url.protocol !== "https:" && url.protocol !== "http:") ||
+        url.pathname !== "/" ||
+        url.search !== "" ||
+        url.hash !== "" ||
+        url.username !== "" ||
+        url.password !== "" ||
+        value.includes("#") ||
+        value.includes("?")) {
+        throw new Error(`site.url must be an origin without a path, such as https://example.com: ${value}`);
+    }
+    return url.origin;
+}
+function validateTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat("en", { timeZone });
+    }
+    catch {
+        throw new Error(`site.timeZone must be an IANA time zone such as Asia/Shanghai: ${timeZone}`);
+    }
+    return timeZone;
+}
 /** Define a site config in the app package without taking on the build pipeline. */
 export function meowSite(config = {}) {
     const themeStylesheet = config.themeStylesheet ?? DEFAULT_THEME_STYLESHEET;
@@ -25,15 +58,26 @@ export function meowSite(config = {}) {
         projectRootDirectory: config.projectRootDirectory
             ? resolve(config.projectRootDirectory)
             : undefined,
-        site: { ...DEFAULT_SITE, ...config.site },
+        site: resolveSite(config.site),
         pages: config.pages,
         notFound: config.notFound,
         agentGuide: config.agentGuide,
         mdxComponents: config.mdxComponents ?? {},
         themeStylesheet,
         fonts: config.fonts ?? (config.theme === undefined || config.theme === blogTheme ? blogFonts : []),
+        locales: resolveLocales(config.locales),
+        localesDirectory: resolve(config.localesDirectory ?? "locales"),
     };
 }
+function resolveSite(site) {
+    const resolved = { ...DEFAULT_SITE, ...site };
+    if (site?.url !== undefined)
+        resolved.url = resolveSiteUrl(site.url);
+    else
+        delete resolved.url;
+    resolved.timeZone = validateTimeZone(site?.timeZone ?? DEFAULT_TIME_ZONE);
+    return resolved;
+}
 async function writePage(generatedDirectory, pathname, html) {
     const target = join(generatedDirectory, pathname);
     await mkdir(resolve(target, ".."), { recursive: true });
@@ -95,6 +139,15 @@ async function writeConsumerPages(generatedDirectory, pages) {
 }
 /** Files the build writes itself; a page's Markdown copy may not take their place. */
 const RESERVED_MARKDOWN = new Set(["agents.md"]);
+/** A Markdown copy names its language, and a translation the original it comes from. */
+function pageMarkdownCopy(page) {
+    if (page.locale === undefined)
+        return page.markdown;
+    const markers = [`lang: ${page.locale}`];
+    if (page.original !== undefined)
+        markers.push(`original: ${page.original}`);
+    return `<!-- ${markers.join("; ")} -->\n\n${page.markdown.trim()}\n`;
+}
 /** Each page's Markdown copy, written straight into the output next to its route. */
 async function writeConsumerMarkdown(outputDirectory, pages) {
     for (const page of pages) {
@@ -102,16 +155,17 @@ async function writeConsumerMarkdown(outputDirectory, pages) {
             continue;
         if (RESERVED_MARKDOWN.has(sitePageMarkdownFile(page.path)))
             throw new Error(`Site page Markdown would replace the agent index: ${page.path}`);
-        await writePage(outputDirectory, consumerPageFile(outputDirectory, page.path, sitePageMarkdownFile), page.markdown);
+        await writePage(outputDirectory, consumerPageFile(outputDirectory, page.path, sitePageMarkdownFile), pageMarkdownCopy(page));
     }
 }
-async function writeContentPages(generatedDirectory, posts, thoughts, theme, site, stylesheet) {
+async function writeContentPages(generatedDirectory, posts, thoughts, theme, site, stylesheet, locale) {
     const entrypoints = [];
+    const prefix = locale.segment === "" ? "" : `${locale.segment}/`;
     for (const post of posts) {
-        entrypoints.push(await writePage(generatedDirectory, `posts/${post.slug}/index.html`, postPage(post, posts, thoughts, theme, site, stylesheet)));
+        entrypoints.push(await writePage(generatedDirectory, `${prefix}posts/${post.slug}/index.html`, postPage(post, posts, thoughts, theme, site, stylesheet, locale)));
     }
     for (const thought of thoughts) {
-        entrypoints.push(await writePage(generatedDirectory, `thoughts/${thought.slug}/index.html`, thoughtPage(thought, theme, site, stylesheet)));
+        entrypoints.push(await writePage(generatedDirectory, `${prefix}thoughts/${thought.slug}/index.html`, thoughtPage(thought, theme, site, stylesheet, locale)));
     }
     return entrypoints;
 }
@@ -133,48 +187,195 @@ export async function buildSite(input = {}) {
         await rm(workspace, { recursive: true, force: true });
     }
 }
+/** Collects, per locale, the theme and site sentences that had no translation. */
+function createMissingLog() {
+    const byLocale = new Map();
+    return {
+        record(miss) {
+            const keys = byLocale.get(miss.locale) ?? new Set();
+            keys.add(JSON.stringify([miss.context ?? "", miss.source]));
+            byLocale.set(miss.locale, keys);
+        },
+        report(directory, segmentOf) {
+            for (const [tag, keys] of byLocale) {
+                const path = join(directory, `${segmentOf(tag)}.json`);
+                const local = relative(process.cwd(), path);
+                const file = local.startsWith("..") || isAbsolute(local) ? path : local;
+                console.log(`Locale ${tag}: ${keys.size} messages have no translation and fall back to the source text. Fill ${file}.`);
+            }
+        },
+    };
+}
+/** Top-level names of the output that a locale's URL segment may not take. */
+async function takenSegments(config, pages) {
+    const taken = new Set(RESERVED_SEGMENTS);
+    for (const asset of await collectContentAssets(config.content, { directory: "assets" })) {
+        const segment = firstSegment(asset.relativePath);
+        if (segment)
+            taken.add(segment);
+    }
+    for (const source of normalizeContentSources(config.content)) {
+        const segment = source.slugPrefix ? firstSegment(source.slugPrefix) : undefined;
+        if (segment)
+            taken.add(segment);
+    }
+    for (const page of pages ?? []) {
+        const segment = firstSegment(page.path);
+        if (segment)
+            taken.add(segment);
+    }
+    return taken;
+}
 async function writeSite(config, generatedDirectory) {
-    const [posts, thoughts, skills] = await Promise.all([
-        loadSection(config.content, "post", { components: config.mdxComponents }),
-        loadSection(config.content, "thought", { components: config.mdxComponents }),
+    const timeZone = config.site.timeZone ?? DEFAULT_TIME_ZONE;
+    const locales = config.locales;
+    // A locale suffix is read only for a configured locale, so pairing follows the site's config.
+    const contentLocales = locales
+        ? { source: locales.source, targets: locales.targets.map((target) => target.tag) }
+        : undefined;
+    const [posts, thoughts, skills, catalogs] = await Promise.all([
+        loadSection(config.content, "post", {
+            components: config.mdxComponents,
+            timeZone,
+            locales: contentLocales,
+        }),
+        loadSection(config.content, "thought", {
+            components: config.mdxComponents,
+            timeZone,
+            locales: contentLocales,
+        }),
         config.pages
             ? Promise.resolve([])
             : loadSkills(config.skillsDirectory, {
                 includeProjectSkills: config.includeProjectSkills,
                 projectRootDirectory: config.projectRootDirectory,
             }),
+        config.locales
+            ? loadLocaleCatalogs(config.locales, config.localesDirectory)
+            : Promise.resolve({}),
     ]);
-    const timeline = [...posts, ...thoughts].sort((left, right) => (right.date?.getTime() ?? 0) - (left.date?.getTime() ?? 0));
+    const source = locales?.source ?? "en";
+    // A site that would rather not publish an outdated translation fails the build instead.
+    if (locales?.stale === "fail") {
+        for (const translation of [...posts, ...thoughts].flatMap((item) => item.translations)) {
+            if (translation.translationState !== "stale")
+                continue;
+            throw new Error(`Stale translation ${reportedPath(translation.sourcePath)}: its original changed since it was translated. Revise it and run meowpress locales stamp, or set locales.stale to "notice".`);
+        }
+    }
+    // The source tree lists the originals written in its own language; originals in a target
+    // language live in that language's tree.
+    const sourcePosts = posts.filter((post) => post.locale === source);
+    const sourceThoughts = thoughts.filter((thought) => thought.locale === source);
+    const timeline = [...sourcePosts, ...sourceThoughts].sort((left, right) => (right.date?.getTime() ?? 0) - (left.date?.getTime() ?? 0));
     await mkdir(config.outputDirectory, { recursive: true });
     await mkdir(generatedDirectory, { recursive: true });
-    // A consumer that supplies its own pages owns the whole site map; the package's
-    // own blog routes are not published alongside them.
+    const missing = createMissingLog();
+    const entries = locales
+        ? [
+            { tag: locales.source, segment: "", label: locales.source, isSource: true },
+            ...locales.targets.map((target) => ({
+                tag: target.tag,
+                segment: target.segment,
+                label: target.label,
+                isSource: false,
+            })),
+        ]
+        : undefined;
+    const localeFor = (tag, segment) => createPageLocale({
+        tag,
+        source,
+        segment,
+        catalogs,
+        timeZone,
+        entries,
+        disclosure: locales?.disclosure ?? true,
+        onMissing: (miss) => missing.record(miss),
+    });
+    const rootLocale = localeFor(source, "");
+    const targetLocales = (locales?.targets ?? []).map((target) => ({
+        target,
+        locale: localeFor(target.tag, target.segment),
+    }));
+    /** The locale a consumer page is written in, with the site's catalogs and time zone. */
+    const pageLocaleFor = (tag) => {
+        if (tag === source)
+            return rootLocale;
+        const target = locales?.targets.find((candidate) => candidate.tag === tag);
+        if (!target)
+            throw new Error(`Page locale "${tag}" is not configured: add it to locales.targets or use "${source}".`);
+        return localeFor(target.tag, target.segment);
+    };
+    // A consumer that supplies its own pages owns the whole site map; the package's own blog
+    // routes are not published alongside them.
     const pages = config.pages
         ? await config.pages({
             posts,
             thoughts,
             site: config.site,
             theme: config.theme,
+            locales: config.locales,
+            pageLocale: pageLocaleFor,
         })
         : undefined;
+    // Everything that decides what a locale's URL segment may be is known here.
+    if (locales)
+        assertNoRouteCollisions(locales, await takenSegments(config, pages));
+    // What each target tree shows and publishes. `treeItems` lists an original where no
+    // translation exists; `localizedItems` is the set of pages that tree owns.
+    const targetTrees = targetLocales.map(({ target, locale }) => {
+        const treePosts = treeItems(posts, target.tag, {
+            source,
+            untranslated: locales?.untranslated ?? "link",
+        });
+        const treeThoughts = treeItems(thoughts, target.tag, {
+            source,
+            untranslated: locales?.untranslated ?? "link",
+        });
+        return {
+            target,
+            locale,
+            posts: treePosts,
+            thoughts: treeThoughts,
+            timeline: [...treePosts, ...treeThoughts].sort((left, right) => (right.date?.getTime() ?? 0) - (left.date?.getTime() ?? 0)),
+        };
+    });
     const entrypoints = [];
     if (pages) {
         entrypoints.push(...(await writeConsumerPages(generatedDirectory, pages)));
     }
     else {
         entrypoints.push(...(await Promise.all([
-            writePage(generatedDirectory, "index.html", homePage(timeline, config.theme, config.site, config.themeStylesheet)),
-            writePage(generatedDirectory, "about/index.html", aboutPage(config.theme, config.site, config.themeStylesheet)),
-            writePage(generatedDirectory, "posts/index.html", listPage("post", posts, config.theme, config.site, config.themeStylesheet)),
-            writePage(generatedDirectory, "thoughts/index.html", listPage("thought", thoughts, config.theme, config.site, config.themeStylesheet)),
-            writePage(generatedDirectory, "skills/index.html", skillsIndexPage(skills, config.theme, config.site, config.themeStylesheet)),
-        ])), ...(await writeContentPages(generatedDirectory, posts, thoughts, config.theme, config.site, config.themeStylesheet)));
+            writePage(generatedDirectory, "index.html", homePage(timeline, config.theme, config.site, config.themeStylesheet, rootLocale)),
+            writePage(generatedDirectory, "about/index.html", aboutPage(config.theme, config.site, config.themeStylesheet, rootLocale)),
+            writePage(generatedDirectory, "posts/index.html", listPage("post", sourcePosts, config.theme, config.site, config.themeStylesheet, rootLocale)),
+            writePage(generatedDirectory, "thoughts/index.html", listPage("thought", sourceThoughts, config.theme, config.site, config.themeStylesheet, rootLocale)),
+            writePage(generatedDirectory, "skills/index.html", skillsIndexPage(skills, config.theme, config.site, config.themeStylesheet, rootLocale)),
+        ])), ...(await writeContentPages(generatedDirectory, sourcePosts, sourceThoughts, config.theme, config.site, config.themeStylesheet, rootLocale)));
         if (config.notFound !== false) {
-            entrypoints.push(await writePage(generatedDirectory, "404.html", notFoundPage(config.notFound ?? {}, config.theme, config.site, config.themeStylesheet)));
+            entrypoints.push(await writePage(generatedDirectory, "404.html", notFoundPage(config.notFound ?? {}, config.theme, config.site, config.themeStylesheet, rootLocale, targetLocales.map(({ target, locale }) => ({
+                tag: target.tag,
+                label: target.label,
+                href: localePath(locale, "/"),
+            })))));
         }
         for (const skill of skills) {
             const skillPath = skill.scope === "public" ? `skills/${skill.slug}` : `skills/project/${skill.slug}`;
-            entrypoints.push(await writePage(generatedDirectory, `${skillPath}/index.html`, skillPage(skill, config.theme, config.site, config.themeStylesheet)));
+            entrypoints.push(await writePage(generatedDirectory, `${skillPath}/index.html`, skillPage(skill, config.theme, config.site, config.themeStylesheet, rootLocale)));
+        }
+        // Skills pages exist once, in the source tree. Every target tree has its own home, About,
+        // the two archives, a 404 and a page for each content item written in its language.
+        for (const tree of targetTrees) {
+            const prefix = `${tree.target.segment}/`;
+            entrypoints.push(...(await Promise.all([
+                writePage(generatedDirectory, `${prefix}index.html`, homePage(tree.timeline, config.theme, config.site, config.themeStylesheet, tree.locale)),
+                writePage(generatedDirectory, `${prefix}about/index.html`, aboutPage(config.theme, config.site, config.themeStylesheet, tree.locale)),
+                writePage(generatedDirectory, `${prefix}posts/index.html`, listPage("post", tree.posts, config.theme, config.site, config.themeStylesheet, tree.locale)),
+                writePage(generatedDirectory, `${prefix}thoughts/index.html`, listPage("thought", tree.thoughts, config.theme, config.site, config.themeStylesheet, tree.locale)),
+            ])), ...(await writeContentPages(generatedDirectory, localizedItems(posts, tree.target.tag), localizedItems(thoughts, tree.target.tag), config.theme, config.site, config.themeStylesheet, tree.locale)));
+            if (config.notFound !== false) {
+                entrypoints.push(await writePage(generatedDirectory, `${prefix}404.html`, notFoundPage(config.notFound ?? {}, config.theme, config.site, config.themeStylesheet, tree.locale)));
+            }
         }
     }
     // Font faces come first in the one theme stylesheet; the bundled stylesheet sits at the output
@@ -186,16 +387,57 @@ async function writeSite(config, generatedDirectory) {
     if (pages)
         await writeConsumerMarkdown(config.outputDirectory, pages);
     await writeAssets(config.outputDirectory, config.content, "posts/assets");
-    const full = pages ? llmFullText(config.site, pages, config.agentGuide) : undefined;
-    await Promise.all([
-        writeFile(join(config.outputDirectory, "llm.txt"), llmText(posts, thoughts, config.site, pages, config.agentGuide), "utf8"),
-        writeFile(join(config.outputDirectory, "llms.txt"), llmText(posts, thoughts, config.site, pages, config.agentGuide), "utf8"),
-        ...(full === undefined
-            ? []
-            : [writeFile(join(config.outputDirectory, "llms-full.txt"), full, "utf8")]),
-        writeFile(join(config.outputDirectory, "agents.md"), agentMarkdown(posts, thoughts, config.site, pages, config.content.some((source) => typeof source !== "string" &&
-            (source.postsDirectory !== undefined || source.thoughtsDirectory !== undefined))), "utf8"),
-    ]);
+    const full = pages ? llmFullText(config.site, pages, config.agentGuide, rootLocale) : undefined;
+    const mappedSections = config.content.some((input) => typeof input !== "string" &&
+        (input.postsDirectory !== undefined || input.thoughtsDirectory !== undefined));
+    const indexes = [
+        ["llm.txt", llmText(posts, thoughts, config.site, pages, config.agentGuide, rootLocale)],
+        ["llms.txt", llmText(posts, thoughts, config.site, pages, config.agentGuide, rootLocale)],
+        ...(full === undefined ? [] : [["llms-full.txt", full]]),
+        ["agents.md", agentMarkdown(posts, thoughts, config.site, pages, mappedSections, rootLocale)],
+    ];
+    // A target locale gets its own agent indexes next to the pages it publishes. A consumer that
+    // owns the site map owns its indexes too, so no locale tree is written for it.
+    if (!pages) {
+        for (const tree of targetTrees) {
+            indexes.push([
+                `${tree.target.segment}/llm.txt`,
+                llmText(tree.posts, tree.thoughts, config.site, undefined, config.agentGuide, tree.locale),
+            ], [
+                `${tree.target.segment}/llms.txt`,
+                llmText(tree.posts, tree.thoughts, config.site, undefined, config.agentGuide, tree.locale),
+            ], [
+                `${tree.target.segment}/agents.md`,
+                agentMarkdown(tree.posts, tree.thoughts, config.site, undefined, mappedSections, tree.locale),
+            ]);
+        }
+    }
+    await Promise.all(indexes.map(([path, text]) => writeFile(join(config.outputDirectory, path), text, "utf8")));
+    // The manifest is published only when locales are configured: it is the same work list the
+    // `locales` command prints, for an agent that reads the site instead of its source.
+    if (locales) {
+        const report = translationReport({
+            locales,
+            catalogs,
+            site: config.site,
+            notFound: config.notFound,
+            posts,
+            thoughts,
+            pages,
+        });
+        await writeFile(join(config.outputDirectory, "translations.json"), `${JSON.stringify(report, null, 2)}\n`, "utf8");
+        if (!config.site.url && locales.targets.length > 0)
+            console.log("Site url is not set, so pages carry no alternate or canonical links. Set site.url to the public origin.");
+    }
+    // A file that used to carry its locale in its slug now reads it as a suffix; say which URL
+    // changed rather than leaving it to be discovered.
+    const allItems = [...posts, ...thoughts].flatMap((item) => [item, ...item.translations]);
+    for (const item of allItems) {
+        if (item.previousSlug === undefined)
+            continue;
+        console.log(`Locale ${item.locale}: ${reportedPath(item.sourcePath)} publishes at ${contentRoute(item.kind, item.slug, item.locale, source)}; the file name used to make /${item.kind}s/${item.previousSlug}/.`);
+    }
+    missing.report(config.localesDirectory, (tag) => localeSegment(tag));
     return pages
         ? `${posts.length} content items and ${pages.length} site pages`
         : `${posts.length} posts and ${thoughts.length} thoughts`;