@edgekits/tanstack-i18n 0.0.0-stage → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+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.2.1 — 2026-10-27
+
+No changes; released in lockstep with the plugin rename (see `@edgekits/astro-i18n` 0.2.1).
+
+## 0.2.0 — 2026-10-27
+
+First release, over `@edgekits/i18n-core` 0.2.0, for TanStack Start on a Hono Worker:
+
+- `i18nMiddleware`: sets `c.var.locale` from the cookie, `userPreference`, Accept-Language, the default; never sets a cookie or redirects.
+- `createTranslationsLoader`: the body of the app's own server function, the same cascade plus `fetchTranslations`; drops repeated namespaces.
+- `isNamespaceList`: the validator for the namespace list from the browser: known names only, no repeats, non-empty, at most the generated count.
+- `./react`: `I18nProvider` (nesting, inner namespaces merged over outer), `useI18n`, `useT` typed from the schema.
+- `LanguageSwitcher`: headless, writes the lang cookie, then `afterChange` (e.g. `router.invalidate()`) or a reload.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Stupak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,250 @@
-# Temporary Holding Version
+# @edgekits/tanstack-i18n
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Edge-native i18n for TanStack Start on Cloudflare Workers, over the EdgeKits engine
+[`@edgekits/i18n-core`](https://github.com/EdgeKits/i18n/tree/main/packages/core#readme):
+translations in Workers KV, a per-namespace edge cache, typed keys. For an app whose Worker
+entry is a Hono app that hands the request to TanStack Start, and whose URLs carry no locale.
+
+- `@edgekits/tanstack-i18n` (server): `i18nMiddleware` for the Hono chain (sets `c.var.locale`),
+  `createTranslationsLoader` and `isNamespaceList` for the app's translations server function.
+- `@edgekits/tanstack-i18n/react` (client-safe): `I18nProvider`, `useI18n`, `useT` and the
+  headless `LanguageSwitcher`.
+
+The locale of a request comes from the request alone, in this order: the lang cookie, the
+user's saved preference (a hook you supply), `Accept-Language` (a regional tag such as `de-DE`
+matches `de`), the default locale. The middleware and the loader run the same cascade, so Hono
+and TanStack agree. Nothing here sets a cookie or redirects; the switcher writes the cookie.
+
+## Install
+
+```sh
+npm install @edgekits/tanstack-i18n @edgekits/i18n-core
+```
+
+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:
+
+```sh
+npx edgekits-i18n seed
+```
+
+## 1. The instance: `src/i18n/instance.ts`
+
+```ts
+import { env, waitUntil } from 'cloudflare:workers'
+import { createI18n, parseBooleanFlag } from '@edgekits/i18n-core'
+
+import config from '../../edgekits-i18n.config'
+import * as fallbacks from './fallbacks.generated'
+import * as runtimeConstants from './runtime-constants'
+
+export const i18n = createI18n(
+  config,
+  { fallbacks, runtimeConstants },
+  {
+    get kv() {
+      return env.TRANSLATIONS
+    },
+    get cache() {
+      return caches.default ?? null
+    },
+    waitUntil,
+    get cacheEnabled() {
+      return parseBooleanFlag(env.I18N_CACHE, true)
+    },
+    get debug() {
+      return parseBooleanFlag(env.DEBUG_I18N, false)
+    },
+  },
+)
+
+// Optional: the user's saved locale, consulted after the cookie. Sync or async; return a
+// locale string or null. The value is checked against your locales, never trusted.
+export const userPreference = async (request: Request): Promise<string | null> => null
+```
+
+## 2. The middleware: `src/worker.ts`
+
+```ts
+import { Hono } from 'hono'
+import handler from '@tanstack/react-start/server-entry'
+import { i18nMiddleware, type I18nVariables } from '@edgekits/tanstack-i18n'
+
+import { i18n, userPreference } from './i18n/instance'
+
+const app = new Hono<{ Variables: I18nVariables /* & your own */ }>()
+
+app.use(i18nMiddleware(i18n, { userPreference })) // before middleware that reads c.var.locale
+// …your session and tenant middleware…
+app.all('*', (c) => handler.fetch(c.req.raw, { context: {} }))
+
+export default app
+```
+
+Hand `c.req.raw` to TanStack unchanged: server functions live under `/_serverFn/`, and that
+path is case-sensitive.
+
+## 3. The server function: `src/i18n/server.ts`
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { getRequest, setResponseHeaders } from '@tanstack/react-start/server'
+import { createTranslationsLoader, isNamespaceList } from '@edgekits/tanstack-i18n'
+
+import { i18n, userPreference } from './instance'
+
+const isNamespaces = isNamespaceList(i18n)
+const load = createTranslationsLoader(i18n, { userPreference })
+
+export const getTranslations = createServerFn({ method: 'GET' })
+  .validator((data: unknown) => {
+    if (!isNamespaces(data)) throw new Error('Unknown namespace')
+    return data
+  })
+  .handler(({ data }) => {
+    // The answer depends on the lang cookie: no shared cache may store it for everyone.
+    setResponseHeaders(new Headers({ 'Cache-Control': 'private, no-store', Vary: 'Cookie' }))
+    return load(getRequest(), data)
+  })
+```
+
+The namespace list comes from the browser: `isNamespaceList` is true only for a non-empty
+array of distinct namespaces the CLI generated, at most as many as there are, and the server
+function rejects anything else, so an unknown name never reaches a KV key and one request
+reads at most every namespace once. The package ships no server function of its own: Start compiles
+one from a dependency too, but it is declared in the app so that the app's own request
+helpers and kernel are in scope. The handler, the instance and the compiled fallbacks stay out
+of the client bundle.
+
+## 4. The root route: `src/routes/__root.tsx`
+
+```tsx
+import { Outlet, createRootRoute, HeadContent, Scripts } from '@tanstack/react-router'
+import { localesOf } from '@edgekits/i18n-core'
+import { I18nProvider } from '@edgekits/tanstack-i18n/react'
+
+import config from '../../edgekits-i18n.config'
+import { getTranslations } from '../i18n/server'
+
+const { LANGUAGES } = localesOf(config)
+
+export const Route = createRootRoute({
+  loader: () => getTranslations({ data: ['common'] }),
+  component: Root,
+})
+
+function Root() {
+  const { locale, translations } = Route.useLoaderData()
+  return (
+    <html lang={locale}>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <I18nProvider locale={locale} translations={translations} languages={LANGUAGES} cookie={config.cookie}>
+          <Outlet />
+        </I18nProvider>
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+The config and `localesOf` are pure, safe to import on the client. `languages` and `cookie` are
+given once, here.
+
+## 5. A page: `src/routes/index.tsx`
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { I18nProvider, useT } from '@edgekits/tanstack-i18n/react'
+
+import { getTranslations } from '../i18n/server'
+
+export const Route = createFileRoute('/')({
+  loader: () => getTranslations({ data: ['home'] }),
+  component: Page,
+})
+
+function Page() {
+  return (
+    <I18nProvider translations={Route.useLoaderData().translations}>
+      <Home />
+    </I18nProvider>
+  )
+}
+
+function Home() {
+  const common = useT('common') // from the root route
+  const home = useT('home') // from this one
+  return (
+    <main>
+      <h1>{common.title}</h1>
+      <p>{home.hero}</p>
+    </main>
+  )
+}
+```
+
+Providers nest: an inner one merges its namespaces over the ones above and inherits the locale,
+`languages` and `cookie`. `useT(namespace)` returns the namespace object, typed from your
+default locale's JSON; a namespace no route loader above has loaded throws. `useI18n()` returns
+`{ locale, languages, translations }`. Each route's dehydrated loader data carries only its own
+namespaces, in one locale.
+
+## The language switcher
+
+```tsx
+import { useRouter } from '@tanstack/react-router'
+import { LanguageSwitcher } from '@edgekits/tanstack-i18n/react'
+
+function Header() {
+  const router = useRouter()
+  return <LanguageSwitcher classes={{ root: 'ls', trigger: 'ls-trigger', dropdown: 'ls-menu', item: 'ls-item', itemActive: 'is-active' }} texts={{ trigger: 'Switch language' }} afterChange={() => router.invalidate()} />
+}
+```
+
+Headless: a trigger button and one item per language (the label carries `lang`, the active item
+`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`,
+or reloads the page without one; `router.invalidate()` re-runs the loaders in place. With one
+language it renders nothing.
+
+## A narrowed `Locale` (optional)
+
+`Locale` is `string` until you list your locales, in any `.d.ts` your tsconfig includes:
+
+```ts
+export {}
+
+declare module '@edgekits/i18n-core' {
+  interface I18nLocales {
+    en: true
+    de: true
+    es: true
+  }
+}
+```
+
+`c.var.locale` is typed from the instance either way.
+
+## Monorepo
+
+One translations folder for several Workers: the config, `locales/` and the generated files live
+in a shared package, and each app imports them from there. The CLI takes the two paths:
+
+```sh
+npx edgekits-i18n seed --config packages/i18n/edgekits-i18n.config.ts --wrangler apps/app/wrangler.jsonc
+npx edgekits-i18n migrate --config packages/i18n/edgekits-i18n.config.ts --wrangler apps/app/wrangler.jsonc
+```
+
+See the core README's
+[monorepo section](https://github.com/EdgeKits/i18n/tree/main/packages/core#monorepo-one-translations-folder-several-workers).
+
+## License
+
+MIT © Gary Stupak. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { i18nMiddleware, type I18nVariables } from './middleware.ts';
+export { createTranslationsLoader, type LoadedTranslations, type LoaderI18n } from './loader.ts';
+export { isNamespaceList } from './namespaces.ts';
+export type { RequestI18n, RequestLocaleOptions } from './request-locale.ts';

package/dist/index.js

@@ -0,0 +1,5 @@
+// `@edgekits/tanstack-i18n`, the server entry: no React, no TanStack. The Hono middleware
+// for the Worker's chain, and the loader and validator the app's own server function wraps.
+export { i18nMiddleware } from "./middleware.js";
+export { createTranslationsLoader } from "./loader.js";
+export { isNamespaceList } from "./namespaces.js";

package/dist/loader.d.ts

@@ -0,0 +1,16 @@
+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>>;
+};
+export type LoadedTranslations<L extends string, N extends Namespace> = {
+    locale: 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.
+ */
+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

@@ -0,0 +1,13 @@
+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.
+ */
+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)]) };
+    };
+}

package/dist/middleware.d.ts

@@ -0,0 +1,15 @@
+import type { Locale } from '@edgekits/i18n-core';
+import type { MiddlewareHandler } from 'hono';
+import { type RequestI18n, type RequestLocaleOptions } from './request-locale.ts';
+/** The middleware's variables, for the app's `new Hono<{ Variables: I18nVariables & … }>()`. */
+export type I18nVariables<L extends string = Locale> = {
+    locale: L;
+};
+/**
+ * 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.
+ */
+export declare function i18nMiddleware<L extends string>(i18n: RequestI18n<L>, options?: RequestLocaleOptions): MiddlewareHandler<{
+    Variables: I18nVariables<L>;
+}>;

package/dist/middleware.js

@@ -0,0 +1,12 @@
+import { resolveRequestLocale } from "./request-locale.js";
+/**
+ * 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.
+ */
+export function i18nMiddleware(i18n, options = {}) {
+    return async (c, next) => {
+        c.set('locale', await resolveRequestLocale(i18n, c.req.raw, options));
+        await next();
+    };
+}

package/dist/namespaces.d.ts

@@ -0,0 +1,15 @@
+import type { Namespace } from '@edgekits/i18n-core';
+/**
+ * The validator for a server function's namespace list: true only for a non-empty array of
+ * distinct strings, all in the generated `NAMESPACE_KEYS`, no longer than that list. The
+ * input comes from the browser, so on false the server function rejects:
+ *   - an unknown namespace must never reach a KV key;
+ *   - the bounds keep one request to what a page can need. The list becomes one batched
+ *     KV read (a Workers KV batch takes at most 100 keys; a longer one fails and the
+ *     request is served from the compiled fallbacks) and one cache lookup and write per
+ *     entry, so repeats and oversized lists would multiply a request's work for nothing.
+ *     An empty list asks for nothing.
+ */
+export declare function isNamespaceList(i18n: {
+    readonly NAMESPACE_KEYS: readonly string[];
+}): (data: unknown) => data is Namespace[];

package/dist/namespaces.js

@@ -0,0 +1,19 @@
+/**
+ * The validator for a server function's namespace list: true only for a non-empty array of
+ * distinct strings, all in the generated `NAMESPACE_KEYS`, no longer than that list. The
+ * input comes from the browser, so on false the server function rejects:
+ *   - an unknown namespace must never reach a KV key;
+ *   - the bounds keep one request to what a page can need. The list becomes one batched
+ *     KV read (a Workers KV batch takes at most 100 keys; a longer one fails and the
+ *     request is served from the compiled fallbacks) and one cache lookup and write per
+ *     entry, so repeats and oversized lists would multiply a request's work for nothing.
+ *     An empty list asks for nothing.
+ */
+export function isNamespaceList(i18n) {
+    const known = new Set(i18n.NAMESPACE_KEYS);
+    return (data) => Array.isArray(data) &&
+        data.length > 0 &&
+        data.length <= known.size &&
+        new Set(data).size === data.length &&
+        data.every((ns) => typeof ns === 'string' && known.has(ns));
+}

package/dist/react/index.d.ts

@@ -0,0 +1,2 @@
+export { I18nProvider, useI18n, useT, type I18nCookie, type I18nLanguages, type I18nProviderProps, type NamespaceTranslations, } from './provider.tsx';
+export { LanguageSwitcher, type LanguageSwitcherProps } from './language-switcher.tsx';

package/dist/react/index.js

@@ -0,0 +1,4 @@
+// `@edgekits/tanstack-i18n/react`: the provider a route's loader data feeds, the hooks over
+// it and the headless language switcher. Client-safe: nothing here reaches KV.
+export { I18nProvider, useI18n, useT, } from "./provider.js";
+export { LanguageSwitcher } from "./language-switcher.js";

package/dist/react/language-switcher.d.ts

@@ -0,0 +1,14 @@
+import type { Locale } from '@edgekits/i18n-core';
+export type LanguageSwitcherProps = {
+    classes?: Partial<Record<'root' | 'trigger' | 'triggerIcon' | 'dropdown' | 'item' | 'itemActive' | 'itemLabel', string>>;
+    texts?: {
+        trigger?: string;
+    };
+    afterChange?: (locale: Locale) => unknown;
+};
+/**
+ * The languages of the root provider as a menu. Selecting one writes the lang cookie (the
+ * only place it is born; the middleware never sets it), then calls `afterChange` or
+ * reloads the page. Renders nothing with fewer than two languages.
+ */
+export declare function LanguageSwitcher({ classes, texts, afterChange }: LanguageSwitcherProps): import("react").JSX.Element | null;

package/dist/react/language-switcher.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { useI18n, useI18nCookie } from "./provider.js";
+const join = (...names) => names.filter(Boolean).join(' ') || undefined;
+/**
+ * The languages of the root provider as a menu. Selecting one writes the lang cookie (the
+ * only place it is born; the middleware never sets it), then calls `afterChange` or
+ * reloads the page. Renders nothing with fewer than two languages.
+ */
+export function LanguageSwitcher({ classes = {}, texts, afterChange }) {
+    const { locale, languages } = useI18n();
+    const cookie = useI18nCookie();
+    const [open, setOpen] = useState(false);
+    const root = useRef(null);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onClick = (event) => {
+            if (!root.current?.contains(event.target))
+                setOpen(false);
+        };
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape')
+                setOpen(false);
+        };
+        document.addEventListener('click', onClick);
+        document.addEventListener('keydown', onKeyDown);
+        return () => {
+            document.removeEventListener('click', onClick);
+            document.removeEventListener('keydown', onKeyDown);
+        };
+    }, [open]);
+    const entries = Object.entries(languages).flatMap(([code, language]) => (language ? [{ code, language }] : []));
+    if (entries.length < 2)
+        return null;
+    if (!cookie) {
+        throw new Error('[@edgekits/tanstack-i18n] LanguageSwitcher needs `cookie` on an I18nProvider above it');
+    }
+    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`;
+        setOpen(false);
+        if (afterChange)
+            afterChange(next);
+        else
+            window.location.reload();
+    };
+    return (_jsxs("div", { ref: root, className: classes.root, "data-ls-root": "", "data-open": open ? 'true' : 'false', children: [_jsx("button", { type: "button", "data-ls-trigger": "", className: classes.trigger, "aria-haspopup": "true", "aria-expanded": open, "aria-label": texts?.trigger ?? 'Switch language', onClick: () => setOpen(!open), children: _jsxs("svg", { className: classes.triggerIcon, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1", "aria-hidden": "true", children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("ellipse", { cx: "12", cy: "12", rx: "4", ry: "9" }), _jsx("path", { d: "M3 12h18" })] }) }), _jsx("div", { "data-ls-dropdown": "", className: classes.dropdown, role: "menu", hidden: !open, children: entries.map(({ code, language }) => {
+                    const isActive = code === locale;
+                    // The label is the language's own name: `lang` lets a screen reader say it in
+                    // that language.
+                    return (_jsx("button", { type: "button", className: join(classes.item, isActive && classes.itemActive), "data-ls-item": "", "data-lang": code, "data-active": isActive ? 'true' : undefined, "aria-current": isActive ? 'true' : undefined, role: "menuitem", disabled: isActive, onClick: () => select(code), children: _jsx("span", { className: classes.itemLabel, lang: code, children: language.name }) }, code));
+                }) })] }));
+}

package/dist/react/provider.d.ts

@@ -0,0 +1,28 @@
+import type { I18nConfig, I18nLanguage, Locale, Namespace } from '@edgekits/i18n-core';
+import { type ReactNode } from 'react';
+export type I18nLanguages = Readonly<Partial<Record<Locale, I18nLanguage>>>;
+export type I18nCookie = Readonly<I18nConfig['cookie']>;
+export type NamespaceTranslations<N extends Namespace> = N extends keyof I18n.Schema ? I18n.Schema[N] : Record<string, unknown>;
+type I18nContextValue = {
+    locale: Locale;
+    languages: I18nLanguages;
+    translations: Readonly<Record<string, unknown>>;
+    cookie: I18nCookie | undefined;
+};
+export type I18nProviderProps = {
+    locale?: Locale;
+    translations: Readonly<Record<string, unknown>>;
+    languages?: I18nLanguages;
+    cookie?: I18nCookie;
+    children?: ReactNode;
+};
+/**
+ * The translations a route's loader returned, for the components below it. Providers nest:
+ * the root route gives `common` (with `languages` and `cookie`), a page its own namespaces.
+ */
+export declare function I18nProvider({ locale, translations, languages, cookie, children }: I18nProviderProps): import("react").JSX.Element;
+export declare function useI18n(): Pick<I18nContextValue, 'locale' | 'languages' | 'translations'>;
+export declare function useI18nCookie(): I18nCookie | undefined;
+/** One namespace a route loader above this component has loaded. */
+export declare function useT<N extends Namespace>(namespace: N): NamespaceTranslations<N>;
+export {};

package/dist/react/provider.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+const I18nContext = createContext(null);
+/**
+ * The translations a route's loader returned, for the components below it. Providers nest:
+ * the root route gives `common` (with `languages` and `cookie`), a page its own namespaces.
+ */
+export function I18nProvider({ locale, translations, languages, cookie, children }) {
+    const outer = useContext(I18nContext);
+    const resolvedLocale = locale ?? outer?.locale;
+    if (resolvedLocale === undefined) {
+        throw new Error('[@edgekits/tanstack-i18n] the outermost I18nProvider needs a `locale`');
+    }
+    const value = useMemo(() => ({
+        locale: resolvedLocale,
+        languages: languages ?? outer?.languages ?? {},
+        translations: outer ? { ...outer.translations, ...translations } : translations,
+        cookie: cookie ?? outer?.cookie,
+    }), [resolvedLocale, languages, cookie, translations, outer]);
+    return _jsx(I18nContext.Provider, { value: value, children: children });
+}
+function useI18nContext() {
+    const value = useContext(I18nContext);
+    if (!value)
+        throw new Error('[@edgekits/tanstack-i18n] no I18nProvider above this component');
+    return value;
+}
+export function useI18n() {
+    const { locale, languages, translations } = useI18nContext();
+    return { locale, languages, translations };
+}
+// The switcher's cookie settings; not part of `useI18n`.
+export function useI18nCookie() {
+    return useI18nContext().cookie;
+}
+/** One namespace a route loader above this component has loaded. */
+export function useT(namespace) {
+    const translations = useI18nContext().translations[namespace];
+    if (translations === undefined) {
+        throw new Error(`[@edgekits/tanstack-i18n] namespace "${namespace}" is not loaded by a route loader above this component`);
+    }
+    return translations;
+}

package/dist/request-locale.d.ts

@@ -0,0 +1,24 @@
+import type { FallbackInputs } from '@edgekits/i18n-core';
+/**
+ * What the server entry reads from the core's instance (`createI18n`), structurally: the
+ * locale type `L` is inferred from it, so a literal config types `c.var.locale` and the
+ * loader's `locale` with its own keys.
+ */
+export type RequestI18n<L extends string> = {
+    readonly LANG_COOKIE_NAME: string;
+    parseLocale(value: unknown): L | null;
+    resolveFallbackLocale(inputs: FallbackInputs<L>): L;
+};
+export type RequestLocaleOptions = {
+    userPreference?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+};
+/**
+ * The locale of a request, from the request alone: the middleware and the loader both call
+ * this, so Hono's chain and TanStack's server functions (which cannot reach Hono's context)
+ * give the same answer. The core's cascade without its country step: the lang cookie, then
+ * `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.
+ */
+export declare function resolveRequestLocale<L extends string>(i18n: RequestI18n<L>, request: Request, options?: RequestLocaleOptions): Promise<L>;

package/dist/request-locale.js

@@ -0,0 +1,21 @@
+import { getCookie } from 'hono/cookie';
+/**
+ * The locale of a request, from the request alone: the middleware and the loader both call
+ * this, so Hono's chain and TanStack's server functions (which cannot reach Hono's context)
+ * give the same answer. The core's cascade without its country step: the lang cookie, then
+ * `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.
+ */
+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);
+    return i18n.resolveFallbackLocale({
+        cookieLocale: () => cookieLocale,
+        userPreference: () => preferred,
+        acceptLanguage: () => request.headers.get('accept-language'),
+        country: () => undefined,
+    });
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@edgekits/tanstack-i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "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",
+    "tanstack-start",
+    "react",
+    "hono",
+    "i18n",
+    "cloudflare",
+    "cloudflare-workers",
+    "kv",
+    "edge"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "Gary Stupak",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EdgeKits/i18n.git",
+    "directory": "packages/tanstack"
+  },
+  "homepage": "https://github.com/EdgeKits/i18n/tree/main/packages/tanstack#readme",
+  "bugs": {
+    "url": "https://github.com/EdgeKits/i18n/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "node --import tsx --test test/**/*.test.ts test/**/*.test.tsx",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@edgekits/i18n-core": "0.2.1"
+  },
+  "peerDependencies": {
+    "hono": "^4",
+    "react": "^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "hono": "^4.13.14",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  }
+}