@markcom/i18n 0.0.0-stage → 0.1.0

package/dist/i18next.d.mts

@@ -0,0 +1,4 @@
+import { LocaleRecord, LocaleSet } from "./locales.mjs";
+import { i18n } from "i18next";
+/** A ready i18next instance serving every locale, starting in the default language. */
+export declare function createI18n<Lang extends string, Locale extends LocaleRecord>(locales: LocaleSet<Lang, Locale>): Promise<i18n>;

package/dist/i18next.mjs

@@ -0,0 +1,16 @@
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+// src/i18next.ts
+/** A ready i18next instance serving every locale, starting in the default language. */
+async function createI18n(locales) {
+	const instance = i18next.createInstance();
+	const resources = Object.fromEntries(locales.entries.map(([lang, translation]) => [lang, { translation }]));
+	await instance.use(initReactI18next).init({
+		resources,
+		lng: locales.defaultLang,
+		fallbackLng: locales.defaultLang,
+		interpolation: { escapeValue: false }
+	});
+	return instance;
+}
+export { createI18n };

package/dist/locales.d.mts

@@ -0,0 +1,24 @@
+import { ParseKeys } from "i18next";
+export type LocaleValue = string | LocaleRecord;
+export type LocaleRecord = {
+  readonly [key: string]: LocaleValue;
+};
+/** The string at a dotted key path; throws if missing or not a string. */
+export declare function lookupString(locale: LocaleRecord, key: string): string;
+/** Every dotted key path that ends in a string. */
+export declare function leafKeys(locale: LocaleRecord): string[];
+/** A site's languages and their locale files; the default locale holds the full key set. */
+export declare class LocaleSet<Lang extends string, Locale extends LocaleRecord> {
+  readonly defaultLang: Lang;
+  readonly defaultLocale: Locale;
+  readonly langs: readonly Lang[];
+  private readonly locales;
+  constructor(locales: Readonly<Record<Lang, Locale>>, defaultLang: NoInfer<Lang>);
+  get entries(): readonly (readonly [Lang, Locale])[];
+  localeFor(lang: Lang): Locale;
+  isSupportedLang(lang: string | undefined): lang is Lang;
+  /** The best supported match for the browser's preferences, else the default. */
+  detectLang(preferred: readonly string[]): Lang;
+  /** True for a key of the default locale. ViewModels hold these; views turn them into text. */
+  isLocaleKey(key: string): key is ParseKeys;
+}

package/dist/locales.mjs

@@ -0,0 +1,50 @@
+import { match } from "@formatjs/intl-localematcher";
+import { flatten } from "flat";
+// src/locales.ts
+/** Every dotted key path that ends in a string, with its string. */
+function flattenLocale(locale) {
+	return new Map(Object.entries(flatten(locale)));
+}
+/** The string at a dotted key path; throws if missing or not a string. */
+function lookupString(locale, key) {
+	const value = flattenLocale(locale).get(key);
+	if (value === void 0) throw new Error(`Locale key is missing or not a string: ${key}`);
+	return value;
+}
+/** Every dotted key path that ends in a string. */
+function leafKeys(locale) {
+	return [...flattenLocale(locale).keys()];
+}
+/** A site's languages and their locale files; the default locale holds the full key set. */
+var LocaleSet = class {
+	defaultLang;
+	defaultLocale;
+	langs;
+	locales;
+	constructor(locales, defaultLang) {
+		this.locales = new Map(Object.entries(locales).filter((entry) => Object.hasOwn(locales, entry[0])));
+		this.langs = [...this.locales.keys()];
+		this.defaultLang = defaultLang;
+		this.defaultLocale = this.localeFor(defaultLang);
+	}
+	get entries() {
+		return [...this.locales.entries()];
+	}
+	localeFor(lang) {
+		const locale = this.locales.get(lang);
+		if (locale === void 0) throw new Error(`No locale for language: ${lang}`);
+		return locale;
+	}
+	isSupportedLang(lang) {
+		return this.langs.some((supported) => supported === lang);
+	}
+	/** The best supported match for the browser's preferences, else the default. */
+	detectLang(preferred) {
+		return match(preferred, this.langs, this.defaultLang);
+	}
+	/** True for a key of the default locale. ViewModels hold these; views turn them into text. */
+	isLocaleKey(key) {
+		return leafKeys(this.defaultLocale).includes(key);
+	}
+};
+export { LocaleSet, leafKeys, lookupString };

package/dist/react-router.d.mts

@@ -0,0 +1,27 @@
+import { LocaleRecord, LocaleSet } from "./locales.mjs";
+import { RouteObject } from "react-router";
+import { ComponentType } from "react";
+/** The one thing routing needs from i18next, so tests can pass a fake. */
+export interface LanguageSwitcher {
+  changeLanguage(lang: string): Promise<unknown>;
+}
+export type LanguageRoutesOptions<Lang extends string, Locale extends LocaleRecord> = {
+  locales: LocaleSet<Lang, Locale>;
+  i18n: LanguageSwitcher;
+  /** The site's root path, usually `/`. */
+  rootPath: string;
+  /** The browser's language preferences: `() => navigator.languages`. */
+  preferredLanguages: () => readonly string[];
+  /** Gets the page language: `document.documentElement`. */
+  documentElement: {
+    lang: string;
+  };
+  /** Renders around every page of a language; its Outlet shows the children. */
+  layout: ComponentType | null;
+  children: RouteObject[];
+};
+/**
+ * The `/<lang>/…` route: a supported language switches i18next and the page language before
+ * rendering; no language or an unsupported one redirects to the one detectLang picks.
+ */
+export declare function languageRoutes<Lang extends string, Locale extends LocaleRecord>(options: LanguageRoutesOptions<Lang, Locale>): RouteObject[];

package/dist/react-router.mjs

@@ -0,0 +1,22 @@
+import { redirect } from "react-router";
+// src/react-router.ts
+/**
+* The `/<lang>/…` route: a supported language switches i18next and the page language before
+* rendering; no language or an unsupported one redirects to the one detectLang picks.
+*/
+function languageRoutes(options) {
+	const { locales, rootPath } = options;
+	return [{
+		path: `${rootPath}:lang?`,
+		Component: options.layout,
+		loader: async ({ params }) => {
+			const { lang } = params;
+			if (!locales.isSupportedLang(lang)) return redirect(`${rootPath}${locales.detectLang(options.preferredLanguages())}`);
+			await options.i18n.changeLanguage(lang);
+			options.documentElement.lang = lang;
+			return null;
+		},
+		children: options.children
+	}];
+}
+export { languageRoutes };

package/dist/vite.d.mts

@@ -0,0 +1,12 @@
+import { LocaleRecord, LocaleSet } from "./locales.mjs";
+import { Plugin } from "vite";
+export type LocaleHtmlOptions<Lang extends string, Locale extends LocaleRecord> = {
+  locales: LocaleSet<Lang, Locale>;
+  /** Values for `{{name}}` placeholders, such as the theme colour. `{{lang}}` is filled in. */
+  values: ReadonlyMap<string, string>;
+};
+/**
+ * Fills index.html from the default locale, and stops `vite` and `vite build` when a locale
+ * file is incomplete or index.html has text or colours that do not come from a placeholder.
+ */
+export declare function localeHtmlPlugin<Lang extends string, Locale extends LocaleRecord>(options: LocaleHtmlOptions<Lang, Locale>): Plugin;

package/dist/vite.mjs

@@ -0,0 +1,104 @@
+import { leafKeys, lookupString } from "./locales.mjs";
+import { flatten } from "flat";
+import { checkInvalidTranslations, checkMissingTranslations } from "@lingual/i18n-check";
+import escapeHtml from "escape-html";
+// src/vite.ts
+/** index.html placeholders filled by localeHtmlPlugin. */
+const HTML_PLACEHOLDER = /\{\{[\w:.]+\}\}/g;
+const TEXT_BETWEEN_TAGS = /(?<=>)[^<>]+(?=<)/g;
+const TEXT_ATTRIBUTE = /(?<= (?:content|title|alt|aria-label|aria-description|placeholder)=")[^"]*(?=")/g;
+const HEX_COLOUR = /#[0-9a-f]{3,8}\b/gi;
+const CHECK_OPTIONS = { format: "i18next" };
+/** Meta content that is configuration, not text a person reads. */
+const ALLOWED_META_CONTENT = /* @__PURE__ */ new Set(["width=device-width, initial-scale=1"]);
+/** i18n-check compares flat files: one dotted key per string. */
+function flat(locale) {
+	return flatten(locale);
+}
+function withoutPlaceholders(text) {
+	return text.replace(HTML_PLACEHOLDER, "").trim();
+}
+/** Keys whose string is blank. */
+function findBlankStrings(locale) {
+	return leafKeys(locale).filter((key) => lookupString(locale, key).trim() === "");
+}
+function keysMissingFrom(target, source) {
+	return Object.values(checkMissingTranslations(flat(source), { target: flat(target) }, CHECK_OPTIONS)).flat();
+}
+/** Keys the default locale has and this locale lacks. */
+function findMissingKeys(defaultLocale, locale) {
+	return keysMissingFrom(locale, defaultLocale);
+}
+/** Keys this locale has and the default locale lacks. */
+function findExtraKeys(defaultLocale, locale) {
+	return keysMissingFrom(defaultLocale, locale);
+}
+/** Keys whose interpolation placeholders or nesting differ from the default locale. */
+function findInvalidTranslations(defaultLocale, locale) {
+	return Object.values(checkInvalidTranslations(flat(defaultLocale), { locale: flat(locale) }, CHECK_OPTIONS)).flat().map(({ key }) => key);
+}
+/** Text in index.html a person would read that does not come from a locale placeholder. */
+function findLiteralHtmlText(html) {
+	const betweenTags = [...html.matchAll(TEXT_BETWEEN_TAGS)].map(([text]) => text);
+	const inAttributes = [...html.matchAll(TEXT_ATTRIBUTE)].map(([value]) => value).filter((value) => !ALLOWED_META_CONTENT.has(value));
+	return [...betweenTags, ...inAttributes].map(withoutPlaceholders).filter((text) => text !== "");
+}
+/** Colours written into index.html instead of coming from the tokens. */
+function findHtmlColours(html) {
+	return [...html.matchAll(HEX_COLOUR)].map(([colour]) => colour);
+}
+/** Every problem in a site's locale files, one message each; empty when they are all fine. */
+function findLocaleProblems(locales) {
+	const defaultFile = `${locales.defaultLang}.json`;
+	const blank = findBlankStrings(locales.defaultLocale).map((key) => `${defaultFile}: ${key} is blank`);
+	const translations = locales.langs.filter((lang) => lang !== locales.defaultLang).flatMap((lang) => {
+		const locale = locales.localeFor(lang);
+		const file = `${lang}.json`;
+		return [
+			...findMissingKeys(locales.defaultLocale, locale).map((key) => `${file}: ${key} is missing`),
+			...findExtraKeys(locales.defaultLocale, locale).map((key) => `${file}: ${key} is not in ${defaultFile}`),
+			...findInvalidTranslations(locales.defaultLocale, locale).map((key) => `${file}: ${key} has different placeholders from ${defaultFile}`)
+		];
+	});
+	return [...blank, ...translations];
+}
+/** Every problem in a site's index.html, one message each; empty when it is fine. */
+function findIndexHtmlProblems(html) {
+	return [...findLiteralHtmlText(html).map((text) => `index.html: "${text}" is literal text; use {{t:key}}`), ...findHtmlColours(html).map((colour) => `index.html: ${colour} is a hard-coded colour; use {{name}}`)];
+}
+/** `{{t:meta.title}}` inserts a locale string; `{{lang}}` inserts a named value. */
+const PLACEHOLDER = /\{\{(t:)?([\w.]+)\}\}/g;
+const PLUGIN_NAME = "markcom-locale-html";
+function resolveValue(values, name) {
+	const value = values.get(name);
+	if (value === void 0) throw new Error(`index.html placeholder {{${name}}} has no value`);
+	return value;
+}
+function failOnProblems(problems) {
+	if (problems.length > 0) throw new Error(`Locale problems:\n${problems.join("\n")}`);
+}
+/** Replaces every placeholder in index.html, HTML-escaped; fails on an unknown key or value. */
+function renderLocaleHtml(html, locale, values) {
+	return html.replace(PLACEHOLDER, (_match, localePrefix, key) => escapeHtml(localePrefix === void 0 ? resolveValue(values, key) : lookupString(locale, key)));
+}
+/**
+* Fills index.html from the default locale, and stops `vite` and `vite build` when a locale
+* file is incomplete or index.html has text or colours that do not come from a placeholder.
+*/
+function localeHtmlPlugin(options) {
+	const values = new Map([["lang", options.locales.defaultLang], ...options.values]);
+	return {
+		name: PLUGIN_NAME,
+		buildStart: () => {
+			failOnProblems(findLocaleProblems(options.locales));
+		},
+		transformIndexHtml: {
+			order: "pre",
+			handler: (html) => {
+				failOnProblems(findIndexHtmlProblems(html));
+				return renderLocaleHtml(html, options.locales.defaultLocale, values);
+			}
+		}
+	};
+}
+export { localeHtmlPlugin };

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@markcom/i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Locale checks, language detection and routing, and i18next set-up for the react-ui websites.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarkIsMyNames/ClaudeSkills.git",
+    "directory": "libraries/markcom-i18n"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/locales.d.mts",
+      "default": "./dist/locales.mjs"
+    },
+    "./i18next": {
+      "types": "./dist/i18next.d.mts",
+      "default": "./dist/i18next.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "default": "./dist/vite.mjs"
+    },
+    "./react-router": {
+      "types": "./dist/react-router.d.mts",
+      "default": "./dist/react-router.mjs"
+    }
+  },
+  "prettier": "@markcom/web-config/prettier",
+  "scripts": {
+    "build": "tsdown src/locales.ts src/i18next.ts src/vite.ts src/react-router.ts --dts --format esm --clean",
+    "lint": "eslint --max-warnings=0 .",
+    "format": "prettier --ignore-path ../../.gitignore --write .",
+    "format:check": "prettier --ignore-path ../../.gitignore --check .",
+    "typecheck": "tsc",
+    "audit": "npm audit --audit-level=low",
+    "test": "vitest run --coverage",
+    "test:e2e": "playwright test"
+  },
+  "dependencies": {
+    "@formatjs/intl-localematcher": "^0.10.1",
+    "escape-html": "^1.0.3",
+    "flat": "^6.0.1",
+    "@lingual/i18n-check": "^0.9.5"
+  },
+  "peerDependencies": {
+    "i18next": "^27.1.1",
+    "react-i18next": "^18.0.1",
+    "vite": "^8.3.7",
+    "react-router": "^8.5.1"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@markcom/web-config": "file:../markcom-web-config",
+    "@playwright/test": "^1.65.0",
+    "@types/escape-html": "^1.0.4",
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "@vitest/coverage-v8": "^5.1.0",
+    "eslint": "^10.14.0",
+    "i18next": "^27.1.1",
+    "jiti": "^2.7.0",
+    "prettier": "^3.9.10",
+    "react": "^19.3.1",
+    "react-i18next": "^18.0.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.7",
+    "vitest": "^5.1.0",
+    "@tsconfig/strictest": "^2.0.8",
+    "tsdown": "^0.23.7",
+    "react-router": "^8.5.1",
+    "react-dom": "^19.3.1",
+    "@vitejs/plugin-react": "^6.3.0",
+    "@types/react-dom": "^19.3.0"
+  },
+  "overrides": {
+    "minimatch": "^11.0.5",
+    "glob": "^14.0.4"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.