@ultimat3/seo 22.2.2 → 22.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/seo",
-  "version": "22.2.2",
+  "version": "22.3.0",
   "description": "Enforced SEO: typed meta, JSON-LD, sitemap, robots, feeds, responsive images, perf budgets",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.2.2",
-    "@ultimat3/schema": "22.2.2"
+    "@ultimat3/core": "22.3.0",
+    "@ultimat3/schema": "22.3.0"
   }
 }

package/src/index.ts

@@ -70,6 +70,8 @@ export {
   SoftwareApplication,
   WebSite,
 } from './ld';
+export type { LocalizedPage, MetaLocalization } from './locale-tags';
+export { hreflangTag, ogLocaleTag } from './locale-tags';
 export type {
   AlternateLocale,
   HeadTag,
@@ -85,6 +87,7 @@ export {
   applyTitleTemplate,
   DESCRIPTION_MAX_LENGTH,
   hreflangSet,
+  localizedAlternates,
   renderMeta,
   robotsContent,
   TITLE_MAX_LENGTH,

package/src/locale-tags.ts

@@ -0,0 +1,37 @@
+// A locale as the two vocabularies a crawler reads spell it. An app registers `es-co` (lowercase is
+// the catalog and URL form); `hreflang` wants BCP 47 with its region uppercased, `es-CO`, and Open
+// Graph wants the underscore form, `es_CO`. One conversion, so the sitemap and the head agree.
+
+/**
+ * `es-co` → `es-CO`, `zh-hant-tw` → `zh-Hant-TW`, `en` → `en`. `Intl`'s own canonical form, which
+ * is BCP 47's; a tag `Intl` refuses is returned as written rather than thrown — this runs per
+ * render, and the config screen (`configureLocales`) already refused anything unparseable.
+ */
+export function hreflangTag(locale: string): string {
+  try {
+    return Intl.getCanonicalLocales(locale)[0] ?? locale;
+  } catch {
+    return locale;
+  }
+}
+
+/** `es-co` → `es_CO`: Open Graph's `language_TERRITORY`. */
+export function ogLocaleTag(locale: string): string {
+  return hreflangTag(locale).replace(/-/g, '_');
+}
+
+/** A page in one locale: the locale and the page's own path in it. */
+export interface LocalizedPage {
+  readonly locale: string;
+  readonly path: string;
+}
+
+/** What `renderMeta` needs to emit a page's hreflang cluster and its `og:locale` pair. */
+export interface MetaLocalization {
+  /** The locale this document renders in. */
+  readonly locale: string;
+  /** The locale whose page `x-default` names. */
+  readonly defaultLocale: string;
+  /** This page in every locale it exists in, the current one included. */
+  readonly alternates: readonly LocalizedPage[];
+}

package/src/meta.ts

@@ -2,6 +2,7 @@
 // for a global default: a route that does not declare a description does not get
 // one, it fails the build (see validate.ts).
 
+import { hreflangTag, type MetaLocalization, ogLocaleTag } from './locale-tags';
 import { absoluteUrl } from './xml';
 
 /**
@@ -100,6 +101,33 @@ export interface RenderMetaOptions {
   baseUrl?: string;
   /** Resolved path, used when `canonical` is omitted. */
   path?: string;
+  /**
+   * The document's locale and the page in every routed locale. Given, and the route declares no
+   * `alternates` of its own, the full hreflang cluster is emitted — every locale plus `x-default` —
+   * with `og:locale` and one `og:locale:alternate` per other locale. A cluster of one is none.
+   */
+  localization?: MetaLocalization;
+}
+
+/**
+ * The hreflang set a route did not have to write: one entry per locale, BCP 47 region form, and
+ * `x-default` naming the default locale's page. Empty for a single-locale app — an hreflang cluster
+ * of one tells a crawler nothing and costs every document a tag.
+ */
+export function localizedAlternates(
+  localization: MetaLocalization | undefined,
+): readonly AlternateLocale[] {
+  if (localization === undefined || localization.alternates.length < 2) return [];
+  const cluster = localization.alternates.map((page) => ({
+    hreflang: hreflangTag(page.locale),
+    href: page.path,
+  }));
+  const fallback = localization.alternates.find(
+    (page) => page.locale === localization.defaultLocale,
+  );
+  return fallback === undefined
+    ? cluster
+    : [...cluster, { hreflang: 'x-default', href: fallback.path }];
 }
 
 /**
@@ -190,17 +218,31 @@ export function renderMeta(meta: RouteMeta, options: RenderMetaOptions = {}): re
 
   // --- Open Graph ------------------------------------------------------------
   const og = meta.og ?? {};
+  const localization = options.localization;
+  const ogLocale =
+    og.locale ?? (localization === undefined ? undefined : ogLocaleTag(localization.locale));
   const ogEntries: Array<[string, string | undefined]> = [
     ['og:type', og.type ?? 'website'],
     ['og:title', og.title ?? meta.title],
     ['og:description', og.description ?? meta.description],
     ['og:url', og.url === undefined ? canonicalHref : abs(og.url)],
     ['og:site_name', og.siteName],
-    ['og:locale', og.locale],
+    ['og:locale', ogLocale],
   ];
   for (const [property, content] of ogEntries) {
     if (content !== undefined) tags.push({ tag: 'meta', attrs: { property, content } });
   }
+  // Every OTHER locale the page exists in — a repeatable property, which `@ultimat3/render`'s head
+  // dedupe keys by content as well (`head-seo.ts`), so N alternates do not collapse to the last.
+  if (localization !== undefined && localization.alternates.length > 1) {
+    for (const page of localization.alternates) {
+      if (page.locale === localization.locale) continue;
+      tags.push({
+        tag: 'meta',
+        attrs: { property: 'og:locale:alternate', content: ogLocaleTag(page.locale) },
+      });
+    }
+  }
   if (og.image !== undefined) {
     const image = typeof og.image === 'string' ? { url: og.image } : og.image;
     tags.push({ tag: 'meta', attrs: { property: 'og:image', content: abs(image.url) } });
@@ -251,7 +293,10 @@ export function renderMeta(meta: RouteMeta, options: RenderMetaOptions = {}): re
   }
 
   // --- hreflang --------------------------------------------------------------
-  for (const alternate of hreflangSet(meta.alternates ?? [], meta.xDefault ?? canonicalHref)) {
+  // A route's own `alternates` win whole; otherwise the cluster comes from the routed locales.
+  const declared = meta.alternates ?? [];
+  const alternates = declared.length > 0 ? declared : localizedAlternates(localization);
+  for (const alternate of hreflangSet(alternates, meta.xDefault ?? canonicalHref)) {
     tags.push({
       tag: 'link',
       attrs: { rel: 'alternate', hreflang: alternate.hreflang, href: abs(alternate.href) },

package/src/robots.ts

@@ -18,6 +18,12 @@ export interface RobotsConfig {
   /** Omitted means "resolve from the environment"; anything but `production` disallows all. */
   environment?: Environment | undefined;
   groups?: readonly RobotsGroup[];
+  /**
+   * Paths every crawler is kept out of — `app.config.ts`'s `seo.robots.disallow`. Added to the
+   * default `User-agent: *` group, or to each declared group that names `*`. Production only: a
+   * non-production `robots.txt` already disallows everything.
+   */
+  disallow?: readonly string[];
   /** Sitemap paths or absolute URLs. Only emitted in production. */
   sitemaps?: readonly string[];
   /** Extra lines appended verbatim, e.g. a `Host:` directive. */
@@ -57,10 +63,16 @@ export function buildRobots(config: RobotsConfig): string {
     return `${lines.join('\n')}\n`;
   }
 
-  const groups: readonly RobotsGroup[] =
+  const declared: readonly RobotsGroup[] =
     config.groups === undefined || config.groups.length === 0
       ? [{ userAgent: '*', allow: ['/'] }]
       : config.groups;
+  const extra = config.disallow ?? [];
+  const groups = declared.map((group) =>
+    extra.length === 0 || !agents(group.userAgent).includes('*')
+      ? group
+      : { ...group, disallow: [...(group.disallow ?? []), ...extra] },
+  );
 
   for (const group of groups) {
     for (const agent of agents(group.userAgent)) lines.push(`User-agent: ${agent}`);

package/src/sitemap.ts

@@ -4,6 +4,7 @@
 
 import { assert } from '@ultimat3/core';
 import { sitemapTooLarge } from './errors';
+import { hreflangTag } from './locale-tags';
 import { type ChangeFreq, expandRoute, indexableRoutes, type RouteRecord } from './routes';
 import { absoluteUrl, attributes, escapeXml } from './xml';
 
@@ -95,7 +96,9 @@ export async function sitemapUrls(
         path: localize(path, locale, options),
       }));
       const alternates: SitemapAlternate[] = localised.map((entry) => ({
-        hreflang: entry.locale,
+        // BCP 47 region form (`es-CO`), the spelling `renderMeta` puts in the head: one cluster,
+        // one vocabulary, whether a crawler reads the page or the sitemap.
+        hreflang: hreflangTag(entry.locale),
         href: absoluteUrl(options.baseUrl, entry.path),
       }));
       // `x-default` only when it names a URL THIS sitemap lists. It was the bare `path` for every