@shop-on/i18n 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @shop-on/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.
+Lightweight i18n for TanStack Start. Handles locale routing, URL rewriting, cookie sync, and translations via `use-intl`.
+
+## Strategy
+
+- No prefix for default locale (`/about`)
+- Prefix for other locales (`/en/about`)
+- Ignored paths (`/api`, `/rpc`) bypass locale handling
+
+## Exports
+
+```ts
+// Isomorphic — factories + React hooks + cookie utils
+import { createI18nClient, IntlProvider, useTranslations } from "@shop-on/i18n";
+import { LOCALE_COOKIE, createCookieHeader, parseLocaleCookie } from "@shop-on/i18n";
+
+// Server only — middleware + cookie utils
+import { createI18nServer, createCookieHeader } from "@shop-on/i18n/server";
+```
+
+The cookie utils on the root entry serve cookie-only consumers (apps/admin reads
+`spn-locale` on both server and client — no URL prefixes; see `apps/admin/src/lib/locale.ts`).
+Path-prefixed surfaces (themes) keep using `createI18nClient` / `createI18nServer`.
+
+## Usage
+
+Themes keep their locale list in a root-level `theme.config.json` so the runtime and the build (postbuild script) share a single source of truth:
+
+```ts
+// lib/i18n.ts — theme reads from its own theme.config.json
+import config from "../../theme.config.json";
+
+const i18n = createI18nClient({
+  defaultLocale: "mn",
+  locales: config.locales,
+});
+
+export const { getCurrentLocale, deLocalizeUrl, localizeUrl, isValidLocale } = i18n;
+```
+
+## Adding a language to a theme
+
+1. Add the locale to `themes/<name>/theme.config.json#locales` (the single source of truth — runtime + build both read this file)
+2. Create a translation JSON catalog at `themes/<name>/src/locales/<locale>.default.json`
+3. Run `pnpm build` — postbuild copies `locales` into `.output/theme.json#available_locales`, which the Rails API validates on upload

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/core/isomorphic.d.ts

@@ -0,0 +1,10 @@
+import { I18nConfig, I18nConfigInput } from "./shared.js";
+//#region src/core/isomorphic.d.ts
+export declare function createI18nClient<L extends string>(config: I18nConfigInput<L>): {
+  getCurrentLocale: import("@tanstack/react-start").IsomorphicFn<[], L, L>;
+  deLocalizeUrl: (url: URL) => URL;
+  localizeUrl: (url: URL) => URL;
+  isValidLocale: (locale: string | undefined) => locale is L;
+  getConfig: () => I18nConfig<L>;
+};
+//#endregion

package/dist/core/isomorphic.js

@@ -0,0 +1,48 @@
+import { extractLocaleFromPath, parseLocaleCookie, resolveConfigInput, shouldIgnorePath } from "./shared.js";
+import { getRequest } from "@tanstack/react-start/server";
+import { createIsomorphicFn } from "@tanstack/react-start";
+//#region src/core/isomorphic.ts
+function createI18nClient(config) {
+	const getConfig = resolveConfigInput(config);
+	const getCurrentLocale = createIsomorphicFn().server(() => {
+		const cfg = getConfig();
+		const request = getRequest();
+		const url = new URL(request.url);
+		if (shouldIgnorePath(url.pathname)) return parseLocaleCookie(request.headers.get("cookie"), cfg.locales) ?? cfg.defaultLocale;
+		return extractLocaleFromPath(url.pathname, cfg) ?? cfg.defaultLocale;
+	}).client(() => {
+		const cfg = getConfig();
+		if (shouldIgnorePath(window.location.pathname)) return parseLocaleCookie(document.cookie, cfg.locales) ?? cfg.defaultLocale;
+		return extractLocaleFromPath(window.location.pathname, cfg) ?? cfg.defaultLocale;
+	});
+	function deLocalizeUrl(url) {
+		if (shouldIgnorePath(url.pathname)) return url;
+		const locale = extractLocaleFromPath(url.pathname, getConfig());
+		if (locale) {
+			const newUrl = new URL(url);
+			newUrl.pathname = url.pathname.replace(`/${locale}`, "") || "/";
+			return newUrl;
+		}
+		return url;
+	}
+	function localizeUrl(url) {
+		if (shouldIgnorePath(url.pathname)) return url;
+		const locale = getCurrentLocale();
+		if (locale === getConfig().defaultLocale) return url;
+		const newUrl = new URL(url);
+		newUrl.pathname = `/${locale}${url.pathname === "/" ? "" : url.pathname}`;
+		return newUrl;
+	}
+	function isValidLocale(locale) {
+		return getConfig().locales.includes(locale);
+	}
+	return {
+		getCurrentLocale,
+		deLocalizeUrl,
+		localizeUrl,
+		isValidLocale,
+		getConfig
+	};
+}
+//#endregion
+export { createI18nClient };

package/dist/core/runtime-config.d.ts

@@ -0,0 +1,7 @@
+import { I18nConfig } from "./shared.js";
+//#region src/core/runtime-config.d.ts
+export declare function setRuntimeI18nConfig<L extends string>(config: I18nConfig<L>): void;
+export declare function getRuntimeI18nConfig<L extends string>(): I18nConfig<L> | undefined;
+export declare function createRuntimeI18nConfigProvider<L extends string>(fallback: I18nConfig<L>): () => I18nConfig<L>;
+export declare function runtimeI18nConfigScript(config: I18nConfig<string>): string;
+//#endregion

package/dist/core/runtime-config.js

@@ -0,0 +1,16 @@
+//#region src/core/runtime-config.ts
+const GLOBAL_KEY = "__SPN_I18N_CONFIG__";
+function setRuntimeI18nConfig(config) {
+	globalThis[GLOBAL_KEY] = config;
+}
+function getRuntimeI18nConfig() {
+	return globalThis[GLOBAL_KEY];
+}
+function createRuntimeI18nConfigProvider(fallback) {
+	return () => getRuntimeI18nConfig() ?? fallback;
+}
+function runtimeI18nConfigScript(config) {
+	return `window.${GLOBAL_KEY}=${JSON.stringify(config).replace(/</g, "\\u003c")}`;
+}
+//#endregion
+export { createRuntimeI18nConfigProvider, getRuntimeI18nConfig, runtimeI18nConfigScript, setRuntimeI18nConfig };

package/dist/core/server.d.ts

@@ -0,0 +1,13 @@
+import { I18nConfigInput } from "./shared.js";
+//#region src/core/server.d.ts
+export type LocaleMiddlewareResult = {
+  redirect?: Response;
+  setCookie?: {
+    name: string;
+    value: string;
+  };
+};
+export declare function createI18nServer<L extends string>(config: I18nConfigInput<L>): {
+  handleLocaleMiddleware: (request: Request) => LocaleMiddlewareResult;
+};
+//#endregion

package/dist/core/server.js

@@ -0,0 +1,42 @@
+import { LOCALE_COOKIE, extractAnyLocaleFromPath, extractLocaleFromPath, isValidLocale, parseLocaleCookie, resolveConfigInput, shouldIgnorePath } from "./shared.js";
+//#region src/core/server.ts
+function redirectTo(url, status) {
+	return new Response(null, {
+		status,
+		headers: { Location: url.pathname + url.search }
+	});
+}
+function createI18nServer(config) {
+	const getConfig = resolveConfigInput(config);
+	function handleLocaleMiddleware(request) {
+		const cfg = getConfig();
+		const url = new URL(request.url);
+		const pathname = url.pathname;
+		if (shouldIgnorePath(pathname)) return {};
+		if (pathname.startsWith(`/${cfg.defaultLocale}/`) || pathname === `/${cfg.defaultLocale}`) {
+			url.pathname = pathname.replace(`/${cfg.defaultLocale}`, "") || "/";
+			return { redirect: redirectTo(url, 301) };
+		}
+		const anyLocale = extractAnyLocaleFromPath(pathname);
+		if (anyLocale && !isValidLocale(anyLocale, cfg.locales)) {
+			url.pathname = pathname.replace(`/${anyLocale}`, "") || "/";
+			return { redirect: redirectTo(url, 302) };
+		}
+		const urlLocale = extractLocaleFromPath(pathname, cfg);
+		if (urlLocale) {
+			const strippedPath = pathname.replace(`/${urlLocale}`, "") || "/";
+			if (shouldIgnorePath(strippedPath)) {
+				url.pathname = strippedPath;
+				return { redirect: redirectTo(url, 301) };
+			}
+			if (urlLocale !== parseLocaleCookie(request.headers.get("cookie"), cfg.locales)) return { setCookie: {
+				name: LOCALE_COOKIE,
+				value: urlLocale
+			} };
+		}
+		return {};
+	}
+	return { handleLocaleMiddleware };
+}
+//#endregion
+export { createI18nServer };

package/dist/core/shared.d.ts

@@ -0,0 +1,15 @@
+//#region src/core/shared.d.ts
+export declare const LOCALE_COOKIE = "spn-locale";
+export declare const PLATFORM_LOCALES: readonly ["mn", "en", "zh", "ru", "ko", "ja", "de", "fr", "es"];
+export type PlatformLocale = (typeof PLATFORM_LOCALES)[number];
+export declare const NATIVE_LOCALE_NAMES: Record<string, string>;
+export declare function localeDisplayName(locale: string): string;
+export type I18nConfig<L extends string> = {
+  defaultLocale: L;
+  locales: readonly L[];
+};
+export type I18nConfigInput<L extends string> = I18nConfig<L> | (() => I18nConfig<L>);
+export declare function shouldIgnorePath(pathname: string): boolean;
+export declare function parseLocaleCookie<L extends string>(cookie: string | null, locales: readonly L[], cookieName?: string): L | null;
+export declare function createCookieHeader(name: string, value: string): string;
+//#endregion

package/dist/core/shared.js

@@ -0,0 +1,55 @@
+//#region src/core/shared.ts
+const LOCALE_COOKIE = "spn-locale";
+const ignoredPathsRegex = /^\/(?:api|rpc)(?:\/|$)/;
+const PLATFORM_LOCALES = [
+	"mn",
+	"en",
+	"zh",
+	"ru",
+	"ko",
+	"ja",
+	"de",
+	"fr",
+	"es"
+];
+const NATIVE_LOCALE_NAMES = {
+	mn: "Монгол",
+	en: "English",
+	zh: "中文",
+	ru: "Русский",
+	ko: "한국어",
+	ja: "日本語",
+	de: "Deutsch",
+	fr: "Français",
+	es: "Español"
+};
+function localeDisplayName(locale) {
+	return NATIVE_LOCALE_NAMES[locale] ?? locale;
+}
+function resolveConfigInput(input) {
+	return typeof input === "function" ? input : () => input;
+}
+function shouldIgnorePath(pathname) {
+	return ignoredPathsRegex.test(pathname);
+}
+function isValidLocale(locale, locales) {
+	return locales.includes(locale);
+}
+function extractLocaleFromPath(pathname, config) {
+	const locale = /^\/([a-z]{2})(?:\/|$)/.exec(pathname)?.[1];
+	return locale && isValidLocale(locale, config.locales) && locale !== config.defaultLocale ? locale : null;
+}
+function extractAnyLocaleFromPath(pathname) {
+	const locale = /^\/([a-z]{2})(?:\/|$)/.exec(pathname)?.[1];
+	return locale && isValidLocale(locale, PLATFORM_LOCALES) ? locale : null;
+}
+function parseLocaleCookie(cookie, locales, cookieName = LOCALE_COOKIE) {
+	if (!cookie) return null;
+	const locale = new RegExp(`(?:^|;\\s*)${cookieName}=([^;]+)`).exec(cookie)?.[1];
+	return locale && isValidLocale(locale, locales) ? locale : null;
+}
+function createCookieHeader(name, value) {
+	return `${name}=${value}; Path=/; Max-Age=31536000; SameSite=Lax`;
+}
+//#endregion
+export { LOCALE_COOKIE, NATIVE_LOCALE_NAMES, PLATFORM_LOCALES, createCookieHeader, extractAnyLocaleFromPath, extractLocaleFromPath, isValidLocale, localeDisplayName, parseLocaleCookie, resolveConfigInput, shouldIgnorePath };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { I18nConfig, I18nConfigInput, LOCALE_COOKIE, NATIVE_LOCALE_NAMES, PLATFORM_LOCALES, PlatformLocale, createCookieHeader, localeDisplayName, parseLocaleCookie } from "./core/shared.js";
+import { createI18nClient } from "./core/isomorphic.js";
+import { createRuntimeI18nConfigProvider, getRuntimeI18nConfig, runtimeI18nConfigScript, setRuntimeI18nConfig } from "./core/runtime-config.js";
+import { IntlProvider, createTranslator, useFormatter, useLocale, useTranslations } from "use-intl";
+import { AbstractIntlMessages } from "use-intl/core";
+export { type AbstractIntlMessages, type I18nConfig, type I18nConfigInput, IntlProvider, LOCALE_COOKIE, NATIVE_LOCALE_NAMES, PLATFORM_LOCALES, type PlatformLocale, createCookieHeader, createI18nClient, createRuntimeI18nConfigProvider, createTranslator, getRuntimeI18nConfig, localeDisplayName, parseLocaleCookie, runtimeI18nConfigScript, setRuntimeI18nConfig, useFormatter, useLocale, useTranslations };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { LOCALE_COOKIE, NATIVE_LOCALE_NAMES, PLATFORM_LOCALES, createCookieHeader, localeDisplayName, parseLocaleCookie } from "./core/shared.js";
+import { createI18nClient } from "./core/isomorphic.js";
+import { createRuntimeI18nConfigProvider, getRuntimeI18nConfig, runtimeI18nConfigScript, setRuntimeI18nConfig } from "./core/runtime-config.js";
+import { IntlProvider, createTranslator, useFormatter, useLocale, useTranslations } from "use-intl";
+export { IntlProvider, LOCALE_COOKIE, NATIVE_LOCALE_NAMES, PLATFORM_LOCALES, createCookieHeader, createI18nClient, createRuntimeI18nConfigProvider, createTranslator, getRuntimeI18nConfig, localeDisplayName, parseLocaleCookie, runtimeI18nConfigScript, setRuntimeI18nConfig, useFormatter, useLocale, useTranslations };

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { I18nConfig, I18nConfigInput, LOCALE_COOKIE, PLATFORM_LOCALES, PlatformLocale, createCookieHeader, shouldIgnorePath } from "./core/shared.js";
+import { createRuntimeI18nConfigProvider, getRuntimeI18nConfig, runtimeI18nConfigScript, setRuntimeI18nConfig } from "./core/runtime-config.js";
+import { LocaleMiddlewareResult, createI18nServer } from "./core/server.js";
+export { type I18nConfig, type I18nConfigInput, LOCALE_COOKIE, type LocaleMiddlewareResult, PLATFORM_LOCALES, type PlatformLocale, createCookieHeader, createI18nServer, createRuntimeI18nConfigProvider, getRuntimeI18nConfig, runtimeI18nConfigScript, setRuntimeI18nConfig, shouldIgnorePath };

package/dist/server.js

@@ -0,0 +1,4 @@
+import { LOCALE_COOKIE, PLATFORM_LOCALES, createCookieHeader, shouldIgnorePath } from "./core/shared.js";
+import { createRuntimeI18nConfigProvider, getRuntimeI18nConfig, runtimeI18nConfigScript, setRuntimeI18nConfig } from "./core/runtime-config.js";
+import { createI18nServer } from "./core/server.js";
+export { LOCALE_COOKIE, PLATFORM_LOCALES, createCookieHeader, createI18nServer, createRuntimeI18nConfigProvider, getRuntimeI18nConfig, runtimeI18nConfigScript, setRuntimeI18nConfig, shouldIgnorePath };

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@shop-on/i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "license": "SEE LICENSE IN dist/LICENSE.md",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./dist/server.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "use-intl": "4.14.9"
+  },
+  "devDependencies": {
+    "@tanstack/react-start": "1.169.3",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@tanstack/react-start": "~1.169.3"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --maxWorkers=2"
+  }
 }