@ingram-tech/nk-seo 0.8.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -156,21 +156,35 @@ needed — each is merged into the generated object and wins on conflict. With
156
156
  `titleTemplate` set, `pageMetadata.root()` emits `title.template`, so plain page
157
157
  titles render as "Services | Acme" without every page appending the suffix.
158
158
 
159
- On a localized site the per-page `alternates` and `locale` are what make the
160
- factory usable — `alternates.languages` is what Next renders as
161
- `<link rel="alternate" hreflang>`, and `og:locale` has to vary per page:
159
+ On a localized site give the factory the locale cluster once and every page
160
+ emits its `alternates.languages` (what Next renders as
161
+ `<link rel="alternate" hreflang>`, `x-default` included) and a canonical that
162
+ follows the address. `@ingram-tech/nk-i18n`'s routing object fits as-is:
162
163
 
163
164
  ```ts
164
- import { hreflangAlternates } from "@ingram-tech/nk-seo";
165
+ export const pageMetadata = createMetadata({
166
+ baseUrl: routing.baseUrl,
167
+ siteName: "Acme",
168
+ hreflang: routing, // or { locales, strategy, param, hrefLangTags }
169
+ });
165
170
 
166
- const { languages } = hreflangAlternates(HREFLANG_CONFIG, `/${locale}/about`);
171
+ // A dynamic page: the URL locale makes the canonical self-reference /fr/about.
167
172
  return pageMetadata({
168
- title, description, path: `/${locale}/about`,
169
- alternates: { languages },
170
- locale: "fr_BE", // overrides the site-wide `locale`
173
+ title, description, path: "/about",
174
+ urlLocale: await getUrlLocale(routing), // from "@ingram-tech/nk-i18n/next"
175
+ locale: "fr_BE", // og:locale, overrides the site-wide one
171
176
  });
177
+
178
+ // A static page (`force-static`): one document for every visitor, so no
179
+ // `urlLocale` — it canonicalizes to the bare, x-default address.
180
+ return pageMetadata({ title, description, path: `/posts/${slug}` });
172
181
  ```
173
182
 
183
+ This is the wiring to prefer over `<HreflangLinks>`: it needs no request
184
+ header, so it works on statically rendered routes, and there is nothing to
185
+ forget in middleware. Reach for the component, or the pure `hreflangAlternates`,
186
+ only on pages that don't go through `pageMetadata`.
187
+
174
188
  ## Sitemap & robots
175
189
 
176
190
  ```ts
@@ -295,9 +309,14 @@ return NextResponse.next({ request: { headers: requestHeaders } });
295
309
  ```
296
310
 
297
311
  Copying `req.headers` first also overwrites any client-spoofed `x-pathname`.
298
- Note that reading the header (`headers()`) opts the page into dynamic
299
- rendering — pass `pathname` explicitly (e.g. from route params) on pages that
300
- must stay static.
312
+ Reading the header (`headers()`) opts the page into dynamic rendering, and on a
313
+ route that is already static (`force-static`, no request-time reads) the header
314
+ is simply empty — so a `<HreflangLinks>` in the root layout **throws under any
315
+ static page**. Sites with static routes should emit hreflang from metadata
316
+ instead (`createMetadata({ hreflang })`, above), which needs no header at all;
317
+ short of that, pass `pathname` explicitly from route params on the page itself
318
+ (React hoists `<link>` into `<head>` from anywhere in the tree) and keep the
319
+ header-reading instance out of layouts that static routes share.
301
320
 
302
321
  ```tsx
303
322
  import { HreflangLinks } from "@ingram-tech/nk-seo/components";
@@ -316,21 +335,12 @@ import { HreflangLinks } from "@ingram-tech/nk-seo/components";
316
335
  />
317
336
  ```
318
337
 
319
- Sites that prefix **every** locale — where `/about` redirects to `/en/about`
320
- and no bare path exists — pass `prefixDefaultLocale`, which prefixes the default
321
- locale too and points `x-default` at that prefixed URL. Without it the bare path
322
- is emitted for both `en` and `x-default`, annotating URLs that redirect (Google
323
- wants every hreflang target to answer 200 directly).
324
-
325
- ```tsx
326
- <HreflangLinks
327
- baseUrl="https://example.com"
328
- locales={["en", "fr", "nl"]}
329
- strategy="prefix"
330
- defaultLocale="en"
331
- prefixDefaultLocale
332
- />
333
- ```
338
+ The cluster's **shape** is fixed and not configurable: every locale gets its own
339
+ address, the default included, and the bare path belongs to no locale — it is
340
+ the negotiating entry point that `x-default` names. `strategy` picks only the
341
+ encoding. `@ingram-tech/nk-i18n`'s `defineLocaleRouting` produces a valid config
342
+ for this, and `hreflangConfigFor(routing)` fills in `currentLocale` and the
343
+ pathname header correctly; prefer that over assembling a config by hand.
334
344
 
335
345
  Pass `pathname` explicitly if you don't use the `x-pathname` header. When
336
346
  neither is available the component **throws** instead of guessing — a silent
@@ -351,11 +361,11 @@ Two rules of the road:
351
361
  strategy can't see the query string server-side, so
352
362
  [`hreflangConfigFor(routing)`](../nk-i18n/README.md) from
353
363
  `@ingram-tech/nk-i18n/next` is the wiring that gets this right for you.
354
- - Building metadata instead of rendering links? The pure `hreflangAlternates`
355
- (package root) returns the same links for use in `generateMetadata`:
364
+ - Building metadata instead of rendering links? `createMetadata({ hreflang })`
365
+ does it on every page; the pure `hreflangAlternates` (package root) returns
366
+ the same links for a hand-rolled `generateMetadata`:
356
367
  `{ canonical, links, languages }`, where `languages` is already keyed by
357
- hreflang for `Metadata.alternates.languages` (or `createMetadata`'s
358
- per-page `alternates`).
368
+ hreflang for `Metadata.alternates.languages`.
359
369
 
360
370
  ## Verifying the cluster (`/verify`)
361
371
 
@@ -10,42 +10,35 @@ export interface HreflangConfig {
10
10
  locales: readonly string[];
11
11
  /**
12
12
  * How locale is encoded in the alternate URLs:
13
- * - `"query"` (default): `${baseUrl}${path}?${param}=${locale}` for every locale.
14
- * - `"prefix"`: the default locale stays at the bare path; others get
15
- * `/${locale}${path}` (matches a localized-rewrite setup). Set
16
- * {@link HreflangConfig.prefixDefaultLocale} for sites that prefix every
17
- * locale instead.
13
+ * - `"query"` (default): `${baseUrl}${path}?${param}=${locale}`
14
+ * - `"prefix"`: `/${locale}${path}`
15
+ *
16
+ * The cluster's SHAPE is the same either way and is not configurable: every
17
+ * locale gets its own address, the default included, and the bare path
18
+ * belongs to no locale — it is the negotiating entry point that `x-default`
19
+ * names. `@ingram-tech/nk-i18n`'s `defineLocaleRouting` produces a valid
20
+ * config for this; prefer passing that over assembling one by hand.
18
21
  */
19
22
  strategy?: "query" | "prefix";
20
23
  /** Query-param name for the `"query"` strategy. Default `"hl"`. */
21
24
  param?: string;
22
- /** Default locale. Required for `"prefix"`; it is what `x-default` resolves to. */
23
- defaultLocale?: string;
24
- /**
25
- * `"prefix"` only: prefix the default locale too (`/en/about`, never
26
- * `/about`), and point `x-default` at that prefixed URL. For sites whose
27
- * locale negotiation redirects every bare path — emitting the bare path as
28
- * an alternate would annotate a URL that 3xx-redirects, which is the bug the
29
- * mandatory `defaultLocale` exists to prevent.
30
- */
31
- prefixDefaultLocale?: boolean;
32
25
  /**
33
26
  * The locale **the URL names**, which is not always the locale that rendered.
34
27
  * It determines the self-referencing canonical, and a canonical is a claim
35
- * about an address: under `"query"`, `/pricing` canonicalizes to `/pricing`
36
- * even while content negotiation renders it in French for a French visitor,
37
- * because `/pricing` is the negotiating entry point and belongs to no locale.
38
- * Passing the negotiated locale here instead makes the bare path claim to be
39
- * the French URL, and the real French URL then looks like a duplicate.
28
+ * about an address: `/pricing` canonicalizes to `/pricing` even while content
29
+ * negotiation renders it in French for a French visitor, because `/pricing`
30
+ * belongs to no locale. Passing the negotiated locale here instead makes the
31
+ * bare path claim to be the French URL, and the real French URL then looks
32
+ * like a duplicate of it.
40
33
  *
41
- * Leave it unset on a negotiating bare path. Under `"prefix"` it is detected
42
- * from the pathname; under `"query"` the server cannot see the query string,
43
- * so pass it — `hreflangConfigFor(routing)` from
44
- * "@ingram-tech/nk-i18n/next" fills it in correctly.
34
+ * Leave it unset on the bare path. Under `"prefix"` it is detected from the
35
+ * pathname; under `"query"` the server cannot see the query string, so pass
36
+ * it — `hreflangConfigFor(routing)` from "@ingram-tech/nk-i18n/next" fills it
37
+ * in correctly.
45
38
  */
46
39
  currentLocale?: string;
47
40
  /** Optional locale → hreflang tag map, e.g. `{ en: "en-BE", fr: "fr-BE" }`. */
48
- hrefLangTags?: Record<string, string>;
41
+ hrefLangTags?: Readonly<Partial<Record<string, string>>>;
49
42
  }
50
43
  export interface HreflangLink {
51
44
  /** The `hreflang` attribute value ("fr-BE", "x-default", …). */
@@ -1 +1 @@
1
- {"version":3,"file":"alternates.d.ts","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC5B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IAClC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACd,kBAAkB,CAuFpB"}
1
+ {"version":3,"file":"alternates.d.ts","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,YAAY;IAC5B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IAClC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACd,kBAAkB,CAuDpB"}
@@ -4,18 +4,10 @@ import { absoluteUrl } from "./url.js";
4
4
  * URLs (and an `x-default`) for `pathname`.
5
5
  */
6
6
  export function hreflangAlternates(config, pathname) {
7
- const { strategy = "query", param = "hl", defaultLocale, prefixDefaultLocale, hrefLangTags, } = config;
8
- if (strategy === "prefix" && !defaultLocale) {
9
- // Without it canonical/x-default point at a bare path that is no
10
- // locale's URL — a silent SEO bug. (With `prefixDefaultLocale` no bare
11
- // path is emitted at all, but x-default still has to resolve to *some*
12
- // locale, so the requirement stands.)
13
- throw new Error("hreflangAlternates: `defaultLocale` is required for the prefix strategy.");
14
- }
15
- // Prefix strategy: accept both the bare and the locale-prefixed form of the
16
- // path (middleware's `x-pathname` carries the latter on a real localized
17
- // route — blindly prepending would emit /fr/fr/about) and detect the
18
- // current locale from it.
7
+ const { strategy = "query", param = "hl", hrefLangTags } = config;
8
+ // Accept both the bare and the locale-prefixed form of the path (middleware's
9
+ // `x-pathname` carries the latter on a real localized route — blindly
10
+ // prepending would emit /fr/fr/about) and detect the current locale from it.
19
11
  let basePath = pathname;
20
12
  let currentLocale = config.currentLocale;
21
13
  if (strategy === "prefix") {
@@ -26,46 +18,30 @@ export function hreflangAlternates(config, pathname) {
26
18
  break;
27
19
  }
28
20
  }
29
- currentLocale ??= defaultLocale;
21
+ // Deliberately no fallback to a default locale: a bare path names none.
30
22
  }
31
- /** The bare (locale-free) URL of the path. */
23
+ /** The bare (locale-free) URL — the negotiating entry point, `x-default`. */
32
24
  const bareUrl = absoluteUrl(basePath, config.baseUrl);
33
- const prefixedUrl = (locale) => absoluteUrl(`/${locale}${basePath === "/" ? "" : basePath}`, config.baseUrl);
25
+ /** Every locale has its own address, the default included. */
34
26
  const hrefFor = (locale) => {
35
27
  if (strategy === "prefix") {
36
- if (locale === defaultLocale && !prefixDefaultLocale)
37
- return bareUrl;
38
- return prefixedUrl(locale);
28
+ return absoluteUrl(`/${locale}${basePath === "/" ? "" : basePath}`, config.baseUrl);
39
29
  }
40
30
  return `${bareUrl}${bareUrl.includes("?") ? "&" : "?"}${param}=${locale}`;
41
31
  };
42
- /** x-default: the default locale's own URL, prefixed or not. */
43
- const defaultUrl = strategy === "prefix" && prefixDefaultLocale && defaultLocale
44
- ? prefixedUrl(defaultLocale)
45
- : bareUrl;
46
- // Self-referencing canonical: the current variant's own URL. Canonicalizing
47
- // a localized variant to the bare path makes Google treat the variants as
48
- // duplicates and ignore the hreflang annotations entirely.
49
- //
50
- // Whether the default locale has a URL of its own is strategy-dependent, and
51
- // conflating the two is a silent way to delete the default locale from the
52
- // cluster. Under `"prefix"` it shares the bare path (unless every locale is
53
- // prefixed), so its canonical IS the bare path. Under `"query"` every locale
54
- // gets its own `?param=` address and the bare path belongs to none of them:
55
- // it is the negotiating entry point that `x-default` names. So `?hl=en` must
56
- // canonicalize to `?hl=en`, never to the bare path.
57
- const defaultLocaleOwnsBarePath = strategy === "prefix" && !prefixDefaultLocale;
58
- const canonical = currentLocale &&
59
- config.locales.includes(currentLocale) &&
60
- !(defaultLocaleOwnsBarePath && currentLocale === defaultLocale)
32
+ // Self-referencing canonical: the current variant's own URL, or the bare path
33
+ // when the URL names no locale. Canonicalizing a localized variant to the
34
+ // bare path makes Google treat the variants as duplicates and ignore the
35
+ // hreflang annotations entirely.
36
+ const canonical = currentLocale && config.locales.includes(currentLocale)
61
37
  ? hrefFor(currentLocale)
62
- : defaultUrl;
38
+ : bareUrl;
63
39
  const links = [
64
40
  ...config.locales.map((locale) => ({
65
41
  hrefLang: hrefLangTags?.[locale] ?? locale,
66
42
  href: hrefFor(locale),
67
43
  })),
68
- { hrefLang: "x-default", href: defaultUrl },
44
+ { hrefLang: "x-default", href: bareUrl },
69
45
  ];
70
46
  return {
71
47
  canonical,
@@ -1 +1 @@
1
- {"version":3,"file":"alternates.js","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"alternates.js","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAgEvC;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CACjC,MAAsB,EACtB,QAAgB;IAEhB,MAAM,EAAE,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,IAAI,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAElE,8EAA8E;IAC9E,sEAAsE;IACtE,6EAA6E;IAC7E,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,IAAI,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IACzC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC3B,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,QAAQ,KAAK,IAAI,MAAM,EAAE,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrE,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;gBACpD,aAAa,KAAK,MAAM,CAAC;gBACzB,MAAM;YACP,CAAC;QACF,CAAC;QACD,wEAAwE;IACzE,CAAC;IAED,6EAA6E;IAC7E,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAEtD,8DAA8D;IAC9D,MAAM,OAAO,GAAG,CAAC,MAAc,EAAU,EAAE;QAC1C,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC3B,OAAO,WAAW,CACjB,IAAI,MAAM,GAAG,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,EAC/C,MAAM,CAAC,OAAO,CACd,CAAC;QACH,CAAC;QACD,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,IAAI,MAAM,EAAE,CAAC;IAC3E,CAAC,CAAC;IAEF,8EAA8E;IAC9E,0EAA0E;IAC1E,yEAAyE;IACzE,iCAAiC;IACjC,MAAM,SAAS,GACd,aAAa,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;QACtD,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;QACxB,CAAC,CAAC,OAAO,CAAC;IAEZ,MAAM,KAAK,GAAG;QACb,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAClC,QAAQ,EAAE,YAAY,EAAE,CAAC,MAAM,CAAC,IAAI,MAAM;YAC1C,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC;SACrB,CAAC,CAAC;QACH,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE;KACxC,CAAC;IAEF,OAAO;QACN,SAAS;QACT,KAAK;QACL,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;KAC9E,CAAC;AACH,CAAC"}
@@ -11,9 +11,12 @@ export interface HreflangLinksProps extends HreflangConfig {
11
11
  * return NextResponse.next({ request: { headers: requestHeaders } });
12
12
  * ```
13
13
  *
14
- * Pass explicitly if you don't use that header (e.g. from route params) —
15
- * also the only way to keep the page statically renderable, since reading
16
- * `headers()` opts the page into dynamic rendering.
14
+ * Pass explicitly if you don't use that header (e.g. from route params).
15
+ * On a statically rendered route the header is empty (and reading it would
16
+ * otherwise opt the page into dynamic rendering), so a header-reading
17
+ * instance cannot sit in a layout shared with static pages — prefer
18
+ * `createMetadata({ hreflang })`, which emits the same cluster from metadata
19
+ * without any request header.
17
20
  */
18
21
  pathname?: string;
19
22
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"hreflang.d.ts","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,EACnC,QAAQ,EACR,SAAgB,EAChB,GAAG,MAAM,EACT,EAAE,kBAAkB,wCA4BpB"}
1
+ {"version":3,"file":"hreflang.d.ts","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,EACnC,QAAQ,EACR,SAAgB,EAChB,GAAG,MAAM,EACT,EAAE,kBAAkB,wCA4BpB"}
@@ -1 +1 @@
1
- {"version":3,"file":"hreflang.js","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,iBAAiB,CAAC;AA2B1E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EACnC,QAAQ,EACR,SAAS,GAAG,IAAI,EAChB,GAAG,MAAM,EACW;IACpB,MAAM,IAAI,GAAG,QAAQ,IAAI,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC7D,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACd,wEAAwE;YACvE,kDAAkD;YAClD,kFAAkF;YAClF,4DAA4D;YAC5D,iFAAiF,CAClF,CAAC;IACH,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5E,OAAO,CACN,8BACE,SAAS,CAAC,CAAC,CAAC,eAAM,GAAG,EAAC,WAAW,EAAC,IAAI,EAAE,YAAY,GAAI,CAAC,CAAC,CAAC,IAAI,EAC/D,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACpB,eAIC,GAAG,EAAC,WAAW,EACf,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,IAAI,EAAE,IAAI,CAAC,IAAI,IAHV,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAInC,CACF,CAAC,IACA,CACH,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"hreflang.js","sourceRoot":"","sources":["../src/hreflang.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,iBAAiB,CAAC;AA8B1E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EACnC,QAAQ,EACR,SAAS,GAAG,IAAI,EAChB,GAAG,MAAM,EACW;IACpB,MAAM,IAAI,GAAG,QAAQ,IAAI,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC7D,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACd,wEAAwE;YACvE,kDAAkD;YAClD,kFAAkF;YAClF,4DAA4D;YAC5D,iFAAiF,CAClF,CAAC;IACH,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5E,OAAO,CACN,8BACE,SAAS,CAAC,CAAC,CAAC,eAAM,GAAG,EAAC,WAAW,EAAC,IAAI,EAAE,YAAY,GAAI,CAAC,CAAC,CAAC,IAAI,EAC/D,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACpB,eAIC,GAAG,EAAC,WAAW,EACf,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,IAAI,EAAE,IAAI,CAAC,IAAI,IAHV,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAInC,CACF,CAAC,IACA,CACH,CAAC;AACH,CAAC"}
@@ -1,4 +1,5 @@
1
1
  import type { Metadata } from "next";
2
+ import { type HreflangConfig } from "./alternates.js";
2
3
  /**
3
4
  * Per-site defaults for {@link createMetadata}. Set once, reuse on every page.
4
5
  */
@@ -25,6 +26,15 @@ export interface MetadataSiteConfig {
25
26
  twitterSite?: string;
26
27
  /** Twitter `@handle` for `creator`. */
27
28
  twitterCreator?: string;
29
+ /**
30
+ * Locale cluster for the site. When set, every `pageMetadata()` call emits
31
+ * the per-locale `alternates.languages` (plus `x-default`) and a canonical
32
+ * that follows the address — the same links `<HreflangLinks>` renders, but
33
+ * from metadata, so it works on statically rendered routes too (there is no
34
+ * request header to read there) and needs no middleware wiring.
35
+ * `@ingram-tech/nk-i18n`'s routing object fits directly: `hreflang: routing`.
36
+ */
37
+ hreflang?: Omit<HreflangConfig, "baseUrl" | "currentLocale">;
28
38
  }
29
39
  /** Per-page inputs for the bound `pageMetadata` function. */
30
40
  export interface PageMetadataInput {
@@ -42,11 +52,21 @@ export interface PageMetadataInput {
42
52
  * on a multilingual site `og:locale` has to vary per page.
43
53
  */
44
54
  locale?: string;
55
+ /**
56
+ * With `site.hreflang` set: the locale **the URL names** (not the one that
57
+ * rendered), so the canonical self-references the localized address. Get it
58
+ * from `getUrlLocale(routing)` (`@ingram-tech/nk-i18n/next`) on dynamic
59
+ * pages; leave it unset on the bare path and on static routes, which serve
60
+ * one document for every visitor and so canonicalize to the bare, `x-default`
61
+ * address. Under the prefix strategy a `/fr/…`-prefixed `path` implies it.
62
+ */
63
+ urlLocale?: string;
45
64
  /**
46
65
  * Merged into the generated `alternates` (wins on conflict). The reason it
47
66
  * exists: `alternates.languages` is per-page on a localized site, and
48
- * spreading the result to bolt it on drops the rest of the object.
49
- * `hreflangAlternates()` returns a ready-made `languages` map.
67
+ * spreading the result to bolt it on drops the rest of the object. Prefer
68
+ * `site.hreflang`, which fills it in on every page; `hreflangAlternates()`
69
+ * returns a ready-made `languages` map for the hand-rolled case.
50
70
  */
51
71
  alternates?: Partial<NonNullable<Metadata["alternates"]>>;
52
72
  /** Merged into the generated `openGraph` (wins on conflict). */
@@ -1 +1 @@
1
- {"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAGrC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1D,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACxD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB;YAGzB,iBAAiB,GAAG,QAAQ;mBAgDR,iBAAiB,KAAQ,QAAQ;EAalF;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB;;;;;IAS1D"}
1
+ {"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG1E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,eAAe,CAAC,CAAC;CAC7D;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1D,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACxD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB;YAGzB,iBAAiB,GAAG,QAAQ;mBAgER,iBAAiB,KAAQ,QAAQ;EAalF;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB;;;;;IAS1D"}
package/dist/metadata.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { hreflangAlternates } from "./alternates.js";
1
2
  import { absoluteUrl } from "./url.js";
2
3
  /**
3
4
  * Returns a `pageMetadata(input)` builder that produces a Next `Metadata`
@@ -26,14 +27,27 @@ export function createMetadata(site) {
26
27
  function pageMetadata(input) {
27
28
  const imagePath = input.image ?? site.defaultImage;
28
29
  const imageUrl = imagePath ? absolute(imagePath) : undefined;
29
- const url = absolute(input.path);
30
+ // With a locale cluster the canonical is the current variant's own address
31
+ // (and og:url must agree with it); otherwise the path as given.
32
+ const hreflang = site.hreflang
33
+ ? hreflangAlternates({
34
+ ...site.hreflang,
35
+ baseUrl: site.baseUrl,
36
+ currentLocale: input.urlLocale,
37
+ }, input.path)
38
+ : undefined;
39
+ const url = hreflang?.canonical ?? absolute(input.path);
30
40
  const locale = input.locale ?? site.locale;
31
41
  return {
32
42
  metadataBase: new URL(site.baseUrl),
33
43
  title: input.title,
34
44
  description: input.description,
35
45
  ...(input.keywords ? { keywords: input.keywords } : {}),
36
- alternates: { canonical: url, ...input.alternates },
46
+ alternates: {
47
+ canonical: url,
48
+ ...(hreflang ? { languages: hreflang.languages } : {}),
49
+ ...input.alternates,
50
+ },
37
51
  // noindex but follow: keep link equity flowing through the page. Use a
38
52
  // full robots override in the page's own metadata for nofollow too.
39
53
  ...(input.noIndex ? { robots: { index: false, follow: true } } : {}),
@@ -1 +1 @@
1
- {"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAoEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACtD,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE3E,SAAS,YAAY,CAAC,KAAwB;QAC7C,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QACnD,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;QAE3C,OAAO;YACN,YAAY,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YACnC,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,UAAU,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE;YACnD,uEAAuE;YACvE,oEAAoE;YACpE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,SAAS,EAAE;gBACV,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,SAAS;gBAC7B,GAAG;gBACH,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7B,GAAG,CAAC,QAAQ;oBACX,CAAC,CAAC;wBACA,MAAM,EAAE;4BACP;gCACC,GAAG,EAAE,QAAQ;gCACb,KAAK,EAAE,IAAI,CAAC,iBAAiB,IAAI,IAAI;gCACrC,MAAM,EAAE,IAAI,CAAC,kBAAkB,IAAI,GAAG;gCACtC,GAAG,EAAE,KAAK,CAAC,KAAK;6BAChB;yBACD;qBACD;oBACF,CAAC,CAAC,EAAE,CAAC;gBACN,GAAG,KAAK,CAAC,SAAS;aAClB;YACD,OAAO,EAAE;gBACR,IAAI,EAAE,qBAAqB;gBAC3B,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,GAAG,KAAK,CAAC,OAAO;aAChB;SACD,CAAC;IACH,CAAC;IAED,YAAY,CAAC,IAAI,GAAG,SAAS,YAAY,CAAC,KAAK,GAAsB,EAAE;QACtE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC;QAC3C,OAAO;YACN,YAAY,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YACnC,KAAK,EAAE,IAAI,CAAC,aAAa;gBACxB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE;gBAClD,CAAC,CAAC,KAAK;YACR,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,KAAK,CAAC,SAAS;SAClB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,YAAY,CAAC;AACrB,CAAC;AAoBD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IAC1D,OAAO;QACN;YACC,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;YAC3C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG;YAC3B,GAAG,EAAE,KAAK,CAAC,GAAG;SACd;KACD,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAuB,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAuFvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACtD,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE3E,SAAS,YAAY,CAAC,KAAwB;QAC7C,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QACnD,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,2EAA2E;QAC3E,gEAAgE;QAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ;YAC7B,CAAC,CAAC,kBAAkB,CAClB;gBACC,GAAG,IAAI,CAAC,QAAQ;gBAChB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,aAAa,EAAE,KAAK,CAAC,SAAS;aAC9B,EACD,KAAK,CAAC,IAAI,CACV;YACF,CAAC,CAAC,SAAS,CAAC;QACb,MAAM,GAAG,GAAG,QAAQ,EAAE,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;QAE3C,OAAO;YACN,YAAY,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YACnC,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,UAAU,EAAE;gBACX,SAAS,EAAE,GAAG;gBACd,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtD,GAAG,KAAK,CAAC,UAAU;aACnB;YACD,uEAAuE;YACvE,oEAAoE;YACpE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,SAAS,EAAE;gBACV,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,SAAS;gBAC7B,GAAG;gBACH,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7B,GAAG,CAAC,QAAQ;oBACX,CAAC,CAAC;wBACA,MAAM,EAAE;4BACP;gCACC,GAAG,EAAE,QAAQ;gCACb,KAAK,EAAE,IAAI,CAAC,iBAAiB,IAAI,IAAI;gCACrC,MAAM,EAAE,IAAI,CAAC,kBAAkB,IAAI,GAAG;gCACtC,GAAG,EAAE,KAAK,CAAC,KAAK;6BAChB;yBACD;qBACD;oBACF,CAAC,CAAC,EAAE,CAAC;gBACN,GAAG,KAAK,CAAC,SAAS;aAClB;YACD,OAAO,EAAE;gBACR,IAAI,EAAE,qBAAqB;gBAC3B,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,GAAG,KAAK,CAAC,OAAO;aAChB;SACD,CAAC;IACH,CAAC;IAED,YAAY,CAAC,IAAI,GAAG,SAAS,YAAY,CAAC,KAAK,GAAsB,EAAE;QACtE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC;QAC3C,OAAO;YACN,YAAY,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YACnC,KAAK,EAAE,IAAI,CAAC,aAAa;gBACxB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE;gBAClD,CAAC,CAAC,KAAK;YACR,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,KAAK,CAAC,SAAS;SAClB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,YAAY,CAAC;AACrB,CAAC;AAoBD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IAC1D,OAAO;QACN;YACC,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;YAC3C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG;YAC3B,GAAG,EAAE,KAAK,CAAC,GAAG;SACd;KACD,CAAC;AACH,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-seo",
3
- "version": "0.8.1",
3
+ "version": "0.10.0",
4
4
  "description": "SEO primitives for Next.js sites: typed schema.org JSON-LD builders, a <JsonLd> tag, a Metadata factory (canonical + OG + Twitter), and configurable hreflang alternates.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -43,14 +43,14 @@
43
43
  "test": "vitest run"
44
44
  },
45
45
  "devDependencies": {
46
- "@ingram-tech/nk-dev": "0.12.0",
46
+ "@ingram-tech/nk-dev": "0.13.0",
47
47
  "@types/node": "^26.2.0",
48
48
  "@types/react": "^19.2.18",
49
49
  "next": "^16.3.1",
50
50
  "react": "^19.2.8",
51
51
  "typescript": "^7.0.2",
52
52
  "vitest": "^4.1.10",
53
- "@ingram-tech/nk-i18n": "0.4.1"
53
+ "@ingram-tech/nk-i18n": "0.5.1"
54
54
  },
55
55
  "peerDependencies": {
56
56
  "next": ">=14.0.0",
package/src/alternates.ts CHANGED
@@ -12,42 +12,35 @@ export interface HreflangConfig {
12
12
  locales: readonly string[];
13
13
  /**
14
14
  * How locale is encoded in the alternate URLs:
15
- * - `"query"` (default): `${baseUrl}${path}?${param}=${locale}` for every locale.
16
- * - `"prefix"`: the default locale stays at the bare path; others get
17
- * `/${locale}${path}` (matches a localized-rewrite setup). Set
18
- * {@link HreflangConfig.prefixDefaultLocale} for sites that prefix every
19
- * locale instead.
15
+ * - `"query"` (default): `${baseUrl}${path}?${param}=${locale}`
16
+ * - `"prefix"`: `/${locale}${path}`
17
+ *
18
+ * The cluster's SHAPE is the same either way and is not configurable: every
19
+ * locale gets its own address, the default included, and the bare path
20
+ * belongs to no locale — it is the negotiating entry point that `x-default`
21
+ * names. `@ingram-tech/nk-i18n`'s `defineLocaleRouting` produces a valid
22
+ * config for this; prefer passing that over assembling one by hand.
20
23
  */
21
24
  strategy?: "query" | "prefix";
22
25
  /** Query-param name for the `"query"` strategy. Default `"hl"`. */
23
26
  param?: string;
24
- /** Default locale. Required for `"prefix"`; it is what `x-default` resolves to. */
25
- defaultLocale?: string;
26
- /**
27
- * `"prefix"` only: prefix the default locale too (`/en/about`, never
28
- * `/about`), and point `x-default` at that prefixed URL. For sites whose
29
- * locale negotiation redirects every bare path — emitting the bare path as
30
- * an alternate would annotate a URL that 3xx-redirects, which is the bug the
31
- * mandatory `defaultLocale` exists to prevent.
32
- */
33
- prefixDefaultLocale?: boolean;
34
27
  /**
35
28
  * The locale **the URL names**, which is not always the locale that rendered.
36
29
  * It determines the self-referencing canonical, and a canonical is a claim
37
- * about an address: under `"query"`, `/pricing` canonicalizes to `/pricing`
38
- * even while content negotiation renders it in French for a French visitor,
39
- * because `/pricing` is the negotiating entry point and belongs to no locale.
40
- * Passing the negotiated locale here instead makes the bare path claim to be
41
- * the French URL, and the real French URL then looks like a duplicate.
30
+ * about an address: `/pricing` canonicalizes to `/pricing` even while content
31
+ * negotiation renders it in French for a French visitor, because `/pricing`
32
+ * belongs to no locale. Passing the negotiated locale here instead makes the
33
+ * bare path claim to be the French URL, and the real French URL then looks
34
+ * like a duplicate of it.
42
35
  *
43
- * Leave it unset on a negotiating bare path. Under `"prefix"` it is detected
44
- * from the pathname; under `"query"` the server cannot see the query string,
45
- * so pass it — `hreflangConfigFor(routing)` from
46
- * "@ingram-tech/nk-i18n/next" fills it in correctly.
36
+ * Leave it unset on the bare path. Under `"prefix"` it is detected from the
37
+ * pathname; under `"query"` the server cannot see the query string, so pass
38
+ * it — `hreflangConfigFor(routing)` from "@ingram-tech/nk-i18n/next" fills it
39
+ * in correctly.
47
40
  */
48
41
  currentLocale?: string;
49
42
  /** Optional locale → hreflang tag map, e.g. `{ en: "en-BE", fr: "fr-BE" }`. */
50
- hrefLangTags?: Record<string, string>;
43
+ hrefLangTags?: Readonly<Partial<Record<string, string>>>;
51
44
  }
52
45
 
53
46
  export interface HreflangLink {
@@ -77,27 +70,11 @@ export function hreflangAlternates(
77
70
  config: HreflangConfig,
78
71
  pathname: string,
79
72
  ): HreflangAlternates {
80
- const {
81
- strategy = "query",
82
- param = "hl",
83
- defaultLocale,
84
- prefixDefaultLocale,
85
- hrefLangTags,
86
- } = config;
87
- if (strategy === "prefix" && !defaultLocale) {
88
- // Without it canonical/x-default point at a bare path that is no
89
- // locale's URL — a silent SEO bug. (With `prefixDefaultLocale` no bare
90
- // path is emitted at all, but x-default still has to resolve to *some*
91
- // locale, so the requirement stands.)
92
- throw new Error(
93
- "hreflangAlternates: `defaultLocale` is required for the prefix strategy.",
94
- );
95
- }
73
+ const { strategy = "query", param = "hl", hrefLangTags } = config;
96
74
 
97
- // Prefix strategy: accept both the bare and the locale-prefixed form of the
98
- // path (middleware's `x-pathname` carries the latter on a real localized
99
- // route — blindly prepending would emit /fr/fr/about) and detect the
100
- // current locale from it.
75
+ // Accept both the bare and the locale-prefixed form of the path (middleware's
76
+ // `x-pathname` carries the latter on a real localized route — blindly
77
+ // prepending would emit /fr/fr/about) and detect the current locale from it.
101
78
  let basePath = pathname;
102
79
  let currentLocale = config.currentLocale;
103
80
  if (strategy === "prefix") {
@@ -108,54 +85,38 @@ export function hreflangAlternates(
108
85
  break;
109
86
  }
110
87
  }
111
- currentLocale ??= defaultLocale;
88
+ // Deliberately no fallback to a default locale: a bare path names none.
112
89
  }
113
90
 
114
- /** The bare (locale-free) URL of the path. */
91
+ /** The bare (locale-free) URL — the negotiating entry point, `x-default`. */
115
92
  const bareUrl = absoluteUrl(basePath, config.baseUrl);
116
93
 
117
- const prefixedUrl = (locale: string): string =>
118
- absoluteUrl(`/${locale}${basePath === "/" ? "" : basePath}`, config.baseUrl);
119
-
94
+ /** Every locale has its own address, the default included. */
120
95
  const hrefFor = (locale: string): string => {
121
96
  if (strategy === "prefix") {
122
- if (locale === defaultLocale && !prefixDefaultLocale) return bareUrl;
123
- return prefixedUrl(locale);
97
+ return absoluteUrl(
98
+ `/${locale}${basePath === "/" ? "" : basePath}`,
99
+ config.baseUrl,
100
+ );
124
101
  }
125
102
  return `${bareUrl}${bareUrl.includes("?") ? "&" : "?"}${param}=${locale}`;
126
103
  };
127
104
 
128
- /** x-default: the default locale's own URL, prefixed or not. */
129
- const defaultUrl =
130
- strategy === "prefix" && prefixDefaultLocale && defaultLocale
131
- ? prefixedUrl(defaultLocale)
132
- : bareUrl;
133
-
134
- // Self-referencing canonical: the current variant's own URL. Canonicalizing
135
- // a localized variant to the bare path makes Google treat the variants as
136
- // duplicates and ignore the hreflang annotations entirely.
137
- //
138
- // Whether the default locale has a URL of its own is strategy-dependent, and
139
- // conflating the two is a silent way to delete the default locale from the
140
- // cluster. Under `"prefix"` it shares the bare path (unless every locale is
141
- // prefixed), so its canonical IS the bare path. Under `"query"` every locale
142
- // gets its own `?param=` address and the bare path belongs to none of them:
143
- // it is the negotiating entry point that `x-default` names. So `?hl=en` must
144
- // canonicalize to `?hl=en`, never to the bare path.
145
- const defaultLocaleOwnsBarePath = strategy === "prefix" && !prefixDefaultLocale;
105
+ // Self-referencing canonical: the current variant's own URL, or the bare path
106
+ // when the URL names no locale. Canonicalizing a localized variant to the
107
+ // bare path makes Google treat the variants as duplicates and ignore the
108
+ // hreflang annotations entirely.
146
109
  const canonical =
147
- currentLocale &&
148
- config.locales.includes(currentLocale) &&
149
- !(defaultLocaleOwnsBarePath && currentLocale === defaultLocale)
110
+ currentLocale && config.locales.includes(currentLocale)
150
111
  ? hrefFor(currentLocale)
151
- : defaultUrl;
112
+ : bareUrl;
152
113
 
153
114
  const links = [
154
115
  ...config.locales.map((locale) => ({
155
116
  hrefLang: hrefLangTags?.[locale] ?? locale,
156
117
  href: hrefFor(locale),
157
118
  })),
158
- { hrefLang: "x-default", href: defaultUrl },
119
+ { hrefLang: "x-default", href: bareUrl },
159
120
  ];
160
121
 
161
122
  return {
package/src/hreflang.tsx CHANGED
@@ -13,9 +13,12 @@ export interface HreflangLinksProps extends HreflangConfig {
13
13
  * return NextResponse.next({ request: { headers: requestHeaders } });
14
14
  * ```
15
15
  *
16
- * Pass explicitly if you don't use that header (e.g. from route params) —
17
- * also the only way to keep the page statically renderable, since reading
18
- * `headers()` opts the page into dynamic rendering.
16
+ * Pass explicitly if you don't use that header (e.g. from route params).
17
+ * On a statically rendered route the header is empty (and reading it would
18
+ * otherwise opt the page into dynamic rendering), so a header-reading
19
+ * instance cannot sit in a layout shared with static pages — prefer
20
+ * `createMetadata({ hreflang })`, which emits the same cluster from metadata
21
+ * without any request header.
19
22
  */
20
23
  pathname?: string;
21
24
  /**
package/src/metadata.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { Metadata } from "next";
2
+ import { hreflangAlternates, type HreflangConfig } from "./alternates.js";
2
3
  import { absoluteUrl } from "./url.js";
3
4
 
4
5
  /**
@@ -27,6 +28,15 @@ export interface MetadataSiteConfig {
27
28
  twitterSite?: string;
28
29
  /** Twitter `@handle` for `creator`. */
29
30
  twitterCreator?: string;
31
+ /**
32
+ * Locale cluster for the site. When set, every `pageMetadata()` call emits
33
+ * the per-locale `alternates.languages` (plus `x-default`) and a canonical
34
+ * that follows the address — the same links `<HreflangLinks>` renders, but
35
+ * from metadata, so it works on statically rendered routes too (there is no
36
+ * request header to read there) and needs no middleware wiring.
37
+ * `@ingram-tech/nk-i18n`'s routing object fits directly: `hreflang: routing`.
38
+ */
39
+ hreflang?: Omit<HreflangConfig, "baseUrl" | "currentLocale">;
30
40
  }
31
41
 
32
42
  /** Per-page inputs for the bound `pageMetadata` function. */
@@ -45,11 +55,21 @@ export interface PageMetadataInput {
45
55
  * on a multilingual site `og:locale` has to vary per page.
46
56
  */
47
57
  locale?: string;
58
+ /**
59
+ * With `site.hreflang` set: the locale **the URL names** (not the one that
60
+ * rendered), so the canonical self-references the localized address. Get it
61
+ * from `getUrlLocale(routing)` (`@ingram-tech/nk-i18n/next`) on dynamic
62
+ * pages; leave it unset on the bare path and on static routes, which serve
63
+ * one document for every visitor and so canonicalize to the bare, `x-default`
64
+ * address. Under the prefix strategy a `/fr/…`-prefixed `path` implies it.
65
+ */
66
+ urlLocale?: string;
48
67
  /**
49
68
  * Merged into the generated `alternates` (wins on conflict). The reason it
50
69
  * exists: `alternates.languages` is per-page on a localized site, and
51
- * spreading the result to bolt it on drops the rest of the object.
52
- * `hreflangAlternates()` returns a ready-made `languages` map.
70
+ * spreading the result to bolt it on drops the rest of the object. Prefer
71
+ * `site.hreflang`, which fills it in on every page; `hreflangAlternates()`
72
+ * returns a ready-made `languages` map for the hand-rolled case.
53
73
  */
54
74
  alternates?: Partial<NonNullable<Metadata["alternates"]>>;
55
75
  /** Merged into the generated `openGraph` (wins on conflict). */
@@ -95,7 +115,19 @@ export function createMetadata(site: MetadataSiteConfig) {
95
115
  function pageMetadata(input: PageMetadataInput): Metadata {
96
116
  const imagePath = input.image ?? site.defaultImage;
97
117
  const imageUrl = imagePath ? absolute(imagePath) : undefined;
98
- const url = absolute(input.path);
118
+ // With a locale cluster the canonical is the current variant's own address
119
+ // (and og:url must agree with it); otherwise the path as given.
120
+ const hreflang = site.hreflang
121
+ ? hreflangAlternates(
122
+ {
123
+ ...site.hreflang,
124
+ baseUrl: site.baseUrl,
125
+ currentLocale: input.urlLocale,
126
+ },
127
+ input.path,
128
+ )
129
+ : undefined;
130
+ const url = hreflang?.canonical ?? absolute(input.path);
99
131
  const locale = input.locale ?? site.locale;
100
132
 
101
133
  return {
@@ -103,7 +135,11 @@ export function createMetadata(site: MetadataSiteConfig) {
103
135
  title: input.title,
104
136
  description: input.description,
105
137
  ...(input.keywords ? { keywords: input.keywords } : {}),
106
- alternates: { canonical: url, ...input.alternates },
138
+ alternates: {
139
+ canonical: url,
140
+ ...(hreflang ? { languages: hreflang.languages } : {}),
141
+ ...input.alternates,
142
+ },
107
143
  // noindex but follow: keep link equity flowing through the page. Use a
108
144
  // full robots override in the page's own metadata for nofollow too.
109
145
  ...(input.noIndex ? { robots: { index: false, follow: true } } : {}),