@escape-game-over/atlas 0.1.83 → 0.1.85

package/README.md

@@ -109,6 +109,10 @@ export const { project, redirects } = atlas.project(baseMessages, baseRoutes, {.
 export const site = atlas.site(baseMessages, baseRoutes, project)
 ```
 
+A site that publishes one language under several regions writes the words once:
+`atlas.perLanguage({ en: "Home", fr: "Accueil" })` fills in `en-GB`, `en-IE` and
+`fr-FR` for one entry of `atlas.messages`, with placeholders still checked.
+
 Step 4 returns `t()`, `rich()`, `plain()`, `pathFor()`, `urlFor()`, `fileUrl()`,
 `localeLinksFor()`, `metaFor()`, `breadcrumbFor()`,
 `getStaticPaths()`, `routes`, `sitemap()`, `robots()` and `llms()` already

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.83",
+    "version": "0.1.85",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -58,11 +58,11 @@
         "vite": ">= 8"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.6.4",
+        "@biomejs/biome": "2.6.5",
         "@types/node": "26.6.6",
-        "@vitest/coverage-istanbul": "5.0.5",
-        "astro": "7.4.4",
+        "@vitest/coverage-istanbul": "5.1.0",
+        "astro": "7.4.5",
         "typescript": "6.0.3",
-        "vitest": "5.0.5"
+        "vitest": "5.1.0"
     }
 }

package/src/i18n/per-language.ts

@@ -0,0 +1,45 @@
+/** `"en"` for `"en-GB"`: everything before the first dash. */
+export type LanguageOf<L extends string> =
+    L extends `${infer Language}-${string}` ? Language : never;
+
+/**
+ * Every locale, holding its language's text.
+ *
+ * Keeps each string's literal type, so a message built this way has its
+ * placeholders checked exactly like one written out by hand.
+ */
+export type PerLanguage<L extends string, T> = {
+    readonly [K in L]: T[LanguageOf<K> & keyof T];
+};
+
+/**
+ * One message, written once per language and filled in for each of its tags.
+ *
+ * For a site that publishes one language under several regions, where `en-GB`
+ * and `en-IE` are different tags for `hreflang` but the same words. Checked here
+ * as well as in the types, because the cast below stops the compiler seeing
+ * this body, and a caller's `as any` would otherwise publish `undefined`.
+ */
+export function expandLanguages<L extends string, T>(
+    locales: readonly L[],
+    texts: T
+): PerLanguage<L, T> {
+    const given = texts as Readonly<Record<string, string>>;
+    const languages = new Set(locales.map((tag) => tag.split("-")[0]));
+    for (const language of Object.keys(given)) {
+        if (!languages.has(language)) {
+            throw new Error(
+                `perLanguage: "${language}" is not a language this site declares.`
+            );
+        }
+    }
+    const entries = locales.map((tag) => {
+        const language = tag.split("-")[0] as string;
+        const text = given[language];
+        if (text === undefined) {
+            throw new Error(`perLanguage: no text for "${language}" (${tag}).`);
+        }
+        return [tag, text];
+    });
+    return Object.fromEntries(entries) as PerLanguage<L, T>;
+}

package/src/jsonld/organization.ts

@@ -5,6 +5,7 @@ import {
     type PostalAddress,
 } from "../contact.ts";
 import type { ImageAsset } from "../image.ts";
+import type { IsoDate } from "../types.ts";
 import { absoluteUrl, type HttpsUrl, joinUrl, type UrlPath } from "../url.ts";
 import { organizationId } from "./ids.ts";
 import { alternateName, type JsonLdNode } from "./node.ts";
@@ -15,6 +16,16 @@ export interface OrganizationInput {
     readonly name: string;
     /** The brand's own home. Also its identity, see `@id` below. */
     readonly url: HttpsUrl;
+    /**
+     * What the brand is, in a sentence. Google lists it as a recommended
+     * property of an organization.
+     */
+    readonly description?: string;
+    /**
+     * When the brand was founded: a full date, or just the year where that is
+     * all anyone can honestly state. Both are valid ISO 8601.
+     */
+    readonly foundingDate?: IsoDate | `${number}`;
     /**
      * Another name the brand actually goes by — an acronym, a short form.
      *
@@ -162,6 +173,12 @@ export function organization(brand: OrganizationInput): JsonLdNode {
         name: brand.name,
         url: brand.url,
         ...alternateName(brand.name, brand.alternateName),
+        ...(brand.description === undefined
+            ? {}
+            : { description: brand.description }),
+        ...(brand.foundingDate === undefined
+            ? {}
+            : { foundingDate: brand.foundingDate }),
         ...(brand.logo === undefined
             ? {}
             : { logo: joinUrl(brand.url, brand.logo) }),

package/src/llms.ts

@@ -68,6 +68,11 @@ export interface LlmsInput {
         readonly tag: string;
         readonly url: HttpsUrl;
     }[];
+    /**
+     * Whether any page's slug differs between languages. Decides what the file
+     * tells a reader about reaching the same page in another one.
+     */
+    readonly translatedSlugs?: boolean;
     readonly sections: readonly LlmsSection[];
 }
 
@@ -104,14 +109,18 @@ export function buildLlms(input: LlmsInput): GeneratedFile {
     // Which language the links are in, and how to get to the others — stated
     // only when there *are* others.
     //
-    // Not "swap the prefix": a slug is translated too, so the Greek `/about-us`
-    // is `/el-GR/sxetika-me-emas` and a reader told to substitute the prefix
-    // would construct a URL that 404s. The sitemap is where that mapping
-    // actually lives, one `xhtml:link` per page per language, so this points at
-    // it rather than describing a rule that does not hold.
+    // Whether "swap the prefix" works depends on the site, so it is stated only
+    // where it holds. Where a slug is translated, the Greek `/about-us` is
+    // `/el-GR/sxetika-me-emas` and a reader told to substitute the prefix would
+    // construct a URL that 404s; the sitemap is where that mapping lives, one
+    // `xhtml:link` per page per language.
     if (input.otherLanguages !== undefined && input.otherLanguages.length > 0) {
         lines.push(
-            `Every URL below is the ${input.language.tag} version. Other languages translate their slugs, so the same page is not this URL with a different prefix — the sitemap lists each page in every language.`,
+            `Every URL below is the ${input.language.tag} version. ${
+                input.translatedSlugs === true
+                    ? "Other languages might translate their slugs, so the same page is not always this URL with a different prefix —"
+                    : "Other languages use the same path under their own address above —"
+            } the sitemap lists each page in every language.`,
             ""
         );
     }

package/src/site/create.ts

@@ -761,6 +761,18 @@ export function createSite<
                 tag: localeMeta[other].htmlLang,
                 url: joinUrl(siteUrl, buildPath("", other, pathContext)),
             })),
+            // Read off the routes, so the file cannot claim something the URLs
+            // do not do.
+            translatedSlugs: enabledRouteIds.some((id) => {
+                const route = resolved[id];
+                return (
+                    route !== undefined &&
+                    others.some(
+                        (other) =>
+                            slugFor(route, other) !== slugFor(route, locale)
+                    )
+                );
+            }),
             sections,
         });
     }

package/src/site/define.ts

@@ -10,6 +10,11 @@ import {
     type NoExtraLocales,
     type ValidateBase,
 } from "../i18n/define.ts";
+import {
+    expandLanguages,
+    type LanguageOf,
+    type PerLanguage,
+} from "../i18n/per-language.ts";
 import {
     bindRedirects,
     type DefinedProject,
@@ -86,6 +91,13 @@ export function defineSite<
             return defineMessages(config, catalog as never) as T;
         },
 
+        /** One message per language, filled in for each of that language's tags. */
+        perLanguage<const T extends Readonly<Record<LanguageOf<L>, string>>>(
+            texts: T & Readonly<Record<Exclude<keyof T, LanguageOf<L>>, never>>
+        ): PerLanguage<L, T> {
+            return expandLanguages(Object.keys(config.locales) as L[], texts);
+        },
+
         /** One deployment: what differs from the defaults. */
         project<
             const Catalog extends BaseCatalog<L>,