@escape-game-over/atlas 0.1.112 → 0.1.113

package/README.md

@@ -58,40 +58,58 @@ Linking to a page the active deployment switched off is a compile error, not a
 
 **2. A deployment is an overlay, not a fork.**
 
-One file per deployment, saying only what differs:
+A few files per deployment, saying only what differs. Its copy first, the
+languages it publishes and what it rewords or adds:
 
 ```ts
-export const { project, redirects } = atlas.project(
-    defaultMessages,
-    defaultRoutes,
-    {
-        url: "https://acme.example",
-        siteName: "Acme Rome",
-        icon,
-        themeColor: "#1d51e0",
-
-        enabledLocales: ["el-GR", "en-US"],
-        overrideRouting: { defaultLocale: "el-GR", prefixDefaultLocale: true },
-        formats: {
-            clock: { "el-GR": "h23", "en-US": "h12" }, // how each language prints times
-            prices: { decimals: "always" }, // "18,00 €", each page in its own locale
+// projects/rome/messages.ts
+export const messages = atlas.catalog(defaultMessages, {
+    locales: ["el-GR", "en-US"],
+    override: {
+        // Greek only — the English copy still falls through to the default catalog.
+        "home.hero.body": { "el-GR": "Η {company} κρατά το απόθεμα…" },
+    },
+    add: {
+        // Copy only this deployment has, in every language it publishes.
+        "venue.parking": {
+            "el-GR": "Πάρκινγκ στη γωνία",
+            "en-US": "Parking round the corner",
         },
+    },
+});
+```
 
-        overrideMessages: {
-            // Greek only — the English copy still falls through to the default catalog.
-            "home.hero.body": { "el-GR": "Η {company} κρατά το απόθεμα…" },
-        },
-        overrideRoutes: {
-            careers: { enabled: true }, // opt into a page
-            contact: { slugByLocale: { "el-GR": "epikoinoniste-mazi-mas" } }, // retranslate a URL
-        },
-    }
-);
+Then the project, beside it:
+
+```ts
+// projects/rome/project.ts
+export const { project, redirects } = atlas.project(messages, defaultRoutes, {
+    url: "https://acme.example",
+    siteName: "Acme Rome",
+    icon,
+    themeColor: "#1d51e0",
+
+    overrideRouting: { defaultLocale: "el-GR", prefixDefaultLocale: true },
+    formats: {
+        clock: { "el-GR": "h23", "en-US": "h12" }, // how each language prints times
+        prices: { decimals: "always" }, // "18,00 €", each page in its own locale
+    },
+
+    overrideRoutes: {
+        careers: { enabled: true }, // opt into a page
+        contact: { slugByLocale: { "el-GR": "epikoinoniste-mazi-mas" } }, // retranslate a URL
+    },
+});
 ```
 
 Every field is named for what it _does_ to the defaults, so a project file can
-never be mistaken for the whole truth: `enabledLocales` picks from what the site
-declares, and every `override*` is a patch over it.
+never be mistaken for the whole truth: `locales` picks from what the site
+declares, and `override` and every `override*` is a patch over it.
+
+The copy comes first so a deployment's other files can name its messages by
+key. Anything declared before the project, its venues or its settings, types a
+message as `CatalogKey<typeof messages>`: the default catalog's keys and the
+deployment's own, exactly the ones `t()` takes. A typo fails on its line.
 
 ## The four steps
 
@@ -106,11 +124,12 @@ export const atlas = defineSite({ locales: {...}, defaultRouting: {...} })
 export const baseMessages = atlas.messages({...})
 export const baseRoutes   = atlas.routes({...})
 
-// 3. one deployment, and its redirects, typed against what it builds
-export const { project, redirects } = atlas.project(baseMessages, baseRoutes, {...})
+// 3. one deployment's copy, then the deployment and its redirects
+export const messages = atlas.catalog(baseMessages, { locales: [...], override: {...} })
+export const { project, redirects } = atlas.project(messages, baseRoutes, {...})
 
-// 4. the API the pages use
-export const site = atlas.site(baseMessages, baseRoutes, project)
+// 4. the API the pages use: the deployment's catalog, the routes, the deployment
+export const site = atlas.site(messages, baseRoutes, project)
 ```
 
 A site that publishes one language under several regions writes the words once:
@@ -246,7 +265,7 @@ regression-tested by an `@ts-expect-error` suite.
 | A page with no share image, alt text, description or `robots` directives        | error — none of them have a default          |
 | A `robots` directive that is not a real one                                     | error — the vocabulary is a union            |
 | A project `url` that is not `https://`, or ends in a slash                      | error                                        |
-| `defaultLocale` not among the project's `enabledLocales`                        | error                                        |
+| `defaultLocale` not among the locales the project's catalog publishes           | error                                        |
 | A `formats.clock` leaving out a published locale, or naming an unpublished one  | error                                        |
 | `site.clockFor` on a project that declares no clock                             | throws, naming the project                   |
 | `site.priceFormatFor` on a project that declares no price format                | throws, naming the project                   |

package/docs/checks.md

@@ -37,20 +37,20 @@ conditional's result, but goes structural — `Property '__X__' is missing` —
 it is an annotation, and there the property name is the only part the reader
 sees.
 
-| Compile error                                                                             | Build-time throw                                                        |
-| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| unknown message key, or an override dropping a `{placeholder}`                            | two routes resolving to the same URL                                    |
-| a message the project declared mandatory and never wrote (`CatalogCovers`)                |                                                                         |
-| copy or a locale label written for a locale outside `enabledLocales`                      |                                                                         |
-| a `formats.clock` leaving out a published locale, or naming one outside `enabledLocales`  | the same, for a project that was not type-checked first                 |
-| a `formats.prices.locale` the project does not publish                                    | the same, for a project that was not type-checked first                 |
-| a slug whose translation sits at a different depth, in the registry or across the overlay | the same, when a slug is not a literal (computed, or from an env var)   |
-| unknown route id, or a locale the site does not ship                                      | a locale published twice                                                |
-| a malformed language tag (`en_US`, `en-us`, `EN-US`, bare `en`)                           | an icon that is not square, a multiple of 48, and PNG                   |
-| `defaultLocale` outside `locales`; unknown top-level field                                | a `url` that is not `https://` or ends in `/`, when it is not a literal |
-| a `url` literal that is not `https://` or ends in `/`                                     |                                                                         |
-| a `lastmod` that is not a `YYYY-MM-DD` calendar date                                      |                                                                         |
-| config for a route this project does not build, or missing for one it does (`PerRoute`)   |                                                                         |
+| Compile error                                                                                | Build-time throw                                                        |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| unknown message key, or an override dropping a `{placeholder}`                               | two routes resolving to the same URL                                    |
+| a message the project declared mandatory and never wrote (`CatalogCovers`)                   |                                                                         |
+| copy or a locale label written for a locale its catalog does not publish                     |                                                                         |
+| a `formats.clock` leaving out a published locale, or naming one its catalog does not publish | the same, for a project that was not type-checked first                 |
+| a `formats.prices.locale` the project does not publish                                       | the same, for a project that was not type-checked first                 |
+| a slug whose translation sits at a different depth, in the registry or across the overlay    | the same, when a slug is not a literal (computed, or from an env var)   |
+| unknown route id, or a locale the site does not ship                                         | a locale published twice                                                |
+| a malformed language tag (`en_US`, `en-us`, `EN-US`, bare `en`)                              | an icon that is not square, a multiple of 48, and PNG                   |
+| `defaultLocale` outside `locales`; unknown top-level field                                   | a `url` that is not `https://` or ends in `/`, when it is not a literal |
+| a `url` literal that is not `https://` or ends in `/`                                        |                                                                         |
+| a `lastmod` that is not a `YYYY-MM-DD` calendar date                                         |                                                                         |
+| config for a route this project does not build, or missing for one it does (`PerRoute`)      |                                                                         |
 
 The runtime checks are the ones types cannot see: facts about a _file_ (an icon's
 real dimensions), facts only known after merging (URL collisions), or a value

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.112",
+    "version": "0.1.113",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/config.ts

@@ -195,7 +195,7 @@ export interface LocaleNotDeclared<L extends string> {
 
 /** Editor-facing error for anything written for a locale a project does not ship. */
 export interface LocaleNotEnabled<L extends string> {
-    readonly __LOCALE_NOT_ENABLED__: `locale "${L}" is not among this project's enabledLocales, so anything written for it would never be built`;
+    readonly __LOCALE_NOT_ENABLED__: `locale "${L}" is not among the locales this project's catalog publishes, so anything written for it would never be built`;
 }
 
 /**

package/src/i18n/catalog.ts

@@ -0,0 +1,149 @@
+import type {
+    LocaleNotEnabled,
+    LocalesOf,
+    SiteConfigShape,
+} from "../config.ts";
+import type { NoExcessKeys, StringKeys } from "../types.ts";
+import type {
+    BaseCatalog,
+    OverrideCatalog,
+    ValidateAdditions,
+    ValidateOverrideCatalog,
+} from "./define.ts";
+
+/**
+ * One project's copy: the site's catalog, the locales the project publishes,
+ * and what it rewords or adds.
+ *
+ * Built before the project, and from nothing but copy, so the project's other
+ * files (its settings, its venues' data) can name a message by its exact key
+ * with `CatalogKey<typeof catalog>`. Were the copy declared inside the project,
+ * as it once was, a file the project is built from could only name keys as a
+ * string pattern: reaching the project's keys from there is a cycle.
+ */
+export interface ProjectCatalog<Base, Published extends string, Override, Add> {
+    readonly base: Base;
+    /** The locales the project publishes, in the order it lists them. */
+    readonly locales: readonly Published[];
+    /** Rewordings of the base catalog's messages. */
+    readonly override: Override;
+    /** Messages only this project has. */
+    readonly add: Add;
+}
+
+/**
+ * Every message key a project's copy has: the base catalog's and its own.
+ *
+ * What a site built from the project translates, so a key typed with it is
+ * one `t()` takes as it is.
+ */
+export type CatalogKey<C> =
+    C extends ProjectCatalog<infer Base, string, unknown, infer Add>
+        ? StringKeys<Base> | StringKeys<Add>
+        : never;
+
+/** The messages a site built from the catalog reads: the base's and its own. */
+export type MessagesOf<C> =
+    C extends ProjectCatalog<infer Base, string, unknown, infer Add>
+        ? Base & Add
+        : never;
+
+/**
+ * What `override` may hold, as the editor offers it: the base catalog's keys,
+ * each written for the locales the project publishes. A key or a locale beyond
+ * these is named by `OverrideChecks`.
+ */
+export type OverrideEntries<Base, Published extends string> = {
+    readonly [K in StringKeys<Base>]?: Readonly<
+        Partial<Record<Published, string>>
+    >;
+};
+
+/** What `add` may hold, as the editor offers it: new keys, published locales. */
+export type AddedEntries<Published extends string> = Readonly<
+    Record<string, Readonly<Partial<Record<Published, string>>>>
+>;
+
+/** The locales a catalog publishes. */
+export type PublishedOf<C> =
+    C extends ProjectCatalog<unknown, infer Published, unknown, unknown>
+        ? Published
+        : never;
+
+/**
+ * What `override` must be: keys the base catalog declares, each written only
+ * for locales the project publishes. Copy for a locale it does not publish is
+ * never built, so it is always a mistake: a locale removed from the list, or a
+ * project copied from another.
+ */
+export type OverrideChecks<Base, Published extends string, O> = NoExcessKeys<
+    O,
+    StringKeys<Base>
+> & {
+    readonly [K in StringKeys<O>]: {
+        readonly [Locale in StringKeys<O[K]>]: Locale extends Published
+            ? O[K][Locale]
+            : LocaleNotEnabled<Locale>;
+    };
+};
+
+/**
+ * Declares one project's copy, validated against the base catalog.
+ *
+ * Enforced at compile time, each on the line that is wrong:
+ *  - `locales` are ones the site ships;
+ *  - `override` keys exist in the base catalog, keep its `{placeholders}` and
+ *    `[marks]`, and are written only for published locales;
+ *  - `add` keys are new to the base catalog, written for exactly the published
+ *    locales, with the same `{placeholders}` and `[marks]` in each.
+ */
+export function defineCatalog<
+    const C extends SiteConfigShape,
+    const Base extends BaseCatalog<LocalesOf<C>>,
+    const Published extends LocalesOf<C>,
+    const Override extends OverrideEntries<Base, Published> &
+        OverrideChecks<Base, Published, Override>,
+    const Add extends AddedEntries<Published> = Record<never, never>,
+>(
+    // Read for its type only: it is how the site's locales are inferred.
+    _config: C,
+    base: Base,
+    // The whole-object validators sit here rather than in the constraints, so
+    // a mistake is reported on its own line instead of at this call.
+    own: {
+        readonly locales: readonly Published[];
+        readonly override: Override &
+            ValidateOverrideCatalog<Override, Base, LocalesOf<C>>;
+        readonly add?: Add & ValidateAdditions<Add, Base, Published>;
+    }
+): ProjectCatalog<Base, Published, Override, Add> {
+    // Checked at runtime as well as in the type: an Astro config is evaluated
+    // before the type check runs, so the error has to be readable from here.
+    if (own.override === undefined) {
+        throw new Error(
+            "A catalog declares no override. It is required even when nothing is reworded — write `override: {}`, which tells a reader the shared copy is used as it is."
+        );
+    }
+    const add: OverrideCatalog<Published> = own.add ?? {};
+    for (const [key, entry] of Object.entries(add)) {
+        if (key in base) {
+            throw new Error(
+                `add: "${key}" is already in the base catalog. Reword it in override instead.`
+            );
+        }
+        const missing = own.locales.filter(
+            (locale) => typeof entry[locale] !== "string"
+        );
+        if (missing.length > 0) {
+            throw new Error(
+                `add: "${key}" has no ${missing.join(", ")}. A message a project adds is written for every locale it publishes.`
+            );
+        }
+    }
+    return {
+        base,
+        locales: own.locales,
+        override: own.override,
+        add: add as Add,
+    };
+}

package/src/i18n/define.ts

@@ -103,7 +103,7 @@ export function defineMessages<
     return catalog;
 }
 
-/** What `defineProject` checks an `overrideMessages` against: placeholders and locales. */
+/** What `defineCatalog` checks an `override` against: placeholders and locales. */
 export type ValidateOverrideCatalog<
     T,
     Base,
@@ -139,12 +139,12 @@ export type MessageOverrides<Catalog, L extends string> = {
 };
 
 /**
- * What `defineProject` checks an `addMessages` against: each key new to the
+ * What `defineCatalog` checks an `add` against: each key new to the
  * base catalog, written for exactly the locales the project publishes, with
  * the same `{placeholders}` and `[marks]` in each.
  *
  * New only, because a key the base already has is copy every project shares,
- * and rewording it is what `overrideMessages` is for — with its own check that
+ * and rewording it is what `override` is for — with its own check that
  * the placeholders survive. An addition shadowing a base key would get round
  * that check, and two fields could then say different things about one key.
  */
@@ -182,7 +182,7 @@ export function mergeCatalog<L extends string>(
         // Astro config is evaluated before the type check, so say it plainly.
         if (key in merged) {
             throw new Error(
-                `addMessages: "${key}" is already in the default catalog. Reword it in overrideMessages instead.`
+                `add: "${key}" is already in the default catalog. Reword it in override instead.`
             );
         }
         merged[key] = { ...entry } as Record<string, string>;

package/src/i18n/placeholders.ts

@@ -114,7 +114,7 @@ export interface PlaceholderMismatch<Key extends string, L extends string> {
 
 /** Editor-facing error when a project adds a message the base already has. */
 export interface AddedMessageExists<Key extends string> {
-    readonly __ADDED_MESSAGE_EXISTS__: `Message "${Key}" is already in the default catalog: reword it in overrideMessages instead of adding it`;
+    readonly __ADDED_MESSAGE_EXISTS__: `Message "${Key}" is already in the default catalog: reword it in override instead of adding it`;
 }
 
 /** Editor-facing error when an override drops or invents one. */

package/src/index.ts

@@ -7,8 +7,9 @@
  * export const atlas = defineSite({ locales: {...}, defaultRouting: {...} })  // site.config.ts
  * export const defaultMessages = atlas.messages({...})                        // messages.ts
  * export const defaultRoutes = atlas.routes({...})                            // routes.ts
- * export const { project, redirects } = atlas.project(defaultMessages, defaultRoutes, {...}) // projects/<name>/project.ts
- * export const site = atlas.site(defaultMessages, defaultRoutes, project)     // site.ts
+ * export const messages = atlas.catalog(defaultMessages, {...})             // projects/<name>/messages.ts
+ * export const { project, redirects } = atlas.project(messages, defaultRoutes, {...}) // projects/<name>/project.ts
+ * export const site = atlas.site(messages, defaultRoutes, project)            // site.ts
  * ```
  */
 
@@ -176,6 +177,12 @@ export {
     type Weekday,
     type WeeklyHours,
 } from "./hours.ts";
+export type {
+    CatalogKey,
+    MessagesOf,
+    ProjectCatalog,
+    PublishedOf,
+} from "./i18n/catalog.ts";
 export type {
     BaseCatalog,
     CatalogCovers,
@@ -277,7 +284,6 @@ export {
     type PriceFormat,
 } from "./price-format.ts";
 export type {
-    AddedCatalog,
     DefinedProject,
     ProjectInput,
     ProjectRouteId,

package/src/project.ts

@@ -8,12 +8,8 @@ import type {
 } from "./config.ts";
 import type { Fonts } from "./fonts.ts";
 import type { HourCycle } from "./hours.ts";
-import type {
-    BaseCatalog,
-    OverrideCatalog,
-    ValidateAdditions,
-    ValidateOverrideCatalog,
-} from "./i18n/define.ts";
+import type { ProjectCatalog, PublishedOf } from "./i18n/catalog.ts";
+import type { BaseCatalog, OverrideCatalog } from "./i18n/define.ts";
 import type { ImageAsset } from "./image.ts";
 import type { SiteVerification, ThemeColor } from "./meta/index.ts";
 import type { PriceFormat } from "./price-format.ts";
@@ -46,7 +42,7 @@ export interface ProjectFormats<L extends string> {
      * The clock each published language prints times on: `"h23"` for 18:00,
      * `"h12"` for 6:00 PM. Read back with `site.clockFor(locale)`.
      *
-     * One entry for every locale in `enabledLocales`, and none for any other,
+     * One entry for every locale its catalog publishes, and none for any other,
      * so what each page prints is written down beside the languages that print
      * it: a bilingual Canadian site reads `{ "en-CA": "h12", "fr-CA": "h23" }`.
      * Not taken from the locale's own default (`Intl`'s) on purpose: a site may
@@ -121,14 +117,6 @@ export interface ProjectInput<L extends string, Routes> {
     readonly themeColor: ThemeColor;
     /** Which colour schemes the pages support, e.g. `"light"`, `"dark light"`. */
     readonly colorScheme?: string;
-    /**
-     * Which of the site's locales this project publishes.
-     *
-     * A selection, not an override: the site config declares which languages
-     * exist at all, and a project picks from them. Naming one it does not
-     * declare is a compile error.
-     */
-    readonly enabledLocales: readonly L[];
     /**
      * How this site writes what it formats: times and prices. Each format is
      * optional, and its reader refuses to answer for a project that declares
@@ -150,41 +138,13 @@ export interface ProjectInput<L extends string, Routes> {
     /** Adds to the site's `defaultFonts`, or replaces one by key. */
     readonly overrideFonts?: Fonts;
     /**
-     * Copy overrides: any subset of keys, any subset of locales.
+     * Slug retranslations and page on/off switches.
      *
      * **Required, and `{}` is the answer for a deployment that overrides
-     * nothing.** Unlike the two fields above, which are optional.
-     *
-     * The reason is not that an absent overlay and an empty one read
-     * differently — they do, and that argument would make all four of these
-     * required. It is that these two are what the type machinery *computes
-     * from*: the route ids a project builds, the message keys it may override,
-     * and the locales each may be written for are all read off these fields,
-     * at seven sites in this file. Optional means `undefined` flowing into
-     * every one of them, `NonNullable<>` at each — see `overrideRouting` above,
-     * the one optional field that is read, for what that looks like — and an
+     * nothing.** The route ids a project builds are computed from it, and an
+     * optional field would mean `undefined` flowing into each of them and an
      * inference that widens where it should narrow.
-     *
-     * `{}` costing two characters is the price of the ids downstream being
-     * exact. It also happens to read as a statement, which is a bonus rather
-     * than the argument.
      */
-    readonly overrideMessages: OverrideCatalog<L>;
-    /**
-     * Copy only this project has: keys the default catalog does not declare,
-     * each written for every locale the project publishes and no others.
-     *
-     * For what one deployment says and no other does — a venue's own FAQ, a
-     * house rule — so it goes through `translate` and `rich` like any message,
-     * marks and placeholders included, without the shared catalog carrying it
-     * in languages the venue never publishes. A key the default catalog
-     * already has is refused: reword it in `overrideMessages`.
-     *
-     * Optional, unlike `overrideMessages`: nothing downstream is computed from
-     * it except the catalog's keys, which an absent field leaves as they are.
-     */
-    readonly addMessages?: OverrideCatalog<L>;
-    /** Slug retranslations and page on/off switches. See `overrideMessages`. */
     readonly overrideRoutes: RouteOverrides<Routes, L>;
 }
 
@@ -217,60 +177,64 @@ export type ProjectRouteId<
 export interface DefinedProject<
     Routes extends EnabledFlagSource,
     T extends ProjectInput<string, Routes>,
+    Published extends string,
 > {
     readonly project: T;
     /** Rules for this project's old URLs, checked against what it builds. */
     readonly redirects: <
         const Rules extends readonly RedirectRule<
             ProjectRouteId<Routes, T>,
-            T["enabledLocales"][number]
+            Published
         >[],
     >(
         rules: Rules & ValidateRedirectTargets<Rules>
-    ) => ProjectRedirects<
-        ProjectRouteId<Routes, T>,
-        T["enabledLocales"][number]
-    >;
+    ) => ProjectRedirects<ProjectRouteId<Routes, T>, Published>;
 }
 
 /**
  * A project's `redirects`. The one place a rule list is branded as checked.
  *
- * Takes the routes and the project only for their types; the rules come back
- * as they went in.
+ * Takes the routes, the project and its catalog only for their types; the
+ * rules come back as they went in.
  */
 export function bindRedirects<
     Routes extends EnabledFlagSource,
     T extends ProjectInput<string, Routes>,
->(_routes: Routes, _project: T): DefinedProject<Routes, T>["redirects"] {
+    Published extends string,
+>(
+    _routes: Routes,
+    _project: T,
+    _catalog: ProjectCatalog<unknown, Published, unknown, unknown>
+): DefinedProject<Routes, T, Published>["redirects"] {
     return (rules) => rules as never;
 }
 
 /**
- * Declares one deployment, validated against the site config and base data.
+ * Declares one deployment, validated against the site config, its catalog
+ * and the routes.
  *
  * Everything is inferred from the values passed in, so a project file writes no
  * type arguments at all.
  *
  * Enforced at compile time:
  *  - `url` must not end with a slash;
- *  - `overrideMessages` keys must exist in the default catalog, and must keep
- *    the default message's `{placeholders}`;
  *  - `overrideRoutes` keys must be real route ids;
  *  - unknown top-level fields are rejected, so a typo cannot sit there unread;
- *  - locales named anywhere must be ones the site ships and this project enabled.
+ *  - locales named anywhere must be ones its catalog publishes.
+ *
+ * Its copy is checked by `atlas.catalog()`, before the project exists.
  */
 /** Everything a project file must satisfy; see `defineSite`. */
 export type ProjectChecks<
     L extends string,
-    Catalog,
+    Published extends string,
     Routes,
     T extends ProjectInput<L, Routes>,
 > = NoExcessKeys<T, keyof ProjectInput<L, Routes>> & {
     readonly url: ValidSiteUrl<T["url"]>;
     readonly overrideRouting?: {
-        readonly defaultLocale?: T["enabledLocales"][number];
-        // Against `enabledLocales` rather than the site's list: a
+        readonly defaultLocale?: Published;
+        // Against the published locales rather than the site's list: a
         // segment spelled for a language this deployment does not
         // publish is a word that appears in no URL it builds. Mapped
         // over the keys written, for the reason `overrideLocaleMeta`
@@ -278,26 +242,7 @@ export type ProjectChecks<
         readonly pageSegmentByLocale?: {
             readonly [K in StringKeys<
                 NonNullable<T["overrideRouting"]>["pageSegmentByLocale"]
-            >]: K extends T["enabledLocales"][number]
-                ? string
-                : LocaleNotEnabled<K>;
-        };
-    };
-    // Two separate checks on the same field: the keys must be messages
-    // the default catalog declares, and the locales inside each must be
-    // ones this project publishes. Copy written for a locale left out of
-    // `enabledLocales` is never built, so it is always a mistake — a
-    // locale removed from the list, or a project copied from another.
-    readonly overrideMessages: NoExcessKeys<
-        T["overrideMessages"],
-        StringKeys<Catalog>
-    > & {
-        readonly [K in StringKeys<T["overrideMessages"]>]: {
-            readonly [L in StringKeys<
-                T["overrideMessages"][K]
-            >]: L extends T["enabledLocales"][number]
-                ? T["overrideMessages"][K][L]
-                : LocaleNotEnabled<L>;
+            >]: K extends Published ? string : LocaleNotEnabled<K>;
         };
     };
     readonly overrideRoutes: NoExcessKeys<
@@ -310,9 +255,7 @@ export type ProjectChecks<
     // part of `T` and there is no fresh object for excess-property
     // checking to fire on.
     readonly overrideLocaleMeta?: {
-        readonly [K in StringKeys<
-            T["overrideLocaleMeta"]
-        >]: K extends T["enabledLocales"][number]
+        readonly [K in StringKeys<T["overrideLocaleMeta"]>]: K extends Published
             ? NoExcessKeys<T["overrideLocaleMeta"][K], keyof LocaleMetaOverride>
             : LocaleNotEnabled<K>;
     };
@@ -324,13 +267,11 @@ export type ProjectChecks<
         readonly clock?: {
             readonly [K in StringKeys<
                 NonNullable<T["formats"]>["clock"]
-            >]: K extends T["enabledLocales"][number]
-                ? HourCycle
-                : LocaleNotEnabled<K>;
+            >]: K extends Published ? HourCycle : LocaleNotEnabled<K>;
         };
         // Its locale too must be one this project publishes.
         readonly prices?: PriceFormat & {
-            readonly locale?: PriceLocaleCheck<T>;
+            readonly locale?: PriceLocaleCheck<T, Published>;
         };
     };
 };
@@ -343,122 +284,99 @@ type PriceLocaleOf<T> = T extends {
     : never;
 
 /** The price locale, if the project publishes it; else an error naming it. */
-type PriceLocaleCheck<T> = T extends {
-    readonly enabledLocales: readonly (infer Published)[];
-}
-    ? PriceLocaleOf<T> extends Published
+type PriceLocaleCheck<T, Published extends string> =
+    PriceLocaleOf<T> extends Published
         ? PriceLocaleOf<T>
-        : LocaleNotEnabled<PriceLocaleOf<T>>
-    : never;
+        : LocaleNotEnabled<PriceLocaleOf<T>>;
 
 /** The same checks that map the whole override objects, in parameter position. */
 export type ProjectOverrideChecks<
-    L extends string,
-    Catalog,
+    Published extends string,
     Routes,
-    T extends ProjectInput<L, Routes>,
+    T extends ProjectInput<string, Routes>,
 > = {
-    readonly overrideMessages: ValidateOverrideCatalog<
-        T["overrideMessages"],
-        Catalog,
-        L
-    >;
     readonly overrideRoutes: ValidateOverrideSlugDepth<
         Routes,
         T["overrideRoutes"]
     >;
-} & AdditionsCheck<Catalog, T> &
-    ClockCheck<T>;
-
-/** A project's own messages, checked like the catalog's: when it adds any. */
-type AdditionsCheck<
-    Catalog,
-    T extends ProjectInput<string, unknown>,
-> = T extends { readonly addMessages: infer A }
-    ? {
-          readonly addMessages: ValidateAdditions<
-              A,
-              Catalog,
-              T["enabledLocales"][number]
-          >;
-      }
-    : unknown;
+} & ClockCheck<T, Published>;
 
 /**
  * A clock, once declared, is declared for every page: a locale left out would
  * have no clock to print its times on.
  */
-type ClockCheck<T extends ProjectInput<string, unknown>> = T extends {
+type ClockCheck<T, Published extends string> = T extends {
     readonly formats: { readonly clock: object };
 }
     ? {
           readonly formats: {
               readonly clock: {
-                  readonly [K in T["enabledLocales"][number]]: HourCycle;
+                  readonly [K in Published]: HourCycle;
               };
           };
       }
     : unknown;
 
-/** A project's own messages, as a catalog: none when it adds none. */
-export type AddedCatalog<P> = P extends { readonly addMessages: infer A }
-    ? A
-    : Record<never, never>;
+/**
+ * The catalog each project was built with, so the site can check it is given
+ * the same one. Weak, so a project nothing holds any more is not kept alive.
+ */
+const builtWith = new WeakMap<object, object>();
+
+/**
+ * Throws if a site is given a catalog other than the one its project was built
+ * with: the project's locale checks were made against that one. A project
+ * assembled by hand, which `defineProject` never saw, has nothing to compare.
+ */
+export function checkProjectCatalog(
+    project: { readonly siteName: string },
+    catalog: object
+): void {
+    const own = builtWith.get(project);
+    if (own !== undefined && own !== catalog) {
+        throw new Error(
+            `Project "${project.siteName}" was built with a different catalog than the one passed to atlas.site(): pass the catalog its project.ts uses.`
+        );
+    }
+}
 
 export function defineProject<
     const C extends SiteConfigShape,
-    const Catalog extends BaseCatalog<LocalesOf<C>>,
+    const Cat extends ProjectCatalog<
+        BaseCatalog<LocalesOf<C>>,
+        LocalesOf<C>,
+        OverrideCatalog<LocalesOf<C>>,
+        OverrideCatalog<LocalesOf<C>>
+    >,
     const Routes extends RouteRegistry<LocalesOf<C>>,
     const T extends ProjectInput<LocalesOf<C>, Routes> &
-        ProjectChecks<LocalesOf<C>, Catalog, Routes, T>,
+        ProjectChecks<LocalesOf<C>, PublishedOf<Cat>, Routes, T>,
 >(
-    // The first three are read for their types: they are how the locale union,
-    // the message keys and the route ids are inferred without type arguments.
+    // Read for its type: it is how the locale union is inferred without type
+    // arguments.
     _config: C,
-    _messages: Catalog,
+    catalog: Cat,
+    // Read for its type: the route ids.
     _routes: Routes,
-    // Both validators sit in parameter position rather than in the constraint
-    // above. They map the *whole* override object, and a whole-object mapped
-    // type in a constraint makes one unrelated mistake fail the argument
-    // outright — TypeScript then reports at this call instead of on the line
-    // that is wrong.
-    project: T & ProjectOverrideChecks<LocalesOf<C>, Catalog, Routes, T>
+    // The whole-object validators sit in parameter position rather than in the
+    // constraint above: in a constraint, one unrelated mistake fails the
+    // argument outright, and TypeScript reports at this call instead of on the
+    // line that is wrong.
+    project: T & ProjectOverrideChecks<PublishedOf<Cat>, Routes, T>
 ): T {
     // Checked at runtime as well as in the type, because the type is not always
     // what fails first. An Astro config is *evaluated* before `astro check`
-    // runs, so a project file missing one of these reaches `mergeCatalog` and
-    // throws there — a stack trace inside lib, naming a variable the reader
-    // never wrote, for a field the compiler would have named precisely.
-    //
-    // Two lines to turn that back into the error it already was.
-    for (const field of ["overrideMessages", "overrideRoutes"] as const) {
-        if (project[field] === undefined) {
-            throw new Error(
-                `Project "${project.siteName}" declares no ${field}. It is required even when nothing is overridden — write \`${field}: {}\`, which is what the type asks for and what tells a reader the shared ${field === "overrideMessages" ? "copy" : "route table"} is used as it is.`
-            );
-        }
-    }
-    // The same two rules the type states, for the same reason: the config is
-    // evaluated before the type check runs.
-    for (const [key, entry] of Object.entries(project.addMessages ?? {})) {
-        if (key in _messages) {
-            throw new Error(
-                `Project "${project.siteName}": addMessages "${key}" is already in the default catalog. Reword it in overrideMessages instead.`
-            );
-        }
-        const missing = project.enabledLocales.filter(
-            (locale) => typeof entry[locale] !== "string"
+    // runs, so a project file missing this reaches the route table and throws
+    // there, far from the field the compiler would have named precisely.
+    if (project.overrideRoutes === undefined) {
+        throw new Error(
+            `Project "${project.siteName}" declares no overrideRoutes. It is required even when nothing is overridden — write \`overrideRoutes: {}\`, which is what the type asks for and what tells a reader the shared route table is used as it is.`
         );
-        if (missing.length > 0) {
-            throw new Error(
-                `Project "${project.siteName}": addMessages "${key}" has no ${missing.join(", ")}. A message a project adds is written for every locale it publishes.`
-            );
-        }
     }
+    const published: readonly string[] = catalog.locales;
     // The clock's rule, for the same reason.
     const clock = project.formats?.clock;
     if (clock !== undefined) {
-        const published: readonly string[] = project.enabledLocales;
         const missing = published.filter((locale) => !(locale in clock));
         if (missing.length > 0) {
             throw new Error(
@@ -476,13 +394,11 @@ export function defineProject<
     }
     // The price locale's rule, for the same reason.
     const priceLocale: string | undefined = project.formats?.prices?.locale;
-    if (
-        priceLocale !== undefined &&
-        !(project.enabledLocales as readonly string[]).includes(priceLocale)
-    ) {
+    if (priceLocale !== undefined && !published.includes(priceLocale)) {
         throw new Error(
             `Project "${project.siteName}": formats.prices.locale names ${priceLocale}, which this project does not publish.`
         );
     }
+    builtWith.set(project, catalog);
     return project;
 }

package/src/site/create.ts

@@ -15,7 +15,12 @@ import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import { mergeFonts } from "../fonts.ts";
 import type { HourCycle } from "../hours.ts";
-import { type BaseCatalog, mergeCatalog } from "../i18n/define.ts";
+import type { MessagesOf, ProjectCatalog } from "../i18n/catalog.ts";
+import {
+    type BaseCatalog,
+    mergeCatalog,
+    type OverrideCatalog,
+} from "../i18n/define.ts";
 import { createTranslateFactory } from "../i18n/translate.ts";
 import type { ImageAsset } from "../image.ts";
 import { buildLlms, type LlmsItem, type LlmsSection } from "../llms.ts";
@@ -25,7 +30,11 @@ import {
     resolveShareImage,
 } from "../meta/index.ts";
 import type { PriceDecimals } from "../price-format.ts";
-import type { AddedCatalog, ProjectInput, ProjectRouteId } from "../project.ts";
+import {
+    checkProjectCatalog,
+    type ProjectInput,
+    type ProjectRouteId,
+} from "../project.ts";
 import {
     buildRedirects,
     type RedirectRule,
@@ -78,47 +87,52 @@ function decorate(path: UrlPath, options: LinkOptions | undefined): UrlPath {
 }
 
 /**
- * Turns a site config, its base data and one project overlay into the API the
- * pages use.
+ * Turns a site config, one project's catalog, the routes and the project into
+ * the API the pages use.
  *
  * This is the only wiring a consuming project writes: the merging, slug
  * fallbacks, URL building, translation and sitemap all come back ready to use.
  */
 export function createSite<
     const C extends SiteConfigShape,
-    const Catalog extends BaseCatalog<LocalesOf<C>>,
-    const Routes extends RouteRegistry<LocalesOf<C>>,
-    // Inferred from `project.enabledLocales` as its own parameter rather than
-    // read back as `P["enabledLocales"][number]`: that indexed access resolves
-    // through the constraint's `readonly L[]` and collapses to `string`, which
-    // silently un-types every locale the API accepts.
+    // The catalog carries the locales the project publishes and its copy.
+    const Cat extends ProjectCatalog<
+        BaseCatalog<LocalesOf<C>>,
+        LocalesOf<C>,
+        OverrideCatalog<LocalesOf<C>>,
+        OverrideCatalog<LocalesOf<C>>
+    >,
+    // Inferred from `catalog.locales` as its own parameter rather than read
+    // back off `Cat`: a type read back is not known to be one of the site's
+    // locales, where a parameter constrained to them is, and an indexed access
+    // through the constraint would collapse to the whole locale universe and
+    // silently un-type every locale the API accepts.
     const Published extends LocalesOf<C>,
+    const Routes extends RouteRegistry<LocalesOf<C>>,
     const P extends ProjectInput<LocalesOf<C>, Routes>,
 >(
     config_: C,
-    messages: Catalog,
+    // `Published` is named in the *parameter*: a type parameter mentioned
+    // nowhere an argument reaches has nothing to infer from and silently falls
+    // back to its constraint.
+    catalog: Cat & { readonly locales: readonly Published[] },
     routes: Routes,
-    // `Published` is named in the *parameter*, not only in `P`'s constraint:
-    // a type parameter mentioned nowhere an argument reaches has nothing to
-    // infer from and silently falls back to its constraint — here the whole
-    // locale universe, which is the bug this was meant to fix.
-    project: P & { readonly enabledLocales: readonly Published[] }
+    project: P
 ): Site<
     Published,
-    Catalog & AddedCatalog<P>,
+    MessagesOf<Cat>,
     ProjectRouteId<Routes, P>,
     SectionPrefixOf<Routes, P["overrideRoutes"]>,
     OrphanSectionPrefixOf<Routes, P["overrideRoutes"]>
 > {
-    // The locales this *project* publishes, not the universe the site config
-    // declares. The runtime has always used the narrow set — `locales` below is
-    // `project.enabledLocales` — but the type used to be the wide one, so
-    // `pathFor("home", "el-GR")` type-checked on a build with no Greek pages and
-    // returned a URL that was never generated.
+    // The locales this *project* publishes, from its catalog, not the
+    // universe the site config declares: `pathFor("home", "el-GR")` must not
+    // type-check on a build with no Greek pages, since it would return a URL
+    // that was never generated.
     type L = Published;
     type RouteId = ProjectRouteId<Routes, P>;
 
-    const locales = project.enabledLocales as readonly L[];
+    const locales = catalog.locales as readonly L[];
     const defaultLocale = (project.overrideRouting?.defaultLocale ??
         config_.defaultRouting.defaultLocale) as L;
     const prefixDefaultLocale =
@@ -126,6 +140,7 @@ export function createSite<
         config_.defaultRouting.prefixDefaultLocale;
 
     // Checks that types cannot express, run once at build time.
+    checkProjectCatalog(project, catalog);
     if (locales.length === 0) {
         throw new Error("A project must publish at least one locale.");
     }
@@ -182,13 +197,13 @@ export function createSite<
     const llmsUrl: HttpsUrl | undefined =
         config_.llms === false ? undefined : joinUrl(siteUrl, `/${llmsName}`);
 
-    // The project's own messages join the catalog here, typed and resolved like
+    // The project's own messages join the base here, typed and resolved like
     // any other: `Full` is what every reader below knows the keys by.
-    type Full = Catalog & AddedCatalog<P>;
-    const catalog = mergeCatalog<L>(
-        messages,
-        project.overrideMessages,
-        project.addMessages
+    type Full = MessagesOf<Cat>;
+    const messages = mergeCatalog<L>(
+        catalog.base,
+        catalog.override,
+        catalog.add
     );
     const translateFactory = createTranslateFactory<Full, L>();
 
@@ -872,7 +887,7 @@ export function createSite<
         translate: <const Values extends string = never>(
             locale: L,
             bind?: { readonly values?: Readonly<Record<Values, string>> }
-        ) => translateFactory<Values>(catalog, locale, bind?.values),
+        ) => translateFactory<Values>(messages, locale, bind?.values),
         rich: <
             const Links extends string = never,
             const Values extends string = never,
@@ -881,7 +896,7 @@ export function createSite<
             bind?: MessageBindings<RouteId, Links, Values>
         ) =>
             createRichText<Full, L, RouteId, Links, Values>({
-                catalog,
+                catalog: messages,
                 locale,
                 link: richLink(locale),
                 origin: siteUrl,
@@ -892,7 +907,7 @@ export function createSite<
             bind?: { readonly values?: Readonly<Record<Values, string>> }
         ) =>
             createPlainText<Full, L, Values>({
-                catalog,
+                catalog: messages,
                 locale,
                 link: richLink(locale),
                 origin: siteUrl,

package/src/site/define.ts

@@ -4,11 +4,22 @@ import {
     type SiteConfigChecks,
     type SiteConfigShape,
 } from "../config.ts";
+import {
+    type AddedEntries,
+    defineCatalog,
+    type OverrideChecks,
+    type OverrideEntries,
+    type ProjectCatalog,
+    type PublishedOf,
+} from "../i18n/catalog.ts";
 import {
     type BaseCatalog,
     defineMessages,
     type NoExtraLocales,
+    type OverrideCatalog,
+    type ValidateAdditions,
     type ValidateBase,
+    type ValidateOverrideCatalog,
 } from "../i18n/define.ts";
 import {
     expandLanguages,
@@ -47,8 +58,9 @@ import { createSite } from "./create.ts";
  * const rooms = atlas.family("rooms", ROOMS, { enabled: true });
  * export const defaultRoutes = atlas.routes({ ...rooms, home: {…} });
  * export const defaultMessages = atlas.messages({…});
- * export const { project, redirects } = atlas.project(defaultMessages, defaultRoutes, {…});
- * export const site = atlas.site(defaultMessages, defaultRoutes, project);
+ * export const messages = atlas.catalog(defaultMessages, { locales: […], override: {…} });
+ * export const { project, redirects } = atlas.project(messages, defaultRoutes, {…});
+ * export const site = atlas.site(messages, defaultRoutes, project);
  * ```
  *
  * Every check each step makes is the same one it makes as a function: a typo'd
@@ -98,41 +110,74 @@ export function defineSite<
             return expandLanguages(Object.keys(config.locales) as L[], texts);
         },
 
-        /** One deployment: what differs from the defaults. */
+        /**
+         * One deployment's copy: the locales it publishes, and what it rewords
+         * or adds. Built before the project, so the project's other files can
+         * name its messages by key: `CatalogKey<typeof catalog>`.
+         */
+        catalog<
+            const Base extends BaseCatalog<L>,
+            const Published extends L,
+            const Override extends OverrideEntries<Base, Published> &
+                OverrideChecks<Base, Published, Override>,
+            const Add extends AddedEntries<Published> = Record<never, never>,
+        >(
+            base: Base,
+            own: {
+                readonly locales: readonly Published[];
+                readonly override: Override &
+                    ValidateOverrideCatalog<Override, Base, L>;
+                readonly add?: Add & ValidateAdditions<Add, Base, Published>;
+            }
+        ): ProjectCatalog<Base, Published, Override, Add> {
+            return defineCatalog(config, base, own as never) as never;
+        },
+
+        /** One deployment: what differs from the defaults, beside its catalog. */
         project<
-            const Catalog extends BaseCatalog<L>,
+            const Cat extends ProjectCatalog<
+                BaseCatalog<L>,
+                L,
+                OverrideCatalog<L>,
+                OverrideCatalog<L>
+            >,
             const Routes extends RouteRegistry<L>,
             const T extends ProjectInput<L, Routes> &
-                ProjectChecks<L, Catalog, Routes, T>,
+                ProjectChecks<L, PublishedOf<Cat>, Routes, T>,
         >(
-            messages: Catalog,
+            catalog: Cat,
             routes: Routes,
-            project: T & ProjectOverrideChecks<L, Catalog, Routes, T>
-        ): DefinedProject<Routes, T> {
+            project: T & ProjectOverrideChecks<PublishedOf<Cat>, Routes, T>
+        ): DefinedProject<Routes, T, PublishedOf<Cat>> {
             const defined = defineProject(
                 config,
-                messages,
+                catalog,
                 routes,
                 project as never
             ) as T;
             return {
                 project: defined,
-                redirects: bindRedirects(routes, defined),
+                redirects: bindRedirects(routes, defined, catalog),
             };
         },
 
-        /** The API every page reads, wired for one project. */
+        /** The API every page reads, wired for one project and its catalog. */
         site<
-            const Catalog extends BaseCatalog<L>,
-            const Routes extends RouteRegistry<L>,
+            const Cat extends ProjectCatalog<
+                BaseCatalog<L>,
+                L,
+                OverrideCatalog<L>,
+                OverrideCatalog<L>
+            >,
             const Published extends L,
+            const Routes extends RouteRegistry<L>,
             const P extends ProjectInput<L, Routes>,
         >(
-            messages: Catalog,
+            catalog: Cat & { readonly locales: readonly Published[] },
             routes: Routes,
-            project: P & { readonly enabledLocales: readonly Published[] }
-        ): ReturnType<typeof createSite<C, Catalog, Routes, Published, P>> {
-            return createSite(config, messages, routes, project);
+            project: P
+        ): ReturnType<typeof createSite<C, Cat, Published, Routes, P>> {
+            return createSite(config, catalog, routes, project);
         },
     };
 }