From b2bfb734c6afeffc6ccd898a705abb391c8a4d90 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 4 Sep 2026 15:13:29 +0200
Subject: [PATCH] Documented the alternate locales of the Social Card in the
 Infrastructure package.

---
 Packages/Infrastructure/README.md                             | 2 +-
 .../Sources/Public/Types/SocialCard/SocialCardTag.swift       | 1 +
 Services/Website/README.md                                    | 4 ++--
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index ae93c77..9571378 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -7,7 +7,7 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
 | Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `TrailingSlashRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware` (negotiating from a `lang` query parameter, then a leading path segment, then `Accept-Language`), `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
-| Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives |
+| Link previews | `SocialCard`, its `locale` and the `alternateLocales` of its other language editions, its `Image` and `Style`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair |
 | Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to any attribute-bearing HTML or SVG tag), the tracker script `Attribute`s it derives, the optional session `recorder` script paired with it, and the `origin` its preconnect hint targets |
 | Responses | `CachedHTMLResponse`, and `LocalizedHTMLCollectionResponse` rendering one of them per catalog language |
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
index 1924635..d286881 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
@@ -60,6 +60,7 @@ extension SocialCard.Tag {
         case imageWidth = "og:image:width"
         /// The `og:locale` tag, carrying the locale of the card's text.
         case locale = "og:locale"
+        /// The `og:locale:alternate` tag, carrying the locale of one other language edition of the card's page; repeated once per edition.
         case localeAlternate = "og:locale:alternate"
         /// The `og:site_name` tag, carrying the name of the site the card belongs to.
         case siteName = "og:site_name"
diff --git a/Services/Website/README.md b/Services/Website/README.md
index e00147c..08c6709 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -60,7 +60,7 @@ Four of those are page-authored and optional. `IndexPage` supplies `canonicalURL
 | --- | --- | --- |
 | `summary` | `<meta name="description">` | The page's one-line description. |
 | `canonicalURL` | `<link rel="canonical">` | Absolute URL. `IndexPage` derives it from `site.origin` and the page's own language; an unset origin omits it (see [Language editions](#language-editions)). |
-| `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, share image. Scrapers require absolute URLs, so the page composes them from its own origin; `Page+Defaults` supplies the locale as `ogLocale`. |
+| `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, alternate locales, share image. Scrapers require absolute URLs, so the page composes them from its own origin; `Page+Defaults` supplies the locale as `ogLocale`. |
 | `structuredData` | `<script type="application/ld+json">` | A `StructuredData` graph of schema.org nodes; `StructuredData(name:url:logo:inLanguage:profiles:)` builds the site-wide `Organization` + `WebSite` pair, `inLanguage` declaring the languages the site publishes in (see [Language editions](#language-editions)). The payload is an inert data block, so the `Content-Security-Policy` does not apply to it. |
 
 The fifth, `analytics`, is *configuration*-authored rather than page-authored: the executable builds an `Analytics` from the `analytics.*` keys and hands it to `RootController` and `NotFoundMiddleware`, which pass it to both pages. It renders as a `<link rel="preconnect">` plus a deferred `<script>` carrying the [Umami](https://umami.is) `data-` attributes, and — unlike the structured data — it *is* executable, so the `Content-Security-Policy` must allow its origin. It is empty by default; see [Analytics](#analytics) for how to turn it on.
@@ -85,7 +85,7 @@ The catalog's source language is the **default** and owns the site's bare paths;
 
 Given a `site.origin`, each page then emits the `hreflang` alternates tying its editions together — one per language plus an `x-default` pointing at the default language's edition, whose bare URL negotiates the language and so is the right landing for everyone unmatched. A single-language site emits none: a set naming one edition tells a search engine nothing it cannot already see. `Page+Defaults`' `languageAlternates(origin:path:languages:)` takes the language set, so a page translated into only some of them narrows it rather than advertising an edition that does not exist.
 
-The same set belongs in the site-wide structured data: `StructuredData`'s `inLanguage` declares it on the `WebSite` node, so a crawler reads the site's languages from the graph as well as from the alternates.
+The same set belongs in the site-wide structured data: `StructuredData`'s `inLanguage` declares it on the `WebSite` node, so a crawler reads the site's languages from the graph as well as from the alternates. A page's social card says the same to a scraper: its `locale` is the edition the page *is*, and `SocialCard`'s `alternateLocales` names the rest, each mapped through `ogLocales` the way `ogLocale` maps the page's.
 
 `sitemap.xml` is the one part that does *not* follow the catalog: it is a static file, so a new language needs its editions added by hand — `/nl`, `/nl/<page>`, one `<loc>` each, alongside the default language's. Give each the same spelling the page's own canonical carries (the root is the bare origin, with no trailing slash), or the two disagree about which URL is canonical.