@fedify/vocab-runtime 2.1.26 → 2.1.28

package/src/docloader.test.ts

@@ -2,12 +2,13 @@ import { configure, type LogRecord, reset } from "@logtape/logtape";
 import fetchMock from "fetch-mock";
 import { deepStrictEqual, ok, rejects } from "node:assert";
 import dns from "node:dns/promises";
-import { test } from "node:test";
+import { test } from "@fedify/fixture";
 import { createServer } from "node:http";
 import { gzipSync } from "node:zlib";
 import preloadedContexts from "./contexts.ts";
 import cidV1Context from "./contexts/cid-v1.json" with { type: "json" };
 import { getDocumentLoader, getRemoteDocument } from "./docloader.ts";
+import jsonld from "./jsonld.ts";
 import { FetchError } from "./request.ts";
 import { UrlError } from "./url.ts";
 
@@ -44,7 +45,7 @@ test("getDocumentLoader()", async (t) => {
     },
   });
 
-  await t.test("ok", async () => {
+  await t.step("ok", async () => {
     deepStrictEqual(await fetchDocumentLoader("https://example.com/object"), {
       contextUrl: null,
       documentUrl: "https://example.com/object",
@@ -101,7 +102,7 @@ test("getDocumentLoader()", async (t) => {
     },
   });
 
-  await t.test("Link header", async () => {
+  await t.step("Link header", async () => {
     deepStrictEqual(await fetchDocumentLoader("https://example.com/link-ctx"), {
       contextUrl: "https://www.w3.org/ns/activitystreams",
       documentUrl: "https://example.com/link-ctx",
@@ -124,7 +125,7 @@ test("getDocumentLoader()", async (t) => {
     });
   });
 
-  await t.test("Link header relative url", async () => {
+  await t.step("Link header relative url", async () => {
     deepStrictEqual(await fetchDocumentLoader("https://example.com/link-ctx"), {
       contextUrl: "https://www.w3.org/ns/activitystreams",
       documentUrl: "https://example.com/link-ctx",
@@ -150,7 +151,7 @@ test("getDocumentLoader()", async (t) => {
     );
   });
 
-  await t.test("wrong Link header syntax", async () => {
+  await t.step("wrong Link header syntax", async () => {
     deepStrictEqual(
       await fetchDocumentLoader("https://example.com/obj-w-wrong-link"),
       {
@@ -179,7 +180,7 @@ test("getDocumentLoader()", async (t) => {
     headers: { "Content-Type": "text/html; charset=utf-8" },
   });
 
-  await t.test("HTML <link>", async () => {
+  await t.step("HTML <link>", async () => {
     deepStrictEqual(
       await fetchDocumentLoader("https://example.com/html-link"),
       {
@@ -208,7 +209,7 @@ test("getDocumentLoader()", async (t) => {
     headers: { "Content-Type": "application/xhtml+xml; charset=utf-8" },
   });
 
-  await t.test("XHTML <link>", async () => {
+  await t.step("XHTML <link>", async () => {
     deepStrictEqual(
       await fetchDocumentLoader("https://example.com/xhtml-link"),
       {
@@ -239,7 +240,7 @@ test("getDocumentLoader()", async (t) => {
     headers: { "Content-Type": "text/html; charset=utf-8" },
   });
 
-  await t.test("HTML <a>", async () => {
+  await t.step("HTML <a>", async () => {
     deepStrictEqual(await fetchDocumentLoader("https://example.com/html-a"), {
       contextUrl: null,
       documentUrl: "https://example.com/object",
@@ -262,7 +263,7 @@ test("getDocumentLoader()", async (t) => {
     headers: { "Content-Type": "text/html; charset=utf-8" },
   });
 
-  await t.test("Wrong Content-Type", async () => {
+  await t.step("Wrong Content-Type", async () => {
     deepStrictEqual(
       await fetchDocumentLoader("https://example.com/wrong-content-type"),
       {
@@ -280,7 +281,7 @@ test("getDocumentLoader()", async (t) => {
 
   fetchMock.get("https://example.com/404", { status: 404 });
 
-  await t.test("not ok", async () => {
+  await t.step("not ok", async () => {
     await rejects(
       () => fetchDocumentLoader("https://example.com/404"),
       FetchError,
@@ -288,7 +289,7 @@ test("getDocumentLoader()", async (t) => {
     );
   });
 
-  await t.test("preloaded contexts", async () => {
+  await t.step("preloaded contexts", async () => {
     for (const [url, document] of Object.entries(preloadedContexts)) {
       deepStrictEqual(await fetchDocumentLoader(url), {
         contextUrl: null,
@@ -298,13 +299,37 @@ test("getDocumentLoader()", async (t) => {
     }
   });
 
+  await t.step("preloaded Mastodon attribution domains", async () => {
+    const context = [
+      "https://www.w3.org/ns/activitystreams",
+      "http://joinmastodon.org/ns",
+    ];
+    const expanded = await jsonld.expand({
+      "@context": context,
+      id: "https://social.example/users/alice",
+      type: "Person",
+      attributionDomains: ["blog.example"],
+    }, { documentLoader: fetchDocumentLoader });
+    deepStrictEqual(expanded, [{
+      "@id": "https://social.example/users/alice",
+      "@type": ["https://www.w3.org/ns/activitystreams#Person"],
+      "http://joinmastodon.org/ns#attributionDomains": [
+        { "@value": "blog.example" },
+      ],
+    }]);
+    const compacted = await jsonld.compact(expanded, context, {
+      documentLoader: fetchDocumentLoader,
+    });
+    deepStrictEqual(compacted.attributionDomains, ["blog.example"]);
+  });
+
   // Controlled Identifiers v1.0 requires JSON-LD processors to treat this
   // context URL as already resolved.  A temporary W3C outage must not prevent
   // an otherwise valid document from being processed.
   // See: https://www.w3.org/TR/cid-1.0/#json-ld-context
   //      https://github.com/fedify-dev/fedify/issues/932
   fetchMock.get("https://www.w3.org/ns/cid/v1", { status: 503 });
-  await t.test("preloaded CID v1 context", async () => {
+  await t.step("preloaded CID v1 context", async () => {
     const url = "https://www.w3.org/ns/cid/v1";
     deepStrictEqual(await fetchDocumentLoader(url), {
       contextUrl: null,
@@ -318,7 +343,7 @@ test("getDocumentLoader()", async (t) => {
   // document referencing it fails before application handlers run.  It has to
   // be resolved from the built-in copy rather than over the network.
   // See: https://github.com/fedify-dev/fedify/issues/982
-  await t.test("preloaded FEP-ef61 context", async () => {
+  await t.step("preloaded FEP-ef61 context", async () => {
     const url = "https://w3id.org/fep/ef61";
     ok(url in preloadedContexts);
     deepStrictEqual(await fetchDocumentLoader(url), {
@@ -341,7 +366,7 @@ test("getDocumentLoader()", async (t) => {
   // A Codeberg Pages outage must not prevent loading the FEP-7aa9 context.
   // See: https://github.com/fedify-dev/fedify/issues/1078
   fetchMock.get("https://w3id.org/fep/7aa9", { status: 502 });
-  await t.test("preloaded FEP-7aa9 context", async () => {
+  await t.step("preloaded FEP-7aa9 context", async () => {
     const url = "https://w3id.org/fep/7aa9";
     deepStrictEqual(await fetchDocumentLoader(url), {
       contextUrl: null,
@@ -375,7 +400,130 @@ test("getDocumentLoader()", async (t) => {
     deepStrictEqual(fetchMock.callHistory.calls(url).length, 0);
   });
 
-  await t.test("deny non-HTTP/HTTPS", async () => {
+  // A Codeberg Pages outage must not prevent loading or expanding FEP-6757.
+  // See: https://github.com/fedify-dev/fedify/issues/1211
+  fetchMock.get("https://w3id.org/fep/6757", { status: 502 });
+  await t.step("preloaded FEP-6757 context", async () => {
+    const url = "https://w3id.org/fep/6757";
+    deepStrictEqual(await fetchDocumentLoader(url), {
+      contextUrl: null,
+      documentUrl: url,
+      document: {
+        "@context": {
+          license: {
+            "@id": "http://purl.org/dc/terms/license",
+            "@type": "@id",
+          },
+          preferredLicense: {
+            "@id": "https://w3id.org/fep/6757#preferredLicense",
+            "@type": "@id",
+          },
+        },
+      },
+    });
+    deepStrictEqual(
+      await jsonld.expand({
+        "@context": ["https://www.w3.org/ns/activitystreams", url],
+        type: "Person",
+        license: "https://creativecommons.org/licenses/by/4.0/",
+        preferredLicense: "https://creativecommons.org/licenses/by-nc/4.0/",
+      }, { documentLoader: fetchDocumentLoader }),
+      [{
+        "@type": ["https://www.w3.org/ns/activitystreams#Person"],
+        "http://purl.org/dc/terms/license": [{
+          "@id": "https://creativecommons.org/licenses/by/4.0/",
+        }],
+        "https://w3id.org/fep/6757#preferredLicense": [{
+          "@id": "https://creativecommons.org/licenses/by-nc/4.0/",
+        }],
+      }],
+    );
+    deepStrictEqual(fetchMock.callHistory.calls(url).length, 0);
+  });
+
+  // A Codeberg Pages outage must not prevent expanding translation metadata.
+  // See: https://github.com/fedify-dev/fedify/issues/1214
+  fetchMock.get("https://w3id.org/fep/22cd", { status: 502 });
+  await t.step("preloaded FEP-22cd context", async () => {
+    const url = "https://w3id.org/fep/22cd";
+    const articleId = "https://example.com/articles/1";
+    const translatorId = "https://example.com/users/alice";
+    const revisionId = "https://example.com/articles/1/revisions/1";
+    deepStrictEqual(await fetchDocumentLoader(url), {
+      contextUrl: null,
+      documentUrl: url,
+      document: {
+        "@context": {
+          "fep-22cd": "https://w3id.org/fep/22cd#",
+          schema: "https://schema.org/",
+          xsd: "http://www.w3.org/2001/XMLSchema#",
+          translations: {
+            "@id": "fep-22cd:translations",
+            "@container": "@set",
+          },
+          Translation: "fep-22cd:Translation",
+          sourceUpdated: {
+            "@id": "fep-22cd:sourceUpdated",
+            "@type": "xsd:dateTime",
+          },
+          translator: {
+            "@id": "schema:translator",
+            "@type": "@id",
+            "@container": "@set",
+          },
+          inLanguage: "schema:inLanguage",
+          translationOfWork: {
+            "@id": "schema:translationOfWork",
+            "@type": "@id",
+          },
+          isBasedOn: { "@id": "schema:isBasedOn", "@type": "@id" },
+        },
+      },
+    });
+    deepStrictEqual(
+      await jsonld.expand({
+        "@context": ["https://www.w3.org/ns/activitystreams", url],
+        id: articleId,
+        type: "Article",
+        contentMap: { en: "Original", ko: "Translation" },
+        translations: [{
+          type: "Translation",
+          inLanguage: "ko",
+          translator: [translatorId],
+          translationOfWork: articleId,
+          sourceUpdated: "2026-09-01T00:00:00Z",
+          isBasedOn: revisionId,
+        }],
+      }, { documentLoader: fetchDocumentLoader }),
+      [{
+        "@id": articleId,
+        "@type": ["https://www.w3.org/ns/activitystreams#Article"],
+        "https://www.w3.org/ns/activitystreams#content": [
+          { "@language": "en", "@value": "Original" },
+          { "@language": "ko", "@value": "Translation" },
+        ],
+        "https://w3id.org/fep/22cd#translations": [{
+          "@type": ["https://w3id.org/fep/22cd#Translation"],
+          "https://schema.org/inLanguage": [{ "@value": "ko" }],
+          "https://schema.org/translator": [{ "@id": translatorId }],
+          "https://schema.org/translationOfWork": [{ "@id": articleId }],
+          "https://w3id.org/fep/22cd#sourceUpdated": [{
+            "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
+            "@value": "2026-09-01T00:00:00Z",
+          }],
+          "https://schema.org/isBasedOn": [{ "@id": revisionId }],
+        }],
+      }],
+    );
+    deepStrictEqual(fetchMock.callHistory.calls(url).length, 0);
+    deepStrictEqual(
+      fetchMock.callHistory.calls("https://www.w3.org/ns/activitystreams")
+        .length,
+      0,
+    );
+  });
+
+  await t.step("deny non-HTTP/HTTPS", async () => {
     await rejects(
       () => fetchDocumentLoader("ftp://localhost"),
       UrlError,
@@ -409,7 +557,7 @@ test("getDocumentLoader()", async (t) => {
     },
   });
 
-  await t.test("allowPrivateAddress: false", async () => {
+  await t.step("allowPrivateAddress: false", async () => {
     await rejects(
       () => fetchDocumentLoader("https://localhost/object"),
       UrlError,
@@ -426,7 +574,7 @@ test("getDocumentLoader()", async (t) => {
 
   const fetchDocumentLoader2 = getDocumentLoader({ allowPrivateAddress: true });
 
-  await t.test("allowPrivateAddress: true", async () => {
+  await t.step("allowPrivateAddress: true", async () => {
     const expected = {
       contextUrl: null,
       documentUrl: "https://localhost/object",
@@ -463,7 +611,7 @@ test("getDocumentLoader()", async (t) => {
     };
   });
 
-  await t.test("too many redirects", async () => {
+  await t.step("too many redirects", async () => {
     redirectAttempts = 0;
     await rejects(
       () => fetchDocumentLoader("https://example.com/too-many-redirects/0"),
@@ -489,7 +637,7 @@ test("getDocumentLoader()", async (t) => {
     };
   });
 
-  await t.test("redirect loop", async () => {
+  await t.step("redirect loop", async () => {
     loopAttempts = 0;
     await rejects(
       () => fetchDocumentLoader("https://example.com/redirect-loop-a"),
@@ -508,7 +656,7 @@ test("getDocumentLoader()", async (t) => {
     };
   });
 
-  await t.test("redirect loop with relative location", async () => {
+  await t.step("redirect loop with relative location", async () => {
     relativeLoopAttempts = 0;
     await rejects(
       () => fetchDocumentLoader("https://example.com/redirect-loop-relative"),
@@ -528,7 +676,7 @@ test("getDocumentLoader()", async (t) => {
     headers: { "Content-Type": "text/html; charset=utf-8" },
   });
 
-  await t.test("ReDoS resistance (CVE-2025-68475)", async () => {
+  await t.step("ReDoS resistance (CVE-2025-68475)", async () => {
     const start = performance.now();
     // The malicious HTML will fail JSON parsing, but the important thing is
     // that it should complete quickly (not hang due to ReDoS)
@@ -677,12 +825,13 @@ test("getDocumentLoader() logs DNS failures as such", async (t) => {
     "Deno" in globalThis &&
     (await Deno.permissions.query({ name: "net" })).state !== "granted"
   ) {
-    t.skip("requires the net permission");
-    return;
+    throw new Error(
+      "This DNS test requires Deno network permission (--allow-net).",
+    );
   }
   const loader = getDocumentLoader();
   for (const result of ["throws", "empty", "private"] as const) {
-    await t.test(result, async () => {
+    await t.step(result, async () => {
       // Stubbing works only because url.ts uses the default node:dns/promises
       // import; see the FIXME there.
       const originalLookup = dns.lookup;
@@ -738,7 +887,7 @@ test("getDocumentLoader() bounds alternate document chains", async (t) => {
   const loader = getDocumentLoader({ allowPrivateAddress: true });
   for (const mode of ["header", "html", "mixed"] as const) {
     for (const hops of [20, 21]) {
-      await t.test(`${mode}: ${hops} hops`, async () => {
+      await t.step(`${mode}: ${hops} hops`, async () => {
         fetchMock.mockGlobal();
         let requests = 0;
         fetchMock.get(`begin:${base}`, ({ url }) => {
@@ -783,7 +932,7 @@ test("getDocumentLoader() bounds alternate document chains", async (t) => {
       "redirect-intermediate",
     ]
   ) {
-    await t.test(`${mode}: cycle`, async () => {
+    await t.step(`${mode}: cycle`, async () => {
       fetchMock.mockGlobal();
       let requests = 0;
       fetchMock.get(`begin:${base}`, ({ url }) => {
@@ -817,49 +966,55 @@ test("getDocumentLoader() bounds alternate document chains", async (t) => {
     });
   }
 
-  await t.test("alternate followed by 20 redirects shares the limit", async () => {
-    fetchMock.mockGlobal();
-    let requests = 0;
-    fetchMock.get(`begin:${base}`, ({ url }) => {
-      requests++;
-      const index = Number(new URL(url).pathname.split("/").at(-1));
-      if (index === 21) return Response.json({ done: true });
-      return index === 0
-        ? alternate(`${base}1`, false)
-        : Response.redirect(`${base}${index + 1}`, 302);
-    });
-    try {
-      await rejects(loader(`${base}0`), (error: unknown) => {
-        ok(error instanceof FetchError);
-        ok(error.message.includes("Too many redirections (21)"));
-        return true;
+  await t.step(
+    "alternate followed by 20 redirects shares the limit",
+    async () => {
+      fetchMock.mockGlobal();
+      let requests = 0;
+      fetchMock.get(`begin:${base}`, ({ url }) => {
+        requests++;
+        const index = Number(new URL(url).pathname.split("/").at(-1));
+        if (index === 21) return Response.json({ done: true });
+        return index === 0
+          ? alternate(`${base}1`, false)
+          : Response.redirect(`${base}${index + 1}`, 302);
       });
-      deepStrictEqual(requests, 21);
-    } finally {
-      fetchMock.hardReset();
-    }
-  });
+      try {
+        await rejects(loader(`${base}0`), (error: unknown) => {
+          ok(error instanceof FetchError);
+          ok(error.message.includes("Too many redirections (21)"));
+          return true;
+        });
+        deepStrictEqual(requests, 21);
+      } finally {
+        fetchMock.hardReset();
+      }
+    },
+  );
 
-  await t.test("relative alternate after redirect and isolated calls", async () => {
-    fetchMock.mockGlobal();
-    fetchMock.get(`${base}start`, Response.redirect(`${base}html`, 302));
-    fetchMock.get(`${base}html`, alternate("./document", true));
-    fetchMock.get(`${base}document`, Response.json({ done: true }));
-    try {
-      for (let i = 0; i < 2; i++) {
-        const results = await Promise.all([
-          loader(`${base}start`),
-          loader(`${base}start`),
-        ]);
-        for (const result of results) {
-          deepStrictEqual(result.document, { done: true });
-          deepStrictEqual(result.documentUrl, `${base}document`);
+  await t.step(
+    "relative alternate after redirect and isolated calls",
+    async () => {
+      fetchMock.mockGlobal();
+      fetchMock.get(`${base}start`, Response.redirect(`${base}html`, 302));
+      fetchMock.get(`${base}html`, alternate("./document", true));
+      fetchMock.get(`${base}document`, Response.json({ done: true }));
+      try {
+        for (let i = 0; i < 2; i++) {
+          const results = await Promise.all([
+            loader(`${base}start`),
+            loader(`${base}start`),
+          ]);
+          for (const result of results) {
+            deepStrictEqual(result.document, { done: true });
+            deepStrictEqual(result.documentUrl, `${base}document`);
+          }
         }
+      } finally {
+        fetchMock.hardReset();
       }
-    } finally {
-      fetchMock.hardReset();
-    }
-  });
+    },
+  );
 
   function alternate(next: string, html: boolean): Response {
     return html
@@ -882,7 +1037,7 @@ test("getDocumentLoader() preserves cancellation across alternates", async (t) =
   const base = "https://example.com/alternate-abort/";
   const loader = getDocumentLoader({ allowPrivateAddress: true });
   for (const html of [false, true]) {
-    await t.test(html ? "HTML" : "Link header", async () => {
+    await t.step(html ? "HTML" : "Link header", async () => {
       fetchMock.mockGlobal();
       const controller = new AbortController();
       let requests = 0;

package/src/docloader.ts

@@ -281,6 +281,8 @@ export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
  * - <https://w3id.org/security/multikey/v1>
  * - <https://w3id.org/fep/ef61>
  * - <https://w3id.org/fep/7aa9>
+ * - <https://w3id.org/fep/6757>
+ * - <https://w3id.org/fep/22cd>
  * - <https://purl.archive.org/socialweb/webfinger>
  * - <http://schema.org/>
  * @param options Options for the document loader.

package/src/langstr.test.ts

@@ -1,4 +1,4 @@
-import { deepStrictEqual } from "node:assert";
+import { deepStrictEqual, throws } from "node:assert";
 import { test } from "node:test";
 import util from "node:util";
 import { LanguageString } from "./langstr.ts";
@@ -11,6 +11,23 @@ test("new LanguageString()", () => {
   deepStrictEqual(new LanguageString("Hello", new Intl.Locale("en")), langStr);
 });
 
+test("new LanguageString() with extlang tags", () => {
+  // Intl.Locale objects have no own enumerable properties, so their base names
+  // are compared instead:
+  deepStrictEqual(new LanguageString("你好", "zh-YUE").locale.baseName, "yue");
+  deepStrictEqual(
+    new LanguageString("你好", "zh-yue-HK").locale.baseName,
+    "yue-HK",
+  );
+  // Whether cmn is canonicalized to zh depends on the runtime:
+  deepStrictEqual(
+    new LanguageString("你好", "zh-cmn-Hant").locale.baseName,
+    new Intl.Locale("cmn-Hant").baseName,
+  );
+  throws(() => new LanguageString("Hello", "en-USA"), RangeError);
+  throws(() => new LanguageString("你好", "zh-yue-"), RangeError);
+});
+
 test("Deno.inspect(LanguageString)", () => {
   const langStr = new LanguageString("Hello, 'world'", "en");
   deepStrictEqual(

package/src/langstr.ts

@@ -1,3 +1,5 @@
+import { normalizeLanguageTag } from "./langtag.ts";
+
 /**
  * A language-tagged string which corresponds to the `rdf:langString` type.
  */
@@ -12,12 +14,14 @@ export class LanguageString extends String {
    * Constructs a new `LanguageString`.
    * @param value A string value written in the given language.
    * @param language The language of the string.  If a string is given, it will
-   *                 be parsed as a `Intl.Locale` object.
+   *                 be parsed as a `Intl.Locale` object.  Extended language
+   *                 subtags are normalized first, e.g., `zh-yue` is parsed as
+   *                 `yue`.
    */
   constructor(value: string, language: Intl.Locale | string) {
     super(value);
     this.locale = typeof language === "string"
-      ? new Intl.Locale(language)
+      ? new Intl.Locale(normalizeLanguageTag(language))
       : language;
   }
 }

package/src/langtag.test.ts

@@ -0,0 +1,53 @@
+import { deepStrictEqual } from "node:assert";
+import { test } from "node:test";
+import { normalizeLanguageTag } from "./langtag.ts";
+
+test("normalizeLanguageTag() removes extlang subtags", () => {
+  const cases: [string, string][] = [
+    ["zh-yue", "yue"],
+    ["zh-YUE", "yue"],
+    ["ZH-Yue-hk", "yue-hk"],
+    ["zh-yue-HK", "yue-HK"],
+    ["zh-cmn-Hant", "cmn-Hant"],
+    ["zh-yue-u-nu-hanidec", "yue-u-nu-hanidec"],
+    ["sgn-ase", "ase"],
+    ["ar-arz", "arz"],
+    ["ms-zlm", "zlm"],
+    ["kok-gom", "gom"],
+    ["koK-gom", "gom"],
+    ["lv-ltg", "ltg"],
+    ["sw-swc", "swc"],
+    ["uz-uzs", "uzs"],
+    // Valid tags never have more than one extlang, so only the first one is
+    // removed and the result is still rejected by Intl.Locale:
+    ["zh-yue-cmn", "yue-cmn"],
+    ["zh-yue-", "yue-"],
+  ];
+  for (const [input, expected] of cases) {
+    deepStrictEqual(normalizeLanguageTag(input), expected, input);
+  }
+});
+
+test("normalizeLanguageTag() leaves other tags unchanged", () => {
+  const tags = [
+    "",
+    "en",
+    "en-US",
+    "en-USA",
+    "en-yue",
+    "zh",
+    "zh-Hant-TW",
+    "yue",
+    "yue-HK",
+    "x-private",
+    "i-klingon",
+    "zh-min-nan",
+    "koK-gom",
+    "zh-yuK",
+    "constructor-yue",
+    "toString-yue",
+  ];
+  for (const tag of tags) {
+    deepStrictEqual(normalizeLanguageTag(tag), tag, tag);
+  }
+});

package/src/langtag.ts

@@ -0,0 +1,76 @@
+/**
+ * Extended language subtags (extlangs) registered in the IANA Language Subtag
+ * Registry, grouped by their prefixes.  Every extlang record has exactly one
+ * prefix and a `Preferred-Value` equal to the extlang subtag itself, so
+ * replacing the prefix and the extlang with the extlang alone yields
+ * the canonical form.
+ *
+ * Generated from the registry with File-Date: 2026-09-17.
+ */
+const EXTLANGS: Record<string, string> = {
+  ar: "aao abh abv acm acq acw acx acy adf aeb aec afb ajp apc apd arb arq " +
+    "ars ary arz auz avl ayh ayl ayn ayp bbz pga shu ssh",
+  kok: "gom knn",
+  lv: "ltg lvs",
+  ms: "bjn btj bve bvu coa dup hji jak jax kvb kvr kxd lce lcf liw max meo " +
+    "mfa mfb min mqg msi mui orn ors pel pse tmw urk vkk vkt xmm zlm zmi " +
+    "zsm",
+  sgn: "ads aed aen afg ajs ase asf asp asq asw bfi bfk bog bqn bqy bvl bzs " +
+    "cds csc csd cse csf csg csl csn csq csr csx doq dse dsl dsz dyl ecs " +
+    "ehs esl esn eso eth fcs fse fsl fss gds gse gsg gsm gss gus hab haf " +
+    "hds hks hos hps hsh hsl icl iks ils inl ins ise isg isr jcs jhs jks " +
+    "jls jos jsl jus kgi kvk lbs lgs lls lsb lsc lsg lsl lsn lso lsp lst " +
+    "lsv lsw lsy lws mdl mfs mre msd msr mzc mzg mzy nbs ncs nsi nsl nsp " +
+    "nsr nzs okl pgz pks prl prz psc psd psg psl pso psp psr pys rib rms " +
+    "rnb rsi rsl rsm rsn sdl sfb sfs sgg sgx slf sls sqk sqs sqx ssp ssr " +
+    "svk swl syy szs tse tsm tsq tss tsy tza ugn ugy ukl uks vgt vsi vsl " +
+    "vsv wbs xki xml xms yds ygs yhs ysl ysm zhk zib zsl",
+  sw: "swc swh",
+  uz: "uzn uzs",
+  zh: "cdo cjy cmn cnp cpx csp czh czo gan hak hnm hsn luh lzh mnp nan sjc " +
+    "wuu yue",
+};
+
+const EXTLANG_PAIRS: ReadonlySet<string> = new Set(
+  Object.entries(EXTLANGS).flatMap(([prefix, extlangs]) =>
+    extlangs.split(" ").map((extlang) => `${prefix}-${extlang}`)
+  ),
+);
+
+const PREFIX_PATTERN = /^[A-Za-z]{2,3}$/;
+const EXTLANG_PATTERN = /^[A-Za-z]{3}$/;
+
+/**
+ * Normalizes a BCP 47 language tag that has an extended language subtag
+ * (extlang), such as `zh-yue`, into its canonical form, such as `yue`, as
+ * described in [RFC 5646, Section 4.5][1].  `Intl.Locale` rejects extlang
+ * tags, so tags should be normalized before being passed to it.
+ *
+ * Only registered extlangs that follow their registered prefix are removed;
+ * any other tag is returned unchanged, so the result still needs to be
+ * validated, e.g., by `Intl.Locale`.
+ *
+ * NOTE: This function is marked as internal in the 2.0.x–2.4.x patch
+ * releases.  When merging it into the *main* branch, remove the `@internal`
+ * tag, formalize it as a public API (`@since 2.5.0`), and add it to
+ * the changelog fragment.
+ *
+ * [1]: https://www.rfc-editor.org/rfc/rfc5646.html#section-4.5
+ *
+ * @param tag The BCP 47 language tag to normalize.
+ * @returns The normalized language tag.
+ * @internal
+ */
+export function normalizeLanguageTag(tag: string): string {
+  const subtags = tag.split("-");
+  if (subtags.length < 2) return tag;
+  const [prefix, extlang, ...rest] = subtags;
+  // Checked before case folding, since `toLowerCase()` maps some non-ASCII
+  // characters (e.g., U+212A KELVIN SIGN) to ASCII letters:
+  if (!PREFIX_PATTERN.test(prefix) || !EXTLANG_PATTERN.test(extlang)) {
+    return tag;
+  }
+  const language = extlang.toLowerCase();
+  if (!EXTLANG_PAIRS.has(`${prefix.toLowerCase()}-${language}`)) return tag;
+  return [language, ...rest].join("-");
+}