@edgekits/tanstack-i18n 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this package are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package uses
 [Semantic Versioning](https://semver.org/).
 
+## 0.3.0 — 2026-10-28
+
+### Upgrading from 0.2.x
+
+- **The loader returns `{ locale, translationLocale, translations }`.** `locale` is the UI locale (`<html lang>`, the provider); the translations are read in `translationLocale` (the default locale for a locale without translations). A `LoaderI18n` you build yourself needs `resolveLocaleForTranslations`.
+- **A throwing or rejecting `userPreference` no longer fails the request:** it counts as no preference and logs a `console.warn`; pass `onUserPreferenceError` to report it your way.
+- **The switcher writes `Secure` only on https**, so the lang cookie works on `http://localhost`.
+- **`.i18n-hashes.json` changes shape.** It now holds one baseline per KV namespace id (`{ "<kvId>": { "<locale>:<ns>": "<hash>" } }`). An old flat file is the baseline of the top-level `TRANSLATIONS` id (what 0.2.x wrote), whichever environment migrates first, and is rewritten in the new shape. Commit it as before.
+- **The edge cache starts cold once.** Cache URLs carry the entry format (`https://<keyPrefix>/i18n:v2:<locale>:<ns>`, encoded); 0.2.x entries are never read again and expire on their own. Expect one KV read per namespace and data center right after the deploy.
+- **`migrate` takes about a minute longer and can exit 1.** It purges, waits `--purge-delay` seconds (default 65) for KV to settle, and purges the same URLs again. It exits 1 when KV was updated but the edge cache was not purged (no `CLOUDFLARE_ZONE_ID` or token, or a failed purge); `.i18n-hashes.json` is then not written and the next run retries. A CI step that passed without purge credentials now fails.
+- **Regenerate and commit the generated files** (`npx edgekits-i18n bundle --fallbacks`, or `seed`). `I18n.Schema` types numbers and booleans as such and a list of objects as one merged object type (a key every element has is required, any other optional, a key of differing types a union); a list that mixes strings and objects stops the run. A `null` value and a namespace named `locale` are rejected. Hashes of namespaces with mixed-case keys change once (code-point key order), so the first `migrate` purges those namespaces too.
+- **`keyPrefix` must be a plain lower-case host** (`example.com`, `my-site`): no scheme, path, port syntax, space or upper case. `defineI18nConfig` throws otherwise.
+- **The CLI is stricter.** An unknown argument (`-e staging`) exits 1 naming it; `--purge-delay` is at most 600; `CLOUDFLARE_ZONE_ID` must be 32 hex characters. With `--env <name>`, `.dev.vars.<name>` replaces `.dev.vars` when it exists, as in wrangler. `migrate` compares only the baseline of the KV namespace it writes with the committed file, so `migrate --env staging && migrate` runs in one job.
+- **Node `>=22.23.4`.**
+
+### Changed
+
+- The loader fetches in `i18n.resolveLocaleForTranslations(locale)` and returns `translationLocale` beside `locale` and `translations`.
+- A `userPreference` that throws or rejects falls through to Accept-Language.
+- `userPreference` runs once per Request: the middleware and every loader of the request share its answer, and a failure is reported once.
+- `i18nMiddleware` adds `Vary: Cookie, Accept-Language` to every HTML response (merged with its own `Vary`).
+- `LanguageSwitcher` writes `Secure` only when `location.protocol` is `https:`.
+- `engines.node` `>=22.23.4`; built on `@edgekits/i18n-core` 0.3.0 (raw KV values in the edge cache, the CLI changes above).
+
+### Added
+
+- `onUserPreferenceError(error, request)` on `RequestLocaleOptions`; absent, one `console.warn` per failure, whatever `DEBUG_I18N` says.
+
+## 0.2.2 — 2026-10-27
+
+No changes; released in lockstep.
+
 ## 0.2.1 — 2026-10-27
 
 No changes; released in lockstep with the plugin rename (see `@edgekits/astro-i18n` 0.2.1).

package/README.md

@@ -21,9 +21,11 @@ and TanStack agree. Nothing here sets a cookie or redirects; the switcher writes
 npm install @edgekits/tanstack-i18n @edgekits/i18n-core
 ```
 
-Peers: `hono` 4 and `react` 19. Write `edgekits-i18n.config.ts` and `locales/<locale>/<namespace>.json`
+Requires Node `>=22.23.4`. Peers: `hono` 4 and `react` 19. Write `edgekits-i18n.config.ts` and `locales/<locale>/<namespace>.json`
 as the [core README](https://github.com/EdgeKits/i18n/tree/main/packages/core#readme)
-describes, bind the `TRANSLATIONS` KV namespace in `wrangler.jsonc`, then generate and seed:
+describes, bind the `TRANSLATIONS` KV namespace in `wrangler.jsonc`, then generate and seed.
+The CLI runs the Worker's own wrangler, found from the directory of that `wrangler.jsonc`:
+install it in the Worker's package (`npm i -D wrangler`, `^4.152.0`); a global one is never used.
 
 ```sh
 npx edgekits-i18n seed
@@ -85,6 +87,20 @@ export default app
 Hand `c.req.raw` to TanStack unchanged: server functions live under `/_serverFn/`, and that
 path is case-sensitive.
 
+The same URL renders in whichever locale the cookie, the preference or `Accept-Language`
+chose, so after `next()` the middleware adds `Vary: Cookie, Accept-Language` to every HTML
+response (merged with a `Vary` it already has). Cloudflare's cache does not store a Worker's
+HTML by default; a cache rule that does must bypass requests with the lang cookie (or key on
+it) and on `Accept-Language`.
+
+A `userPreference` that throws or rejects counts as no preference: the request resolves through
+Accept-Language, and the error is logged once with `console.warn` (whatever `DEBUG_I18N` says: a
+failing hook is an application error). To report it your own way, pass
+`onUserPreferenceError: (error, request) => …` next to `userPreference`, to the middleware and
+to the loader alike; it is called once per failure, instead of the warning. The hook runs once
+per `Request`: the middleware and every loader of one request (the SSR document's server
+function gets the same `Request`) share its answer, so a failure is reported once.
+
 ## 3. The server function: `src/i18n/server.ts`
 
 ```ts
@@ -155,6 +171,12 @@ function Root() {
 The config and `localesOf` are pure, safe to import on the client. `languages` and `cookie` are
 given once, here.
 
+The loader returns `{ locale, translationLocale, translations }`. `locale` is the UI locale:
+`<html lang>`, the provider and the switcher take it. `translationLocale` is the locale the
+translations were read in: `locale` when it has translations (the generated
+`LOCALES_WITH_TRANSLATIONS`), otherwise the default locale; compare the two to show a "not
+translated yet" notice.
+
 ## 5. A page: `src/routes/index.tsx`
 
 ```tsx
@@ -210,7 +232,8 @@ Headless: a trigger button and one item per language (the label carries `lang`,
 `aria-current`), class names only from `classes` (slots `root`, `trigger`, `triggerIcon`,
 `dropdown`, `item`, `itemActive`, `itemLabel`), `data-ls-*` and `data-open` hooks for styling, no
 styles. Escape and a click outside close it. Choosing a language writes the lang cookie
-(`path=/`, `max-age` from `cookie.maxAge`, `SameSite=Lax; Secure`), then calls `afterChange`,
+(`path=/`, `max-age` from `cookie.maxAge`, `SameSite=Lax`, and `Secure` on an https page), then
+calls `afterChange`,
 or reloads the page without one; `router.invalidate()` re-runs the loaders in place. With one
 language it renders nothing.
 
@@ -230,7 +253,9 @@ declare module '@edgekits/i18n-core' {
 }
 ```
 
-`c.var.locale` is typed from the instance either way.
+`c.var.locale` has the type you give `I18nVariables` in the app's Hono generic: `I18nVariables`
+alone is `Locale` (`string`, or the union this declaration lists), and
+`I18nVariables<'en' | 'de' | 'es'>` names the locales directly.
 
 ## Monorepo
 

package/dist/loader.d.ts

@@ -2,15 +2,18 @@ import type { Namespace, PickSchema } from '@edgekits/i18n-core';
 import { type RequestI18n, type RequestLocaleOptions } from './request-locale.ts';
 export type LoaderI18n<L extends string> = RequestI18n<L> & {
     fetchTranslations<N extends Namespace>(locale: L, namespaces: readonly N[]): Promise<PickSchema<N>>;
+    resolveLocaleForTranslations(locale: L): L;
 };
 export type LoadedTranslations<L extends string, N extends Namespace> = {
     locale: L;
+    translationLocale: L;
     translations: PickSchema<N>;
 };
 /**
  * The body of the app's translations server function: the request's locale (the same
- * cascade as the middleware) and the namespaces asked for in it. The namespaces come from
- * the browser: validate them with `isNamespaceList` before they reach this. Repeats are
- * dropped here as well, for a caller that skips the validator.
+ * cascade as the middleware) and the namespaces asked for in it, read in that locale's
+ * translation locale. The namespaces come from the browser: validate them with
+ * `isNamespaceList` before they reach this. Repeats are dropped here as well, for a caller
+ * that skips the validator.
  */
 export declare function createTranslationsLoader<L extends string>(i18n: LoaderI18n<L>, options?: RequestLocaleOptions): <N extends Namespace>(request: Request, namespaces: readonly N[]) => Promise<LoadedTranslations<L, N>>;

package/dist/loader.js

@@ -1,13 +1,19 @@
 import { resolveRequestLocale } from "./request-locale.js";
 /**
  * The body of the app's translations server function: the request's locale (the same
- * cascade as the middleware) and the namespaces asked for in it. The namespaces come from
- * the browser: validate them with `isNamespaceList` before they reach this. Repeats are
- * dropped here as well, for a caller that skips the validator.
+ * cascade as the middleware) and the namespaces asked for in it, read in that locale's
+ * translation locale. The namespaces come from the browser: validate them with
+ * `isNamespaceList` before they reach this. Repeats are dropped here as well, for a caller
+ * that skips the validator.
  */
 export function createTranslationsLoader(i18n, options = {}) {
     return async (request, namespaces) => {
         const locale = await resolveRequestLocale(i18n, request, options);
-        return { locale, translations: await i18n.fetchTranslations(locale, [...new Set(namespaces)]) };
+        const translationLocale = i18n.resolveLocaleForTranslations(locale);
+        return {
+            locale,
+            translationLocale,
+            translations: await i18n.fetchTranslations(translationLocale, [...new Set(namespaces)]),
+        };
     };
 }

package/dist/middleware.d.ts

@@ -8,7 +8,9 @@ export type I18nVariables<L extends string = Locale> = {
 /**
  * Sets `c.var.locale` from the request (see `resolveRequestLocale`) and hands on. It never
  * sets a cookie and never redirects: the URL carries no locale, and the lang cookie is
- * written by the language switcher alone.
+ * written by the language switcher alone. An HTML response comes back with
+ * `Vary: Cookie, Accept-Language` (merged with its own `Vary`): the same URL renders in
+ * whichever locale those headers chose.
  */
 export declare function i18nMiddleware<L extends string>(i18n: RequestI18n<L>, options?: RequestLocaleOptions): MiddlewareHandler<{
     Variables: I18nVariables<L>;

package/dist/middleware.js

@@ -1,12 +1,36 @@
 import { resolveRequestLocale } from "./request-locale.js";
+// The request headers an HTML page's locale is chosen from (`userPreference` reads whatever
+// the app keys it on, usually a session cookie).
+const NEGOTIATED = ['Cookie', 'Accept-Language'];
 /**
  * Sets `c.var.locale` from the request (see `resolveRequestLocale`) and hands on. It never
  * sets a cookie and never redirects: the URL carries no locale, and the lang cookie is
- * written by the language switcher alone.
+ * written by the language switcher alone. An HTML response comes back with
+ * `Vary: Cookie, Accept-Language` (merged with its own `Vary`): the same URL renders in
+ * whichever locale those headers chose.
  */
 export function i18nMiddleware(i18n, options = {}) {
     return async (c, next) => {
         c.set('locale', await resolveRequestLocale(i18n, c.req.raw, options));
         await next();
+        if (!(c.res.headers.get('Content-Type') ?? '').includes('text/html'))
+            return;
+        try {
+            varyOnNegotiated(c.res.headers);
+        }
+        catch {
+            // Immutable headers (a response passed through from fetch()): vary on a copy.
+            c.res = new Response(c.res.body, c.res);
+            varyOnNegotiated(c.res.headers);
+        }
     };
 }
+function varyOnNegotiated(headers) {
+    const vary = headers.get('Vary');
+    const fields = (vary ?? '').split(',').map((field) => field.trim().toLowerCase());
+    if (fields.includes('*'))
+        return;
+    const missing = NEGOTIATED.filter((name) => !fields.includes(name.toLowerCase()));
+    if (missing.length > 0)
+        headers.set('Vary', [...(vary ? [vary] : []), ...missing].join(', '));
+}

package/dist/react/language-switcher.js

@@ -38,7 +38,7 @@ export function LanguageSwitcher({ classes = {}, texts, afterChange }) {
     }
     const select = (next) => {
         // Not httpOnly: the server reads the value through `parseLocale`, never trusts it.
-        document.cookie = `${cookie.name}=${next}; path=/; max-age=${cookie.maxAge}; SameSite=Lax; Secure`;
+        document.cookie = `${cookie.name}=${next}; path=/; max-age=${cookie.maxAge}; SameSite=Lax${location.protocol === 'https:' ? '; Secure' : ''}`;
         setOpen(false);
         if (afterChange)
             afterChange(next);

package/dist/request-locale.d.ts

@@ -11,6 +11,7 @@ export type RequestI18n<L extends string> = {
 };
 export type RequestLocaleOptions = {
     userPreference?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+    onUserPreferenceError?: (error: unknown, request: Request) => void;
 };
 /**
  * The locale of a request, from the request alone: the middleware and the loader both call
@@ -19,6 +20,11 @@ export type RequestLocaleOptions = {
  * `userPreference`, then Accept-Language, then the default locale.
  *
  * `userPreference` may be async, the core's cascade is not: it is awaited here, and only
- * when the cookie carries no valid locale.
+ * when the cookie carries no valid locale. A hook that throws or rejects counts as no
+ * preference (see `onUserPreferenceError`).
+ *
+ * The hook runs once per Request: the middleware and every loader of one request (the SSR
+ * document's server functions get the same Request through getRequest()) share its answer,
+ * and a failure is reported once. The first caller's options decide.
  */
 export declare function resolveRequestLocale<L extends string>(i18n: RequestI18n<L>, request: Request, options?: RequestLocaleOptions): Promise<L>;

package/dist/request-locale.js

@@ -6,12 +6,17 @@ import { getCookie } from 'hono/cookie';
  * `userPreference`, then Accept-Language, then the default locale.
  *
  * `userPreference` may be async, the core's cascade is not: it is awaited here, and only
- * when the cookie carries no valid locale.
+ * when the cookie carries no valid locale. A hook that throws or rejects counts as no
+ * preference (see `onUserPreferenceError`).
+ *
+ * The hook runs once per Request: the middleware and every loader of one request (the SSR
+ * document's server functions get the same Request through getRequest()) share its answer,
+ * and a failure is reported once. The first caller's options decide.
  */
 export async function resolveRequestLocale(i18n, request, options = {}) {
     // `getCookie` reads `c.req.raw` only: the loader has a Request and no Hono context.
     const cookieLocale = i18n.parseLocale(getCookie({ req: { raw: request } }, i18n.LANG_COOKIE_NAME));
-    const preferred = cookieLocale ? null : i18n.parseLocale((await options.userPreference?.(request)) ?? null);
+    const preferred = cookieLocale ? null : i18n.parseLocale((await readUserPreference(request, options)) ?? null);
     return i18n.resolveFallbackLocale({
         cookieLocale: () => cookieLocale,
         userPreference: () => preferred,
@@ -19,3 +24,25 @@ export async function resolveRequestLocale(i18n, request, options = {}) {
         country: () => undefined,
     });
 }
+// One `userPreference` answer per Request, kept while the Request lives.
+const preferences = new WeakMap();
+function readUserPreference(request, options) {
+    let preference = preferences.get(request);
+    if (!preference) {
+        preference = callUserPreference(request, options);
+        preferences.set(request, preference);
+    }
+    return preference;
+}
+async function callUserPreference(request, options) {
+    try {
+        return await options.userPreference?.(request);
+    }
+    catch (error) {
+        if (options.onUserPreferenceError)
+            options.onUserPreferenceError(error, request);
+        else
+            console.warn('[@edgekits/tanstack-i18n] userPreference failed; falling back to Accept-Language', error);
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgekits/tanstack-i18n",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Edge-native i18n for TanStack Start on Cloudflare Workers: a Hono locale middleware, a translations loader for server functions, and a React provider over the EdgeKits engine.",
   "keywords": [
     "tanstack",
@@ -26,7 +26,7 @@
     "url": "https://github.com/EdgeKits/i18n/issues"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.23.4"
   },
   "exports": {
     ".": {
@@ -55,7 +55,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@edgekits/i18n-core": "0.2.1"
+    "@edgekits/i18n-core": "0.3.0"
   },
   "peerDependencies": {
     "hono": "^4",