@ingram-tech/nk-i18n 0.3.4 → 0.4.0

package/README.md

@@ -91,8 +91,9 @@ import { useLocale } from "@ingram-tech/nk-i18n/client";
 const locale = useLocale<Locale>();
 ```
 
-Resolve the locale on the server however the site routes. `negotiateAcceptLanguage`
-handles the `Accept-Language` step:
+For a site that encodes the locale in the URL, use **locale routing** (next
+section) rather than hand-rolling this. Otherwise, resolve however the site
+routes; `negotiateAcceptLanguage` handles the `Accept-Language` step:
 
 ```ts
 import { cookies, headers } from "next/headers";
@@ -111,11 +112,91 @@ export const resolveLocale = cache(async (): Promise<Locale> => {
 });
 ```
 
+## Locale URL routing
+
+One definition of how a locale is encoded in a URL, shared by the code that
+**serves** a language and the code that **advertises** it to search engines. When
+those two drift — the classic being middleware that redirects away the very
+`?hl=` URLs hreflang points at — the site tells Google the French page lives at
+an address that doesn't serve French, and Google drops the language. Nothing
+catches that, because neither half can see the other.
+
+```ts
+// lib/i18n/routing.ts
+import { defineLocaleRouting } from "@ingram-tech/nk-i18n";
+
+export const routing = defineLocaleRouting({
+	baseUrl: "https://example.com",
+	locales: ["en", "fr", "nl"],
+	defaultLocale: "en",
+	// strategy: "query" (default) → /pricing?hl=fr, bare path is x-default
+	// strategy: "prefix"          → /fr/pricing, default locale stays bare
+	countryLocales: { FR: "fr", NL: "nl" }, // omit BE: geography can't decide
+});
+```
+
+**The rule: a URL that names a locale serves that locale, with a 200, to
+everybody.** Never redirect it.
+
+```ts
+// proxy.ts — forward, never redirect
+import { forwardUrlLocale } from "@ingram-tech/nk-i18n/next";
+
+export function proxy(request: NextRequest) {
+	const requestHeaders = new Headers(request.headers);
+	forwardUrlLocale(routing, request.nextUrl, requestHeaders);
+	return NextResponse.next({ request: { headers: requestHeaders } });
+}
+```
+
+```ts
+// lib/i18n/locale.ts
+import { createLocaleResolver } from "@ingram-tech/nk-i18n/next";
+
+export const resolveLocale = cache(
+	createLocaleResolver(routing, { account: () => getProfile().locale }),
+);
+```
+
+The precedence is fixed and not configurable:
+
+1. **the URL** (`?hl=fr`) 2. account setting 3. cookie 4. `Accept-Language`
+5. country 6. `defaultLocale`
+
+The URL beating the account setting is the load-bearing part: a shared link must
+show the recipient the language it names, or every localized link the site ships
+is a lie. Suppliers are lazy, so a `?hl=` request never touches the database.
+
+For hreflang, hand the same object to nk-seo — `hreflangConfigFor` sets
+`currentLocale` from the **URL**, so canonicals follow the address rather than
+whatever language negotiation rendered:
+
+```tsx
+// app/layout.tsx
+import { hreflangConfigFor } from "@ingram-tech/nk-i18n/next";
+import { HreflangLinks } from "@ingram-tech/nk-seo/components";
+
+<HreflangLinks {...(await hreflangConfigFor(routing))} pathname={pathname} />;
+```
+
+The language switcher must be real `<a href={routing.urlForLocale(path, loc)}>`
+links: hreflang is an annotation, not a discovery mechanism, so a button calling
+a server action gives a crawler no path to the other languages.
+
+Prove the site serves what it advertises with `assertHreflangCluster` from
+`@ingram-tech/nk-seo/verify`. Full rationale in
+[`docs/i18n-routing.md`](../../docs/i18n-routing.md).
+
 ## Exports
 
 - `@ingram-tech/nk-i18n` (server-safe, no React): `createT`, `defineI18nScope`,
   `defineMessages`, `defineI18nConfig`, `deriveLocaleConstants`, `localeMap`,
-  `negotiateAcceptLanguage`, and the `Messages` / `I18nScope` / `Translator` /
-  `TranslationKey` / `I18nConfig` / `LocaleDefinition` types.
+  `negotiateAcceptLanguage`, `defineLocaleRouting`, `LOCALE_PRECEDENCE`,
+  `resolveLocaleFromSignals`, `resolveLocaleFromSuppliers`, and the `Messages` /
+  `I18nScope` / `Translator` / `TranslationKey` / `I18nConfig` /
+  `LocaleDefinition` / `LocaleRouting` / `LocaleSignals` types.
 - `@ingram-tech/nk-i18n/client` (`"use client"`): `LocaleProvider`, `useLocale`,
   `useT`.
+- `@ingram-tech/nk-i18n/next` (server, needs `next`): `forwardUrlLocale`,
+  `getUrlLocale`, `createLocaleResolver`, `hreflangConfigFor`,
+  `LOCALE_URL_HEADER`.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createT, type CreateTOptions, defineI18nScope, defineMessages, type I18nScope, type LocalizedString, type Messages, type MessageSource, type TranslationKey, type Translator, } from "./core.js";
 export { defineI18nConfig, deriveLocaleConstants, type I18nConfig, localeMap, type LocaleDefinition, type MissingKeysPolicy, } from "./config.js";
 export { negotiateAcceptLanguage } from "./negotiate.js";
+export { defineLocaleRouting, LOCALE_PRECEDENCE, type LocaleRouting, type LocaleRoutingConfig, type LocaleSignal, type LocaleSignals, type LocaleStrategy, type LocaleSupplier, type LocaleSuppliers, resolveLocaleFromSignals, resolveLocaleFromSuppliers, } from "./routing.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,OAAO,EACP,KAAK,cAAc,EACnB,eAAe,EACf,cAAc,EACd,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,UAAU,EACf,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,OAAO,EACP,KAAK,cAAc,EACnB,eAAe,EACf,cAAc,EACd,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,UAAU,EACf,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EACN,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,wBAAwB,EACxB,0BAA0B,GAC1B,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@
 export { createT, defineI18nScope, defineMessages, } from "./core.js";
 export { defineI18nConfig, deriveLocaleConstants, localeMap, } from "./config.js";
 export { negotiateAcceptLanguage } from "./negotiate.js";
+export { defineLocaleRouting, LOCALE_PRECEDENCE, resolveLocaleFromSignals, resolveLocaleFromSuppliers, } from "./routing.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,OAAO,EACN,OAAO,EAEP,eAAe,EACf,cAAc,GAOd,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EAErB,SAAS,GAGT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,OAAO,EACN,OAAO,EAEP,eAAe,EACf,cAAc,GAOd,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EAErB,SAAS,GAGT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EACN,mBAAmB,EACnB,iBAAiB,EAQjB,wBAAwB,EACxB,0BAA0B,GAC1B,MAAM,cAAc,CAAC"}

package/dist/next.d.ts

@@ -0,0 +1,79 @@
+import type { LocaleRouting, LocaleSupplier } from "./routing.js";
+/**
+ * Request header carrying the locale the URL named, from middleware to the
+ * server components that render it. A request header, not a response one:
+ * `headers()` in a server component only sees what middleware forwarded.
+ */
+export declare const LOCALE_URL_HEADER = "x-nk-url-locale";
+/**
+ * Middleware: read the locale `url` names and forward it on `requestHeaders`.
+ * Returns it too, for callers that want to branch.
+ *
+ * Set-or-delete, never pass through: the header is ours to mint, so a client
+ * that sends one of its own must not reach the app.
+ *
+ * This deliberately does NOT redirect. Under the `"query"` strategy the bare
+ * path is a negotiating entry point and `?hl=xx` addresses are the indexable
+ * per-locale ones; both must return 200.
+ *
+ *   export function proxy(request: NextRequest) {
+ *     const requestHeaders = new Headers(request.headers);
+ *     forwardUrlLocale(routing, request.nextUrl, requestHeaders);
+ *     return NextResponse.next({ request: { headers: requestHeaders } });
+ *   }
+ */
+export declare function forwardUrlLocale(routing: LocaleRouting, url: URL, requestHeaders: Headers): string | undefined;
+/**
+ * The locale the current URL names, or `undefined` when it names none — the
+ * bare negotiating path under the `"query"` strategy.
+ *
+ * This, not the negotiated locale, is what a canonical tag must follow. A
+ * canonical is a statement about an address; `/pricing` canonicalizes to
+ * `/pricing` even while it renders French for a French visitor.
+ */
+export declare function getUrlLocale(routing: LocaleRouting): Promise<string | undefined>;
+export interface LocaleResolverOptions {
+    /** Remembered-choice cookie name. Default `"locale"`. */
+    cookieName?: string;
+    /**
+     * The signed-in user's stored preference. Only called when the URL did not
+     * name a locale, so a `?hl=` request costs no database round trip.
+     */
+    account?: LocaleSupplier;
+    /**
+     * ISO-3166 alpha-2 country for the last-resort signal. Defaults to Vercel's
+     * `x-vercel-ip-country`. Only consulted when every stronger signal is silent,
+     * and only for countries present in `routing.countryLocales`.
+     */
+    country?: LocaleSupplier;
+}
+/**
+ * Build the request-scoped locale resolver. Wrap the result in React's `cache()`
+ * if you call it more than once per render.
+ *
+ *   export const resolveLocale = cache(
+ *     createLocaleResolver(routing, { account: () => getProfile().locale }),
+ *   );
+ */
+export declare function createLocaleResolver(routing: LocaleRouting, options?: LocaleResolverOptions): () => Promise<string>;
+/**
+ * The hreflang config for the page being rendered, with `currentLocale` set from
+ * the URL rather than from negotiation. Spread it into `<HreflangLinks>` (from
+ * `@ingram-tech/nk-seo/components`) or `hreflangAlternates`:
+ *
+ *   <HreflangLinks {...(await hreflangConfigFor(routing))} pathname={pathname} />
+ *
+ * Going through here is what keeps the advertised URLs and the served URLs the
+ * same strings, and what keeps canonicals following the address instead of the
+ * rendered language.
+ */
+export declare function hreflangConfigFor(routing: LocaleRouting): Promise<{
+    baseUrl: string;
+    locales: readonly string[];
+    defaultLocale: string;
+    strategy: "query" | "prefix";
+    param: string;
+    prefixDefaultLocale: boolean;
+    currentLocale: string | undefined;
+}>;
+//# sourceMappingURL=next.d.ts.map

package/dist/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGlE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAKnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,GAAG,EACR,cAAc,EAAE,OAAO,GACrB,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAED,MAAM,WAAW,qBAAqB;IACrC,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,qBAA0B,GACjC,MAAM,OAAO,CAAC,MAAM,CAAC,CAYvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB,EAAE,OAAO,CAAC;IAC7B,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC,CAUD"}

package/dist/next.js

@@ -0,0 +1,101 @@
+/**
+ * Next.js wiring for {@link LocaleRouting}: the middleware side that reads the
+ * locale a URL names, and the server-component side that resolves the locale
+ * for a request and builds a matching hreflang config.
+ *
+ * The rule this module exists to enforce: a URL that names a locale SERVES that
+ * locale, with a 200. It is never redirected away. Redirecting `?hl=fr` to the
+ * bare path is the bug that makes every hreflang annotation on the site point at
+ * a URL which does not serve the language it claims, and Google responds by
+ * dropping the non-default languages entirely.
+ */
+import { cookies, headers } from "next/headers";
+import { resolveLocaleFromSuppliers } from "./routing.js";
+/**
+ * Request header carrying the locale the URL named, from middleware to the
+ * server components that render it. A request header, not a response one:
+ * `headers()` in a server component only sees what middleware forwarded.
+ */
+export const LOCALE_URL_HEADER = "x-nk-url-locale";
+/** Vercel's geo header, the default source for the country signal. */
+const VERCEL_COUNTRY_HEADER = "x-vercel-ip-country";
+/**
+ * Middleware: read the locale `url` names and forward it on `requestHeaders`.
+ * Returns it too, for callers that want to branch.
+ *
+ * Set-or-delete, never pass through: the header is ours to mint, so a client
+ * that sends one of its own must not reach the app.
+ *
+ * This deliberately does NOT redirect. Under the `"query"` strategy the bare
+ * path is a negotiating entry point and `?hl=xx` addresses are the indexable
+ * per-locale ones; both must return 200.
+ *
+ *   export function proxy(request: NextRequest) {
+ *     const requestHeaders = new Headers(request.headers);
+ *     forwardUrlLocale(routing, request.nextUrl, requestHeaders);
+ *     return NextResponse.next({ request: { headers: requestHeaders } });
+ *   }
+ */
+export function forwardUrlLocale(routing, url, requestHeaders) {
+    const locale = routing.localeFromUrl(url);
+    if (locale) {
+        requestHeaders.set(LOCALE_URL_HEADER, locale);
+    }
+    else {
+        requestHeaders.delete(LOCALE_URL_HEADER);
+    }
+    return locale;
+}
+/**
+ * The locale the current URL names, or `undefined` when it names none — the
+ * bare negotiating path under the `"query"` strategy.
+ *
+ * This, not the negotiated locale, is what a canonical tag must follow. A
+ * canonical is a statement about an address; `/pricing` canonicalizes to
+ * `/pricing` even while it renders French for a French visitor.
+ */
+export async function getUrlLocale(routing) {
+    const value = (await headers()).get(LOCALE_URL_HEADER);
+    return routing.isLocale(value) && value !== null ? value : undefined;
+}
+/**
+ * Build the request-scoped locale resolver. Wrap the result in React's `cache()`
+ * if you call it more than once per render.
+ *
+ *   export const resolveLocale = cache(
+ *     createLocaleResolver(routing, { account: () => getProfile().locale }),
+ *   );
+ */
+export function createLocaleResolver(routing, options = {}) {
+    const { cookieName = "locale", account, country } = options;
+    return () => resolveLocaleFromSuppliers(routing, {
+        url: async () => (await headers()).get(LOCALE_URL_HEADER),
+        account,
+        cookie: async () => (await cookies()).get(cookieName)?.value,
+        acceptLanguage: async () => (await headers()).get("accept-language"),
+        country: country ?? (async () => (await headers()).get(VERCEL_COUNTRY_HEADER)),
+    });
+}
+/**
+ * The hreflang config for the page being rendered, with `currentLocale` set from
+ * the URL rather than from negotiation. Spread it into `<HreflangLinks>` (from
+ * `@ingram-tech/nk-seo/components`) or `hreflangAlternates`:
+ *
+ *   <HreflangLinks {...(await hreflangConfigFor(routing))} pathname={pathname} />
+ *
+ * Going through here is what keeps the advertised URLs and the served URLs the
+ * same strings, and what keeps canonicals following the address instead of the
+ * rendered language.
+ */
+export async function hreflangConfigFor(routing) {
+    return {
+        baseUrl: routing.baseUrl,
+        locales: routing.locales,
+        defaultLocale: routing.defaultLocale,
+        strategy: routing.strategy,
+        param: routing.param,
+        prefixDefaultLocale: routing.prefixDefaultLocale,
+        currentLocale: await getUrlLocale(routing),
+    };
+}
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAEnD,sEAAsE;AACtE,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAC/B,OAAsB,EACtB,GAAQ,EACR,cAAuB;IAEvB,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,MAAM,EAAE,CAAC;QACZ,cAAc,CAAC,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;SAAM,CAAC;QACP,cAAc,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,OAAsB;IAEtB,MAAM,KAAK,GAAG,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACvD,OAAO,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACtE,CAAC;AAkBD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAsB,EACtB,OAAO,GAA0B,EAAE;IAEnC,MAAM,EAAE,UAAU,GAAG,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE5D,OAAO,GAAG,EAAE,CACX,0BAA0B,CAAC,OAAO,EAAE;QACnC,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC;QACzD,OAAO;QACP,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,KAAK;QAC5D,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC;QACpE,OAAO,EACN,OAAO,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;KACtE,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAsB;IAS7D,OAAO;QACN,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,aAAa,EAAE,MAAM,YAAY,CAAC,OAAO,CAAC;KAC1C,CAAC;AACH,CAAC"}

package/dist/routing.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Locale routing: the single definition of how a locale is encoded in a URL,
+ * and the fixed precedence by which a request's locale is decided.
+ *
+ * This exists because the two halves of a multilingual site are easy to drift
+ * apart. One half advertises URLs to search engines (`@ingram-tech/nk-seo`'s
+ * hreflang alternates); the other half decides which language a request gets.
+ * When they disagree — the classic failure is middleware that redirects away
+ * the very `?hl=` URLs hreflang points at — the site tells Google the French
+ * page lives at an address that does not serve French, and Google discards the
+ * whole cluster. Nothing catches that, because neither half can see the other.
+ *
+ * A {@link LocaleRouting} is deliberately shaped so it can be handed straight
+ * to `hreflangAlternates` as its config: one object owns the locale list, the
+ * default, the strategy and the param name, so the advertised URL and the
+ * served URL are the same string by construction.
+ */
+/**
+ * How a locale is encoded in a URL.
+ *
+ * - `"query"`: every locale gets `?<param>=<locale>`, and the bare path is a
+ *   negotiating entry point that belongs to no locale (it is `x-default`).
+ * - `"prefix"`: the default locale lives at the bare path and the rest get
+ *   `/<locale>/…`, unless {@link LocaleRoutingConfig.prefixDefaultLocale}.
+ */
+export type LocaleStrategy = "query" | "prefix";
+export interface LocaleRoutingConfig {
+    /** Absolute site origin, e.g. "https://acme.example". */
+    baseUrl: string;
+    /** Every supported locale, e.g. `["en", "fr", "nl"]`. */
+    locales: readonly string[];
+    /**
+     * The locale served when no signal says otherwise. Under `"query"` it is
+     * NOT the owner of the bare path: the bare path negotiates and `x-default`
+     * points at it, while the default locale gets its own `?<param>=` address
+     * like every other locale.
+     */
+    defaultLocale: string;
+    /** Default `"query"`. */
+    strategy?: LocaleStrategy;
+    /** Query-param name for the `"query"` strategy. Default `"hl"`. */
+    param?: string;
+    /** `"prefix"` only: prefix the default locale too (`/en/about`). */
+    prefixDefaultLocale?: boolean;
+    /**
+     * ISO-3166 alpha-2 country → locale, for the last-resort country signal.
+     * Omit a country whose language is genuinely ambiguous (Belgium is the
+     * obvious one: geography tells you nothing about whether a visitor reads
+     * French or Dutch) so it falls through to {@link defaultLocale} instead of
+     * guessing. Countries absent from the map are ignored.
+     */
+    countryLocales?: Readonly<Record<string, string>>;
+}
+/**
+ * The signals a locale can be decided from, in no particular order — the order
+ * is {@link resolveLocaleFromSignals}'s to own, not the caller's.
+ */
+export interface LocaleSignals {
+    /** The locale the URL itself names (the `?hl=` value, or a path prefix). */
+    url?: string | null | undefined;
+    /** The signed-in user's stored preference. */
+    account?: string | null | undefined;
+    /** The remembered-choice cookie. */
+    cookie?: string | null | undefined;
+    /** Raw `Accept-Language` header value; negotiated, not matched literally. */
+    acceptLanguage?: string | null | undefined;
+    /** ISO-3166 alpha-2 country code, mapped through `countryLocales`. */
+    country?: string | null | undefined;
+}
+export interface LocaleRouting extends Required<Omit<LocaleRoutingConfig, "countryLocales">> {
+    countryLocales: Readonly<Record<string, string>>;
+    /** Narrow an arbitrary value (cookie, header, DB column) to a locale. */
+    isLocale: (value: unknown) => boolean;
+    /**
+     * The locale this URL *names*, or `undefined` when it names none (the bare
+     * negotiating path under `"query"`). This is the value canonical tags must
+     * follow: a canonical is a statement about an address, not about whichever
+     * language negotiation happened to render.
+     */
+    localeFromUrl: (url: URL | string) => string | undefined;
+    /** The absolute address that always serves `locale`. */
+    urlForLocale: (pathname: string, locale: string) => string;
+    /** The absolute bare address — `x-default` under `"query"`. */
+    bareUrl: (pathname: string) => string;
+    /** Apply the fixed precedence to a set of signals. */
+    resolve: (signals: LocaleSignals) => string;
+}
+/**
+ * The one order every Ingram site decides a locale in:
+ *
+ *   1. the URL (`?hl=fr`) — an address that names a language always wins,
+ *      including over a signed-in user's stored preference. A shared link must
+ *      show the recipient the language it names, or the link is a lie and the
+ *      hreflang annotation pointing at it is too.
+ *   2. the account's stored preference
+ *   3. the remembered-choice cookie
+ *   4. `Accept-Language`
+ *   5. country, via `countryLocales`
+ *
+ * ...then `defaultLocale`. The order is not configurable, and it is declared
+ * exactly once so the eager and lazy resolvers cannot disagree. It is the whole
+ * reason this lives in nextkit: a site that puts the cookie above the URL
+ * silently breaks every localized link it ships, and the breakage is invisible
+ * until the search traffic is gone.
+ */
+export declare const LOCALE_PRECEDENCE: readonly ["url", "account", "cookie", "acceptLanguage", "country"];
+export type LocaleSignal = (typeof LOCALE_PRECEDENCE)[number];
+type RoutingSlice = Pick<LocaleRouting, "locales" | "defaultLocale" | "countryLocales" | "isLocale">;
+/** Apply {@link LOCALE_PRECEDENCE} to already-gathered signal values. */
+export declare function resolveLocaleFromSignals(routing: RoutingSlice, signals: LocaleSignals): string;
+/** A signal source; may be async, and is only called if the chain reaches it. */
+export type LocaleSupplier = () => string | null | undefined | Promise<string | null | undefined>;
+export type LocaleSuppliers = Partial<Record<LocaleSignal, LocaleSupplier>>;
+/**
+ * Apply {@link LOCALE_PRECEDENCE} to lazily-evaluated sources, stopping at the
+ * first that yields a locale. Suppliers later in the chain are never called, so
+ * a URL that names its language costs no database round trip.
+ */
+export declare function resolveLocaleFromSuppliers(routing: RoutingSlice, suppliers: LocaleSuppliers): Promise<string>;
+/**
+ * Build the routing definition. Hand the result to BOTH your locale resolver
+ * and your hreflang config — a `LocaleRouting` is a valid `HreflangConfig`, so
+ * the URL you advertise and the URL you serve cannot drift.
+ */
+export declare function defineLocaleRouting(config: LocaleRoutingConfig): LocaleRouting;
+export {};
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"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"}

package/dist/routing.js

@@ -0,0 +1,128 @@
+import { negotiateAcceptLanguage } from "./negotiate.js";
+/** Resolve `path` against `baseUrl`, refusing anything that escapes the origin. */
+const absolute = (path, baseUrl) => {
+    const base = new URL(baseUrl);
+    const resolved = new URL(path, base);
+    if (resolved.origin !== base.origin) {
+        throw new Error(`@ingram-tech/nk-i18n: "${path}" resolves outside the site origin ${base.origin}`);
+    }
+    return resolved.toString();
+};
+/**
+ * The one order every Ingram site decides a locale in:
+ *
+ *   1. the URL (`?hl=fr`) — an address that names a language always wins,
+ *      including over a signed-in user's stored preference. A shared link must
+ *      show the recipient the language it names, or the link is a lie and the
+ *      hreflang annotation pointing at it is too.
+ *   2. the account's stored preference
+ *   3. the remembered-choice cookie
+ *   4. `Accept-Language`
+ *   5. country, via `countryLocales`
+ *
+ * ...then `defaultLocale`. The order is not configurable, and it is declared
+ * exactly once so the eager and lazy resolvers cannot disagree. It is the whole
+ * reason this lives in nextkit: a site that puts the cookie above the URL
+ * silently breaks every localized link it ships, and the breakage is invisible
+ * until the search traffic is gone.
+ */
+export const LOCALE_PRECEDENCE = [
+    "url",
+    "account",
+    "cookie",
+    "acceptLanguage",
+    "country",
+];
+/**
+ * Turn one raw signal value into a locale. Most signals are already a locale
+ * code and only need narrowing; `acceptLanguage` is a header to negotiate and
+ * `country` is an ISO code to look up.
+ */
+const normalize = (signal, raw, routing) => {
+    if (raw === null || raw === undefined || raw === "")
+        return undefined;
+    if (signal === "acceptLanguage") {
+        const negotiated = negotiateAcceptLanguage(raw, routing.locales);
+        return routing.isLocale(negotiated) ? negotiated : undefined;
+    }
+    if (signal === "country") {
+        const mapped = routing.countryLocales[raw.toUpperCase()];
+        return routing.isLocale(mapped) ? mapped : undefined;
+    }
+    return routing.isLocale(raw) ? raw : undefined;
+};
+/** Apply {@link LOCALE_PRECEDENCE} to already-gathered signal values. */
+export function resolveLocaleFromSignals(routing, signals) {
+    for (const signal of LOCALE_PRECEDENCE) {
+        const locale = normalize(signal, signals[signal], routing);
+        if (locale)
+            return locale;
+    }
+    return routing.defaultLocale;
+}
+/**
+ * Apply {@link LOCALE_PRECEDENCE} to lazily-evaluated sources, stopping at the
+ * first that yields a locale. Suppliers later in the chain are never called, so
+ * a URL that names its language costs no database round trip.
+ */
+export async function resolveLocaleFromSuppliers(routing, suppliers) {
+    for (const signal of LOCALE_PRECEDENCE) {
+        const supplier = suppliers[signal];
+        if (!supplier)
+            continue;
+        const locale = normalize(signal, await supplier(), routing);
+        if (locale)
+            return locale;
+    }
+    return routing.defaultLocale;
+}
+/**
+ * Build the routing definition. Hand the result to BOTH your locale resolver
+ * and your hreflang config — a `LocaleRouting` is a valid `HreflangConfig`, so
+ * the URL you advertise and the URL you serve cannot drift.
+ */
+export function defineLocaleRouting(config) {
+    const { baseUrl, locales, defaultLocale, strategy = "query", param = "hl", prefixDefaultLocale = false, countryLocales = {}, } = config;
+    if (!locales.includes(defaultLocale)) {
+        throw new Error(`@ingram-tech/nk-i18n: defaultLocale "${defaultLocale}" is not in locales [${locales.join(", ")}].`);
+    }
+    const isLocale = (value) => typeof value === "string" && locales.includes(value);
+    const bareUrl = (pathname) => absolute(pathname, baseUrl);
+    const urlForLocale = (pathname, locale) => {
+        if (strategy === "prefix") {
+            if (locale === defaultLocale && !prefixDefaultLocale)
+                return bareUrl(pathname);
+            return absolute(`/${locale}${pathname === "/" ? "" : pathname}`, baseUrl);
+        }
+        const bare = bareUrl(pathname);
+        return `${bare}${bare.includes("?") ? "&" : "?"}${param}=${locale}`;
+    };
+    const localeFromUrl = (url) => {
+        const parsed = typeof url === "string" ? new URL(url, baseUrl) : url;
+        if (strategy === "prefix") {
+            const found = locales.find((locale) => parsed.pathname === `/${locale}` ||
+                parsed.pathname.startsWith(`/${locale}/`));
+            if (found)
+                return found;
+            return prefixDefaultLocale ? undefined : defaultLocale;
+        }
+        const value = parsed.searchParams.get(param);
+        return isLocale(value) && value !== null ? value : undefined;
+    };
+    const routing = {
+        baseUrl,
+        locales,
+        defaultLocale,
+        strategy,
+        param,
+        prefixDefaultLocale,
+        countryLocales,
+        isLocale,
+        localeFromUrl,
+        urlForLocale,
+        bareUrl,
+        resolve: (signals) => resolveLocaleFromSignals(routing, signals),
+    };
+    return routing;
+}
+//# sourceMappingURL=routing.js.map

package/dist/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@ingram-tech/nk-i18n",
-	"version": "0.3.4",
-	"description": "Type-safe, English-as-key i18n for Ingram Next.js sites — ICU translator, scopes, locale config, and Accept-Language negotiation.",
+	"version": "0.4.0",
+	"description": "Type-safe, English-as-key i18n for Ingram Next.js sites — ICU translator, scopes, locale config, Accept-Language negotiation, and locale URL routing.",
 	"license": "MIT",
 	"type": "module",
 	"repository": {
@@ -23,6 +23,10 @@
 		"./client": {
 			"types": "./dist/client.d.ts",
 			"import": "./dist/client.js"
+		},
+		"./next": {
+			"types": "./dist/next.d.ts",
+			"import": "./dist/next.js"
 		}
 	},
 	"scripts": {
@@ -34,18 +38,23 @@
 		"intl-messageformat": "^11.2.14"
 	},
 	"devDependencies": {
-		"@ingram-tech/nk-dev": "0.11.0",
+		"@ingram-tech/nk-dev": "0.11.1",
 		"@types/react": "^19.2.18",
 		"react": "^19.2.8",
 		"typescript": "^7.0.2",
-		"vitest": "^4.1.10"
+		"vitest": "^4.1.10",
+		"next": "^16.3.1"
 	},
 	"peerDependencies": {
-		"react": "^18.0.0 || ^19.0.0"
+		"react": "^18.0.0 || ^19.0.0",
+		"next": ">=14.0.0"
 	},
 	"peerDependenciesMeta": {
 		"react": {
 			"optional": true
+		},
+		"next": {
+			"optional": true
 		}
 	}
 }