/** * RFC-0033 §4 / ADR-0035: a site's locales on the web. The locale is in the path * (`prefix-except-default`: the default locale at the root, the others under `/`; * `prefix-all`: every locale prefixed) or in the host (`localization.domains`), never in a cookie * or `Accept-Language`. This module splits a request into locale and graph path, builds localized * URLs, lists a node's language versions for `hreflang`, and rewrites a localized page's internal * links to the same locale. Worker-safe. */ import type { ContentEntry, Page, Site, Taxonomy, Term } from "@cloudhal/core-contracts"; import { entryPath, type PermalinkSite, termSlug } from "@cloudhal/core-ts"; import { localeRouting, localeUrl, localizedPath } from "@cloudhal/core-ts/locale-paths"; import { trimEndChar } from "@cloudhal/core-ts/names"; import { routableEntries } from "./entry-views.ts"; import type { HeadMeta } from "./seo.ts"; import type { GraphSource } from "./source.ts"; /** Scripts written right to left, by primary language subtag (CLDR). */ const RTL = new Set([ "ar", "arc", "ckb", "dv", "fa", "he", "ks", "ku", "ps", "sd", "syr", "ug", "ur", "yi", ]); /** `` for a locale. Kurdish written in Latin (`ku-Latn`) is the one exception handled. */ export function textDirection(locale: string): "ltr" | "rtl" { const [language = "", script] = locale.toLowerCase().split("-"); if (script === "latn" || script === "cyrl") return "ltr"; return RTL.has(language) ? "rtl" : "ltr"; } // The URL helpers live in core-ts (Studio builds the same addresses); re-exported unchanged. export { localeRouting, localeUrl, localizedPath } from "@cloudhal/core-ts/locale-paths"; /** The locale a host serves on its own (`localization.domains`), if any. */ export function hostLocale(site: Site, host: string): string | undefined { const bare = host.toLowerCase().replace(/:\d+$/, ""); const domains = site.localization?.domains ?? {}; return Object.keys(domains).find((l) => domains[l]?.toLowerCase() === bare); } export interface LocaleRequest { /** The locale the request is for. */ readonly locale: string; /** The graph path inside that locale (no prefix). */ readonly path: string; /** Where to send the request instead (a 301), for a non-canonical locale URL. */ readonly redirect?: string; } /** * Splits a request path (no trailing slash, `/` for the root) into locale and graph path. A * default-locale prefix under `prefix-except-default` and an unprefixed path under `prefix-all` * redirect to the canonical URL; a locale served by its own domain is never a prefix. */ export function localeRequest(site: Site, host: string, path: string): LocaleRequest { const own = hostLocale(site, host); if (own) return { locale: own, path }; const segment = path.split("/")[1] ?? ""; const domains = site.localization?.domains ?? {}; const locale = site.locales.find( (l) => l.toLowerCase() === segment.toLowerCase() && domains[l] === undefined, ); const routing = localeRouting(site); if (locale && segment) { const rest = path.slice(segment.length + 1) || "/"; if (locale === site.defaultLocale && routing === "prefix-except-default") return { locale, path: rest, redirect: rest }; if (segment !== locale) return { locale, path: rest, redirect: localizedPath(site, locale, rest) }; return { locale, path: rest }; } if (routing === "prefix-all") return { locale: site.defaultLocale, path, redirect: localizedPath(site, site.defaultLocale, path), }; return { locale: site.defaultLocale, path }; } /** One language version of a page or entry for `hreflang` and the language switcher. */ export interface Alternate { /** BCP 47 locale, or `x-default`. */ readonly locale: string; readonly href: string; /** This is the version being rendered. */ readonly current: boolean; /** This is the group's original (the source of the translations). */ readonly original?: boolean; } type Localized = Page | ContentEntry; const pathOf = (site: PermalinkSite, n: Localized) => ("path" in n ? n.path : entryPath(site, n)); /** The visible members of `group` in this source (pages, or entries in the site's locales). */ async function groupMembers( source: GraphSource, site: Site, group: string, pages: boolean, ): Promise { const inGroup = (n: Localized) => n.id === group || n.translation?.group === group; if (pages) return (await source.pages()).filter(inGroup); const all = await Promise.all(site.locales.map((l) => routableEntries(source, l))); return all.flat().filter(inGroup); } /** * RFC-0034 §6: another site of the project holding versions of the same work (a language * edition): its published source and the origin it is served on. */ export interface PeerEdition { readonly source: GraphSource; readonly origin: string; } /** * RFC-0033 invariant 7: every visible version of the node (itself included), plus `x-default` * (the default locale's version). Empty when the node has no other version — `hreflang` needs two. * `peers` adds the versions published by other sites of the project (RFC-0034 §6), each on its * own host; a locale this site serves itself is not taken from a peer. */ export async function alternatesFor( source: GraphSource, node: Localized, origin: string, peers: readonly PeerEdition[] = [], ): Promise { const site = await source.site(); const group = node.translation?.group ?? (peers.length > 0 ? node.id : undefined); if (!group) return []; const pages = "path" in node; const own = (await groupMembers(source, site, group, pages)).filter((m) => site.locales.includes(m.locale), ); const out: Alternate[] = own.map((m) => ({ locale: m.locale, href: localeUrl(site, m.locale, pathOf(site, m), origin), current: m.id === node.id, ...(m.id === group ? { original: true } : {}), })); for (const peer of peers) { const peerSite = await peer.source.site(); for (const m of await groupMembers(peer.source, peerSite, group, pages)) if (peerSite.locales.includes(m.locale) && !out.some((a) => a.locale === m.locale)) out.push({ locale: m.locale, href: localeUrl(peerSite, m.locale, pathOf(peerSite, m), peer.origin), current: false, ...(m.id === group ? { original: true } : {}), }); } if (out.length < 2) return []; const rank = (l: string) => { const i = site.locales.indexOf(l); return i === -1 ? site.locales.length : i; }; out.sort((a, b) => rank(a.locale) - rank(b.locale) || a.locale.localeCompare(b.locale)); // One x-default for the whole set: across editions, the group's original (every site agrees); // within one site, its default locale's version. const spans = out.some((a) => !site.locales.includes(a.locale)); const fallback = spans ? (out.find((a) => a.original) ?? out.find((a) => a.locale === site.defaultLocale)) : out.find((a) => a.locale === site.defaultLocale); return fallback ? [...out, { locale: "x-default", href: fallback.href, current: false }] : out; } /** * Internal links of a page in `locale` (`origin`: the site's primary origin, for links back from a * locale's own domain): a path that leads to a page, entry or archive with a * version in `locale` goes there; one that leads to a default-locale node without such a version * stays in the default locale (a reader may still follow it); anything else — search, feeds, * unknown paths — stays in `locale`. */ export async function linkLocalizer( source: GraphSource, locale: string, origin: string, ): Promise<((path: string) => string) | undefined> { const site = await source.site(); const def = site.defaultLocale; const prefixAll = localeRouting(site) === "prefix-all"; if (locale === def && !prefixAll) return undefined; const own = site.localization?.domains?.[locale] !== undefined; const here = (p: string) => (own ? p : localizedPath(site, locale, p)); const home = (p: string) => (own ? localeUrl(site, def, p, origin) : localizedPath(site, def, p)); const [pages, entries, translated, taxonomies, terms] = await Promise.all([ source.pages(), routableEntries(source, def), routableEntries(source, locale), source.taxonomies(), source.vocabulary(), ]); const byGroup = new Map(); for (const n of [...pages, ...translated]) if (n.locale === locale && n.translation) byGroup.set(`${"path" in n ? "p" : "e"}:${n.translation.group}`, n); const map = new Map(); for (const n of [...pages.filter((p) => p.locale === def), ...entries]) { const twin = byGroup.get(`${"path" in n ? "p" : "e"}:${n.translation?.group ?? n.id}`); map.set(pathOf(site, n), twin ? here(pathOf(site, twin)) : home(pathOf(site, n))); } const archive = archiveLocalizer(taxonomies, terms, locale, def); return (path) => map.get(path) ?? (archive(path) ? here(archive(path) as string) : here(path)); } /** `/[/…]` with the term's slug in `locale`; undefined for other paths. */ function archiveLocalizer( taxonomies: readonly Taxonomy[], terms: readonly Term[], locale: string, def: string, ): (path: string) => string | undefined { return (path) => { for (const tax of taxonomies) { if (!tax.archive.enabled || !path.startsWith(`${tax.archive.basePath}/`)) continue; const [slug = "", ...rest] = path.slice(tax.archive.basePath.length + 1).split("/"); const term = terms.find((t) => t.taxonomyId === tax.id && t.slug === slug); if (term) return [`${tax.archive.basePath}/${termSlug(term, locale, def)}`, ...rest].join("/"); } return undefined; }; } /** Paths that are never a page: platform endpoints and media. */ const PLATFORM = /^\/(?:_|media\/)/; /** * Rewrites root-relative `href`s of ``, `action`s of `
` and the search dialog's * `data-endpoint`/`data-page` in rendered HTML through `localize` (query and fragment kept). * Platform paths are left alone. */ export function localizeLinks(html: string, localize: (path: string) => string): string { const swap = (all: string, head: string, url: string, tail: string) => { if (url.startsWith("//") || PLATFORM.test(url)) return all; const cut = url.search(/[?#]/); const path = cut < 0 ? url : url.slice(0, cut); const suffix = cut < 0 ? "" : url.slice(cut); return `${head}${localize(path.length > 1 ? trimEndChar(path, "/") : path)}${suffix}${tail}`; }; return html .replace(/(<(?:a|form)\b[^>]*?\s(?:href|action)=")(\/[^"]*)(")/gi, swap) .replace(/(\sdata-(?:endpoint|page)=")(\/[^"]*)(")/gi, swap); } /** * The head of a page rendered in `locale`: its canonical, `og:url` and feed links on the locale's * URLs (each version is self-canonical, never pointing at another language), `lang`/`dir`, the * `hreflang` set and `og:locale:alternate`. */ export function localizeHead( meta: HeadMeta, site: Site, input: { locale: string; origin: string; alternates: readonly Alternate[]; translation?: Localized["translation"]; }, ): HeadMeta { const { locale, origin, alternates } = input; const here = (url: string) => url.startsWith(origin) ? localeUrl(site, locale, url.slice(origin.length) || "/", origin) : url; const canonical = here(meta.canonical); const others = alternates.filter((a) => !a.current && a.locale !== "x-default"); return { ...meta, canonical, lang: locale, dir: textDirection(locale), feeds: meta.feeds.map((f) => ({ ...f, href: here(f.href) })), openGraph: [ ...meta.openGraph.map(([k, v]): [string, string] => [k, k === "og:url" ? canonical : v]), ...others.map((a): [string, string] => ["og:locale:alternate", a.locale.replace("-", "_")]), ], jsonLd: meta.jsonLd.map((doc, i) => i === 0 ? translationLd(doc, alternates, input.translation) : doc, ), ...(alternates.length ? { alternates: alternates.map(({ locale: l, href }) => ({ locale: l, href })) } : {}), }; } /** * schema.org links between versions (RFC-0033 §4): the original lists its `workTranslation`s, a * translation names its `translationOfWork`; `translator` is the reviewer, or the engine * (a `SoftwareApplication`) for machine output nobody has reviewed yet. */ function translationLd( doc: object, alternates: readonly Alternate[], translation: Localized["translation"], ): object { const self = alternates.find((a) => a.current); const original = alternates.find((a) => a.original); const others = alternates.filter((a) => !a.current && a.locale !== "x-default"); const links = !self || !original ? {} : self.original ? { workTranslation: others.map((a) => ({ "@id": a.href, inLanguage: a.locale })) } : { translationOfWork: { "@id": original.href, inLanguage: original.locale } }; const by = translation?.review?.by; const translator = by ? { translator: { "@type": "Person", name: by.name ?? by.id } } : translation?.method === "machine" && translation.provenance ? { translator: { "@type": "SoftwareApplication", name: translation.provenance.engine } } : {}; return { ...doc, ...links, ...translator }; }