emdash-schema-i18n 0.0.0-stage → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serhii Parshyn
+
+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,177 @@
-# Temporary Holding Version
+# emdash-schema-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.
+> Dynamic schema, collections, and block types localization for **EmDash CMS** Admin UI.
+
+[![npm version](https://img.shields.io/npm/v/emdash-schema-i18n.svg)](https://www.npmjs.com/package/emdash-schema-i18n)
+[![npm downloads](https://img.shields.io/npm/dm/emdash-schema-i18n.svg)](https://www.npmjs.com/package/emdash-schema-i18n)
+[![license](https://img.shields.io/npm/l/emdash-schema-i18n.svg)](LICENSE)
+
+**Author:** Serhii Parshyn (<serhii@parshyn.com>)
+
+---
+
+## Overview
+
+In EmDash CMS, metadata for collections, fields, and block types (`label`, `labelSingular`, `description`, `category`) are stored statically in the database schema. When building multilingual admin sites, developers previously had to combine languages with slashes (e.g. `"Кейси / Case studies"` or `"Заголовок / Title"`), which cluttered the interface.
+
+`emdash-schema-i18n` solves this seamlessly by dynamically localizing schema metadata based on the administrator's active session language (`emdash-locale` cookie or `Accept-Language` header).
+
+---
+
+## Features
+
+- **Direct English-first schema:** Keep all your database models and `seed.json` schemas in clean English without slashes.
+- **Dictionary phrase lookup:** Easily map English phrases to any target language (`"Case studies": "Кейси"`, `"Chapter": "Розділ"`).
+- **Exact path overrides:** Override specific fields when needed (e.g. `collections.case_study.fields.title.label`).
+- **Comprehensive coverage:** Localizes collections, singular labels, field inputs, dropdown options, and block types with all their nested version fields.
+- **Automatic Scaffolding:** Scans schemas and block types to scaffold untranslated strings via CLI.
+- **Zero-config slash fallback:** Still supports automatic splitting of legacy bilingual strings (`"Українська / English"`).
+
+---
+
+## Compatibility & Requirements
+
+| Component | Supported Version | Notes |
+| :--- | :--- | :--- |
+| **EmDash CMS (`emdash`)** | `>= 1.0.1` | Tested up to `1.3.0+` |
+| **EmDash Admin (`@emdash-cms/admin`)** | `>= 1.2.0` | Required for admin UI |
+| **Astro** | `>= 6.0.0` | Supports Astro 6 and Astro 7 |
+| **Node.js** | `>= 22.16` | Required by EmDash runtime |
+| **React / React DOM** | `>= 18.0.0` | Fully supports React 18 & 19 |
+
+---
+
+## Installation
+
+Install the package from npm using your package manager of choice:
+
+```bash
+# npm
+npm install emdash-schema-i18n
+
+# pnpm
+pnpm add emdash-schema-i18n
+
+# yarn
+yarn add emdash-schema-i18n
+
+# bun
+bun add emdash-schema-i18n
+```
+
+---
+
+## Setup & Configuration
+
+### 1. In `astro.config.mjs`
+
+```javascript
+import { defineConfig } from "astro/config";
+import emdash from "emdash/astro";
+import { schemaLocalization } from "emdash-schema-i18n";
+import { adminDictionary } from "./src/i18n/admin";
+
+export default defineConfig({
+  integrations: [
+    emdash({
+      plugins: [
+        schemaLocalization({
+          dictionary: adminDictionary,
+        }),
+      ],
+      middleware: {
+        outer: "./src/lib/private-access-middleware.mjs",
+      },
+    }),
+  ],
+});
+```
+
+### 2. In Middleware (`src/lib/private-access-middleware.mjs`)
+
+```javascript
+import {
+  resolveAdminLocale,
+  localizeManifest,
+  localizeBlockTypesResponse,
+  localizeCollectionsResponse,
+} from "emdash-schema-i18n";
+import { adminDictionary } from "../i18n/admin.ts";
+
+export async function onRequest(context, next) {
+  const response = await next();
+
+  if (response?.status >= 200 && response?.status < 300) {
+    const pathname = context.url.pathname;
+    const isManifest = pathname === "/_emdash/api/manifest";
+    const isBlockTypes = pathname === "/_emdash/api/schema/block-types";
+    const isCollections = pathname.startsWith("/_emdash/api/schema/collections");
+
+    if (isManifest || isBlockTypes || isCollections) {
+      const locale = resolveAdminLocale(context.request);
+      const data = await response.clone().json();
+      let localized = data;
+
+      if (isManifest) {
+        localized = localizeManifest(data, locale, { dictionary: adminDictionary });
+      } else if (isBlockTypes) {
+        localized = localizeBlockTypesResponse(data, locale, { dictionary: adminDictionary });
+      } else if (isCollections) {
+        localized = localizeCollectionsResponse(data, locale, { dictionary: adminDictionary });
+      }
+
+      const headers = new Headers(response.headers);
+      headers.set("Content-Type", "application/json; charset=utf-8");
+      headers.set("Vary", "Cookie, Accept-Language");
+      return new Response(JSON.stringify(localized), {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      });
+    }
+  }
+
+  return response;
+}
+```
+
+### 3. Translation Dictionary (`src/i18n/admin.ts`)
+
+```typescript
+export const adminDictionary = {
+  uk: {
+    "Case studies": "Кейси",
+    "Case study": "Кейс",
+    "Disclaimer": "Дисклеймер",
+    "Chapter": "Розділ",
+    "Before and after": "До/після",
+    "Title (H1 and card)": "Заголовок (H1 і картка)",
+    "Visibility": "Видимість",
+  },
+};
+
+export default adminDictionary;
+```
+
+---
+
+## Scaffolding & CLI
+ 
+To extract all schema and block type strings into a translation dictionary automatically:
+
+```bash
+# Run directly via npx
+npx emdash-schema-i18n extract
+
+# Or add to your package.json scripts:
+# "i18n:extract": "emdash-schema-i18n extract"
+npm run i18n:extract
+```
+
+The CLI scans `seed/seed.json` and block types, preserves all existing translations, and appends any newly created untranslated fields.
+
+---
+
+## License
+
+[MIT](LICENSE) © Serhii Parshyn

package/bin/cli.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * CLI for emdash-schema-i18n.
+ *
+ * Scaffolds and synchronizes admin localization strings from EmDash seeds and schemas.
+ *
+ * Usage:
+ *   npx emdash-schema-i18n extract
+ *   npx emdash-schema-i18n extract --clean-seed
+ *   npx emdash-schema-i18n extract --seed=seed/seed.json --out=src/i18n/admin.ts
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+	console.log(`
+Usage: emdash-schema-i18n [command] [options]
+
+Commands:
+  extract              Scaffold/update translation dictionary from schema (default)
+
+Options:
+  --seed=<path>        Path to seed file (default: seed/seed.json or .emdash/seed.json)
+  --out=<path>         Path to output TS/JS dictionary (default: src/i18n/admin.ts)
+  --clean-seed         Remove bilingual slashes from the seed file, keeping English
+  -h, --help           Show help
+`);
+	process.exit(0);
+}
+
+const cwd = process.cwd();
+
+// Resolve seed path
+let seedPath = "";
+for (const arg of args) {
+	if (arg.startsWith("--seed=")) seedPath = path.resolve(cwd, arg.split("=")[1]);
+}
+if (!seedPath) {
+	const candidates = [
+		path.join(cwd, "seed", "seed.json"),
+		path.join(cwd, ".emdash", "seed.json"),
+		path.join(cwd, "seed.json"),
+	];
+	seedPath = candidates.find((p) => fs.existsSync(p)) || candidates[0];
+}
+
+// Resolve output path
+let outPath = "";
+for (const arg of args) {
+	if (arg.startsWith("--out=")) outPath = path.resolve(cwd, arg.split("=")[1]);
+}
+if (!outPath) {
+	outPath = path.join(cwd, "src", "i18n", "admin.ts");
+}
+
+const cleanSeed = args.includes("--clean-seed");
+
+if (!fs.existsSync(seedPath)) {
+	console.error(`Error: Seed file not found at ${seedPath}`);
+	process.exit(1);
+}
+
+console.log(`[emdash-schema-i18n] Reading schema from: ${seedPath}`);
+
+const seedContent = fs.readFileSync(seedPath, "utf-8");
+const seed = JSON.parse(seedContent);
+
+// Load existing translations if present
+let existingTranslations = {};
+if (fs.existsSync(outPath)) {
+	try {
+		const existingContent = fs.readFileSync(outPath, "utf-8");
+		const matches = existingContent.matchAll(/"((?:[^"\\]|\\.)+)"\s*:\s*"((?:[^"\\]|\\.)*)"/g);
+		for (const match of matches) {
+			const key = match[1].replace(/\\"/g, '"');
+			const val = match[2].replace(/\\"/g, '"');
+			existingTranslations[key] = val;
+		}
+	} catch (err) {
+		console.warn("Notice: Could not parse existing translation file, starting fresh:", err.message);
+	}
+}
+
+const extracted = new Map();
+
+function processString(str, parentObj, key) {
+	if (typeof str !== "string" || !str.trim()) return str;
+
+	if (str.includes(" / ")) {
+		const parts = str.split(" / ");
+		const uk = parts[0].trim();
+		const en = parts.slice(1).join(" / ").trim();
+
+		if (!extracted.has(en) || !extracted.get(en)) {
+			extracted.set(en, existingTranslations[en] || uk);
+		}
+
+		if (cleanSeed && parentObj && key) {
+			parentObj[key] = en;
+		}
+		return en;
+	} else {
+		const trimmed = str.trim();
+		if (!extracted.has(trimmed)) {
+			extracted.set(trimmed, existingTranslations[trimmed] || "");
+		}
+		return trimmed;
+	}
+}
+
+const TARGET_KEYS = new Set([
+	"label",
+	"labelSingular",
+	"description",
+	"category",
+	"placeholder",
+	"hint",
+]);
+
+function deepWalk(val) {
+	if (!val) return;
+	if (Array.isArray(val)) {
+		for (let i = 0; i < val.length; i++) {
+			const item = val[i];
+			if (typeof item === "string" && item.includes(" / ")) {
+				val[i] = processString(item, val, i);
+			} else if (item && typeof item === "object") {
+				deepWalk(item);
+			}
+		}
+	} else if (typeof val === "object") {
+		for (const [k, v] of Object.entries(val)) {
+			if (TARGET_KEYS.has(k) && typeof v === "string") {
+				processString(v, val, k);
+			} else if (typeof v === "object") {
+				deepWalk(v);
+			}
+		}
+	}
+}
+
+// 1. Process Block Types
+if (Array.isArray(seed.blockTypes)) {
+	deepWalk(seed.blockTypes);
+}
+
+// 2. Process Collections
+if (Array.isArray(seed.collections)) {
+	deepWalk(seed.collections);
+} else if (seed.collections && typeof seed.collections === "object") {
+	deepWalk(seed.collections);
+}
+
+// Save cleaned seed if requested
+if (cleanSeed) {
+	fs.writeFileSync(seedPath, JSON.stringify(seed, null, 2) + "\n", "utf-8");
+	console.log(`[emdash-schema-i18n] Cleaned seed file at ${seedPath} (removed bilingual slashes)`);
+}
+
+// Generate output file
+const sortedKeys = Array.from(extracted.keys()).sort((a, b) => a.localeCompare(b));
+let translatedCount = 0;
+let untranslatedCount = 0;
+
+const dictLines = sortedKeys.map((enKey) => {
+	const ukVal = extracted.get(enKey);
+	if (ukVal) {
+		translatedCount++;
+		return `\t\t${JSON.stringify(enKey)}: ${JSON.stringify(ukVal)},`;
+	} else {
+		untranslatedCount++;
+		return `\t\t${JSON.stringify(enKey)}: "", // TODO: translate`;
+	}
+});
+
+const isJson = outPath.endsWith(".json");
+let fileContent = "";
+
+if (isJson) {
+	const jsonObj = { uk: {} };
+	for (const key of sortedKeys) {
+		jsonObj.uk[key] = extracted.get(key) || "";
+	}
+	fileContent = JSON.stringify(jsonObj, null, 2) + "\n";
+} else {
+	fileContent = `// Generated and managed by emdash-schema-i18n CLI
+// Run "npx emdash-schema-i18n extract" after updating schema or block types.
+
+export const adminDictionary: Record<string, Record<string, string>> = {
+	uk: {
+${dictLines.join("\n")}
+	},
+};
+
+export type AdminLocale = keyof typeof adminDictionary;
+export default adminDictionary;
+`;
+}
+
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+fs.writeFileSync(outPath, fileContent, "utf-8");
+
+console.log(`[emdash-schema-i18n] Updated:      ${outPath}`);
+console.log(`[emdash-schema-i18n] Total strings: ${sortedKeys.length}`);
+console.log(`[emdash-schema-i18n] Translated:    ${translatedCount}`);
+if (untranslatedCount > 0) {
+	console.log(`[emdash-schema-i18n] Untranslated:  ${untranslatedCount} (marked with TODO)`);
+} else {
+	console.log(`[emdash-schema-i18n] All strings are translated!`);
+}

package/emdash-plugin.jsonc

@@ -0,0 +1,19 @@
+{
+  "slug": "schema-i18n",
+  "name": "Schema & Blocks i18n",
+  "version": "1.1.2",
+  "description": "Dynamic schema, collections, and block types localization for EmDash CMS Admin UI",
+  "license": "MIT",
+  "author": {
+    "name": "Serhii Parshyn",
+    "email": "serhii@parshyn.com"
+  },
+  "capabilities": [],
+  "allowedHosts": [],
+  "storage": {},
+  "release": {
+    "requires": {
+      "env:emdash": ">=1.0.1"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "emdash-schema-i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.2",
+  "description": "Dynamic schema, collections, and block types localization for EmDash CMS Admin UI",
+  "author": {
+    "name": "Serhii Parshyn",
+    "email": "serhii@parshyn.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NimitzUA/emdash-schema-i18n.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NimitzUA/emdash-schema-i18n/issues"
+  },
+  "homepage": "https://github.com/NimitzUA/emdash-schema-i18n#readme",
+  "keywords": [
+    "emdash",
+    "emdash-plugin",
+    "i18n",
+    "localization",
+    "schema",
+    "admin-ui"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "emdash-schema-i18n": "./bin/cli.mjs"
+  },
+  "type": "module",
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "import": "./src/index.mjs"
+    },
+    "./middleware": {
+      "import": "./src/middleware.mjs"
+    },
+    "./admin": "./src/admin/index.tsx"
+  },
+  "files": [
+    "src",
+    "bin",
+    "emdash-plugin.jsonc",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:live": "node --test test/e2e-live.test.mjs",
+    "example:init": "cd example && npx emdash secrets generate --write .env && npx emdash init && npx emdash seed seed/seed.json --on-conflict=update",
+    "example:dev": "ASTRO_TELEMETRY_DISABLED=1 astro dev --root example --host 127.0.0.1 --port 4321",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "peerDependencies": {
+    "@emdash-cms/admin": ">=1.2.0",
+    "emdash": ">=1.0.1",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/node": "^11.1.8",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/admin/index.tsx

@@ -0,0 +1,85 @@
+import * as React from "react";
+import { useLingui } from "@lingui/react";
+import { localizeString } from "../localizer.mjs";
+
+const DEFAULT_SEPARATOR = " / ";
+
+export interface LocalizeTextOptions {
+	separator?: string;
+	key?: string;
+	dictionary?: Record<string, Record<string, string>>;
+}
+
+/**
+ * Hook to retrieve the active admin UI locale.
+ */
+export function useAdminLocale(): string {
+	try {
+		const { i18n } = useLingui();
+		return i18n.locale || "en";
+	} catch {
+		return "en";
+	}
+}
+
+/**
+ * Hook to localize a string, phrase or delimited label using the active admin locale.
+ */
+export function useLocalizedText(
+	text: unknown,
+	options: LocalizeTextOptions | string = DEFAULT_SEPARATOR,
+): string {
+	const locale = useAdminLocale();
+
+	return React.useMemo(() => {
+		const opts: LocalizeTextOptions =
+			typeof options === "string" ? { separator: options } : options;
+		return String(localizeString(text, locale, opts) ?? "");
+	}, [text, locale, options]);
+}
+
+/**
+ * Component that renders localized text for the active admin locale.
+ */
+export function LocalizedText({
+	children,
+	separator = DEFAULT_SEPARATOR,
+	dictionary,
+	translationKey,
+}: {
+	children: string;
+	separator?: string;
+	dictionary?: Record<string, Record<string, string>>;
+	translationKey?: string;
+}) {
+	const localized = useLocalizedText(children, {
+		separator,
+		dictionary,
+		key: translationKey,
+	});
+	return <>{localized}</>;
+}
+
+// Auto-reload watcher on admin UI locale change
+if (
+	typeof window !== "undefined" &&
+	typeof window.MutationObserver !== "undefined" &&
+	!(window as any).__emdash_i18n_lang_watcher__
+) {
+	(window as any).__emdash_i18n_lang_watcher__ = true;
+	let currentLang = document.documentElement.getAttribute("lang") || "";
+	const observer = new MutationObserver(() => {
+		const newLang = document.documentElement.getAttribute("lang") || "";
+		if (newLang && currentLang && newLang !== currentLang) {
+			currentLang = newLang;
+			setTimeout(() => {
+				window.location.reload();
+			}, 60);
+		}
+	});
+	observer.observe(document.documentElement, {
+		attributes: true,
+		attributeFilter: ["lang"],
+	});
+}
+

package/src/index.d.mts

@@ -0,0 +1,73 @@
+import type { PluginDescriptor } from "emdash";
+
+export interface SchemaI18nOptions {
+	separator?: string;
+	defaultLocale?: string;
+	dictionary?: Record<string, Record<string, string>>;
+	autoReloadOnLocaleChange?: boolean;
+}
+
+export type CustomLocalizationOptions = SchemaI18nOptions;
+
+export declare const RELOAD_WATCHER_SCRIPT: string;
+
+export declare function schemaLocalization(
+	options?: SchemaI18nOptions,
+): PluginDescriptor;
+
+export declare const customLocalization: typeof schemaLocalization;
+export declare const schemaI18n: typeof schemaLocalization;
+
+export declare function createPlugin(
+	options?: SchemaI18nOptions,
+): PluginDescriptor;
+
+export declare function createLocalizationMiddleware(
+	options?: SchemaI18nOptions,
+): (context: any, next: () => Promise<Response>) => Promise<Response>;
+
+export declare function resolveAdminLocale(
+	request: Request,
+	defaultLocale?: string,
+): string;
+
+export declare function normalizeLocale(code: string): string;
+
+export declare function localizeString(
+	value: unknown,
+	locale: string,
+	options?: {
+		key?: string;
+		dictionary?: Record<string, Record<string, string>>;
+		separator?: string;
+	},
+): unknown;
+
+export declare function localizeManifest<T = any>(
+	manifest: T,
+	locale: string,
+	options?: {
+		dictionary?: Record<string, Record<string, string>>;
+		separator?: string;
+	},
+): T;
+
+export declare function localizeBlockTypesResponse<T = any>(
+	data: T,
+	locale: string,
+	options?: {
+		dictionary?: Record<string, Record<string, string>>;
+		separator?: string;
+	},
+): T;
+
+export declare function localizeCollectionsResponse<T = any>(
+	data: T,
+	locale: string,
+	options?: {
+		dictionary?: Record<string, Record<string, string>>;
+		separator?: string;
+	},
+): T;
+
+export default schemaLocalization;

package/src/index.mjs

@@ -0,0 +1,66 @@
+import { definePlugin } from "emdash";
+import { createLocalizationMiddleware, RELOAD_WATCHER_SCRIPT } from "./middleware.mjs";
+import {
+	localizeManifest,
+	localizeBlockTypesResponse,
+	localizeCollectionsResponse,
+	localizeString,
+	resolveAdminLocale,
+} from "./localizer.mjs";
+
+const pluginId = "schema-i18n";
+const pluginName = "Schema & Blocks i18n";
+const version = "1.1.1";
+const description = "Dynamic schema, collections, and block types localization for EmDash CMS Admin UI";
+const author = "Serhii Parshyn";
+const packageEntrypoint = "emdash-schema-i18n";
+const adminEntrypoint = "emdash-schema-i18n/admin";
+
+/**
+ * Native plugin descriptor factory for EmDash.
+ *
+ * @param {object} [options]
+ * @returns {import("emdash").PluginDescriptor}
+ */
+export function schemaLocalization(options = {}) {
+	return {
+		id: pluginId,
+		name: pluginName,
+		version,
+		description,
+		author,
+		format: "native",
+		capabilities: [],
+		entrypoint: packageEntrypoint,
+		adminEntry: adminEntrypoint,
+		options,
+	};
+}
+
+// Backwards-compatibility and alternative aliases
+export const customLocalization = schemaLocalization;
+export const schemaI18n = schemaLocalization;
+
+export function createPlugin(options = {}) {
+	return definePlugin({
+		id: pluginId,
+		name: pluginName,
+		version,
+		capabilities: [],
+		admin: {
+			entry: adminEntrypoint,
+		},
+	});
+}
+
+export {
+	createLocalizationMiddleware,
+	RELOAD_WATCHER_SCRIPT,
+	localizeManifest,
+	localizeBlockTypesResponse,
+	localizeCollectionsResponse,
+	localizeString,
+	resolveAdminLocale,
+};
+
+export default schemaLocalization;

package/src/localizer.d.mts

@@ -0,0 +1,36 @@
+export interface LocalizeOptions {
+	key?: string;
+	dictionary?: Record<string, Record<string, string>>;
+	separator?: string;
+}
+
+export declare function normalizeLocale(code: string): string;
+
+export declare function resolveAdminLocale(
+	request: Request,
+	defaultLocale?: string,
+): string;
+
+export declare function localizeString(
+	value: unknown,
+	locale: string,
+	options?: LocalizeOptions,
+): unknown;
+
+export declare function localizeManifest<T = any>(
+	manifest: T,
+	locale: string,
+	options?: LocalizeOptions,
+): T;
+
+export declare function localizeBlockTypesResponse<T = any>(
+	data: T,
+	locale: string,
+	options?: LocalizeOptions,
+): T;
+
+export declare function localizeCollectionsResponse<T = any>(
+	data: T,
+	locale: string,
+	options?: LocalizeOptions,
+): T;

package/src/localizer.mjs

@@ -0,0 +1,450 @@
+/**
+ * String and Manifest localization engine for EmDash.
+ */
+
+const DEFAULT_SEPARATOR = " / ";
+
+/**
+ * Resolves the admin UI locale from an incoming HTTP Request.
+ *
+ * Precedence:
+ * 1. Query parameter `locale`
+ * 2. Cookie `emdash-locale` (standard EmDash admin locale cookie)
+ * 3. Header `Accept-Language`
+ * 4. Fallback default (`en`)
+ *
+ * @param {Request} request
+ * @param {string} [defaultLocale="en"]
+ * @returns {string}
+ */
+export function resolveAdminLocale(request, defaultLocale = "en") {
+	if (!request) return defaultLocale;
+
+	try {
+		const url = new URL(request.url);
+		const queryLocale = url.searchParams.get("locale")?.trim();
+		if (queryLocale) return normalizeLocale(queryLocale);
+	} catch {
+		// Ignore invalid URLs
+	}
+
+	const cookieHeader = request.headers.get("cookie") || "";
+	const cookieMatch = cookieHeader.match(/(?:^|;\s*)emdash-locale=([^;]+)/);
+	if (cookieMatch?.[1]) {
+		return normalizeLocale(decodeURIComponent(cookieMatch[1].trim()));
+	}
+
+	const acceptLanguage = request.headers.get("accept-language");
+	if (acceptLanguage) {
+		const firstLang = acceptLanguage.split(",")[0]?.split(";")[0]?.trim();
+		if (firstLang) return normalizeLocale(firstLang);
+	}
+
+	return defaultLocale;
+}
+
+/**
+ * Normalizes locale code to base language (e.g. "uk-UA" -> "uk", "en-US" -> "en").
+ *
+ * @param {string} code
+ * @returns {string}
+ */
+export function normalizeLocale(code) {
+	if (!code) return "en";
+	return code.toLowerCase().split("-")[0] || code.toLowerCase();
+}
+
+/**
+ * Localizes a single string or object value.
+ *
+ * Supported formats:
+ * 1. Delimited string: `"Українська / English"`
+ * 2. Multi-language object: `{ uk: "Українська", en: "English" }`
+ * 3. Explicit dictionary override: `options.dictionary[locale][key]`
+ *
+ * @param {unknown} value
+ * @param {string} locale
+ * @param {object} [options]
+ * @param {string} [options.key]
+ * @param {Record<string, Record<string, string>>} [options.dictionary]
+ * @param {string} [options.separator=" / "]
+ * @returns {unknown}
+ */
+export function localizeString(value, locale, options = {}) {
+	const currentLocale = normalizeLocale(locale);
+	const { key, dictionary, separator = DEFAULT_SEPARATOR } = options;
+
+	// 1. Check explicit dictionary by key (e.g. "collections.case_study.label")
+	if (key && dictionary?.[currentLocale]?.[key]) {
+		return dictionary[currentLocale][key];
+	}
+
+	// 2. Check dictionary by string value (e.g. "Case studies" -> "Кейси")
+	if (typeof value === "string" && dictionary?.[currentLocale]?.[value]) {
+		return dictionary[currentLocale][value];
+	}
+
+	// 2. Object with language keys: { uk: "...", en: "..." }
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const obj = /** @type {Record<string, any>} */ (value);
+		if (obj[currentLocale] !== undefined) return obj[currentLocale];
+		if (obj.en !== undefined) return obj.en;
+		if (obj.uk !== undefined) return obj.uk;
+		return value;
+	}
+
+	if (typeof value !== "string") return value;
+
+	// 3. Delimited string: "Українська / English"
+	if (value.includes(separator)) {
+		const parts = value.split(separator);
+		if (parts.length === 2) {
+			const [uk, en] = parts;
+			return currentLocale.startsWith("uk") ? uk.trim() : en.trim();
+		}
+		// If more than 2 parts, uk is 0, en is 1, etc.
+		if (currentLocale.startsWith("uk")) return parts[0].trim();
+		if (parts.length > 1) return parts[1].trim();
+	}
+
+	return value;
+}
+
+/**
+ * Recursively localizes EmDash Manifest collections, fields, and block types.
+ *
+ * @param {any} manifest
+ * @param {string} locale
+ * @param {object} [options]
+ * @param {Record<string, Record<string, string>>} [options.dictionary]
+ * @param {string} [options.separator=" / "]
+ * @returns {any}
+ */
+export function localizeManifest(manifest, locale, options = {}) {
+	if (!manifest || typeof manifest !== "object") return manifest;
+
+	// Handle wrapped API envelope: { success: true, data: { collections: ... } }
+	if (manifest.data && typeof manifest.data === "object" && !Array.isArray(manifest.data)) {
+		return {
+			...manifest,
+			data: localizeManifest(manifest.data, locale, options),
+		};
+	}
+
+	// Shallow clone top-level
+	const localized = { ...manifest };
+
+	// 1. Localize Collections
+	if (localized.collections && typeof localized.collections === "object") {
+		const newCollections = {};
+		for (const [colSlug, colDef] of Object.entries(localized.collections)) {
+			if (!colDef || typeof colDef !== "object") {
+				newCollections[colSlug] = colDef;
+				continue;
+			}
+
+			const col = { ...colDef };
+			col.label = localizeString(col.label, locale, {
+				key: `collections.${colSlug}.label`,
+				...options,
+			});
+			if (col.labelSingular) {
+				col.labelSingular = localizeString(col.labelSingular, locale, {
+					key: `collections.${colSlug}.labelSingular`,
+					...options,
+				});
+			}
+			if (col.description) {
+				col.description = localizeString(col.description, locale, {
+					key: `collections.${colSlug}.description`,
+					...options,
+				});
+			}
+
+			// Localize collection fields
+			if (col.fields && typeof col.fields === "object" && !Array.isArray(col.fields)) {
+				const newFields = {};
+				for (const [fSlug, fieldDef] of Object.entries(col.fields)) {
+					if (!fieldDef || typeof fieldDef !== "object") {
+						newFields[fSlug] = fieldDef;
+						continue;
+					}
+					newFields[fSlug] = localizeSingleField(fieldDef, `collections.${colSlug}`, locale, options);
+				}
+				col.fields = newFields;
+			} else if (Array.isArray(col.fields)) {
+				col.fields = col.fields.map((fld) => localizeSingleField(fld, `collections.${colSlug}`, locale, options));
+			}
+
+			newCollections[colSlug] = col;
+		}
+		localized.collections = newCollections;
+	}
+
+	// 2. Localize Block Types
+	if (Array.isArray(localized.blockTypes)) {
+		localized.blockTypes = localized.blockTypes.map((bt) => localizeSingleBlockType(bt, locale, options));
+	}
+
+	// 3. Localize Menus
+	if (Array.isArray(localized.menus)) {
+		localized.menus = localized.menus.map((menu) => {
+			if (!menu || typeof menu !== "object") return menu;
+			const m = { ...menu };
+			m.name = localizeString(m.name, locale, {
+				key: `menus.${m.slug || m.id}.name`,
+				...options,
+			});
+			return m;
+		});
+	}
+
+	return localized;
+}
+
+/**
+ * Localizes block types list / response (GET /_emdash/api/schema/block-types).
+ *
+ * @param {any} data
+ * @param {string} locale
+ * @param {object} [options]
+ * @returns {any}
+ */
+export function localizeBlockTypesResponse(data, locale, options = {}) {
+	if (!data || typeof data !== "object") return data;
+
+	if (data.data && typeof data.data === "object" && !Array.isArray(data.data)) {
+		return {
+			...data,
+			data: localizeBlockTypesResponse(data.data, locale, options),
+		};
+	}
+
+	if (Array.isArray(data.items)) {
+		return {
+			...data,
+			items: data.items.map((bt) => localizeSingleBlockType(bt, locale, options)),
+		};
+	}
+
+	if (Array.isArray(data)) {
+		return data.map((bt) => localizeSingleBlockType(bt, locale, options));
+	}
+
+	return data;
+}
+
+function localizeSingleBlockType(bt, locale, options = {}) {
+	if (!bt || typeof bt !== "object") return bt;
+	const block = { ...bt };
+	const btSlug = block.slug || block.type || block.name || "unknown";
+
+	block.label = localizeString(block.label, locale, {
+		key: `blockTypes.${btSlug}.label`,
+		...options,
+	});
+	if (block.description) {
+		block.description = localizeString(block.description, locale, {
+			key: `blockTypes.${btSlug}.description`,
+			...options,
+		});
+	}
+	if (block.category) {
+		block.category = localizeString(block.category, locale, {
+			key: `blockTypes.${btSlug}.category`,
+			...options,
+		});
+	}
+
+	if (Array.isArray(block.fields)) {
+		block.fields = block.fields.map((fld) => localizeSingleField(fld, `blockTypes.${btSlug}`, locale, options));
+	}
+
+	if (Array.isArray(block.versions)) {
+		block.versions = block.versions.map((ver) => {
+			if (!ver || !Array.isArray(ver.fields)) return ver;
+			return {
+				...ver,
+				fields: ver.fields.map((fld) => localizeSingleField(fld, `blockTypes.${btSlug}`, locale, options)),
+			};
+		});
+	}
+
+	return block;
+}
+
+function localizeSingleField(fld, parentKey, locale, options = {}) {
+	if (!fld || typeof fld !== "object") return fld;
+	const field = { ...fld };
+	const fSlug = field.slug || "unknown";
+
+	if (field.label) {
+		field.label = localizeString(field.label, locale, {
+			key: `${parentKey}.fields.${fSlug}.label`,
+			...options,
+		});
+	}
+	if (field.labelSingular) {
+		field.labelSingular = localizeString(field.labelSingular, locale, {
+			key: `${parentKey}.fields.${fSlug}.labelSingular`,
+			...options,
+		});
+	}
+	if (field.description) {
+		field.description = localizeString(field.description, locale, {
+			key: `${parentKey}.fields.${fSlug}.description`,
+			...options,
+		});
+	}
+	if (field.placeholder) {
+		field.placeholder = localizeString(field.placeholder, locale, {
+			key: `${parentKey}.fields.${fSlug}.placeholder`,
+			...options,
+		});
+	}
+	if (field.hint) {
+		field.hint = localizeString(field.hint, locale, {
+			key: `${parentKey}.fields.${fSlug}.hint`,
+			...options,
+		});
+	}
+
+	// Options for select / multiSelect
+	if (Array.isArray(field.options)) {
+		field.options = field.options.map((opt, idx) => {
+			if (typeof opt === "string") {
+				return localizeString(opt, locale, {
+					key: `${parentKey}.fields.${fSlug}.options.${idx}`,
+					...options,
+				});
+			}
+			if (opt && typeof opt === "object") {
+				return {
+					...opt,
+					label: opt.label
+						? localizeString(opt.label, locale, {
+								key: `${parentKey}.fields.${fSlug}.options.${opt.value || idx}.label`,
+								...options,
+						  })
+						: opt.label,
+				};
+			}
+			return opt;
+		});
+	}
+
+	if (field.validation && Array.isArray(field.validation.options)) {
+		field.validation = {
+			...field.validation,
+			options: field.validation.options.map((opt, idx) => {
+				if (typeof opt === "string") {
+					return localizeString(opt, locale, {
+						key: `${parentKey}.fields.${fSlug}.options.${idx}`,
+						...options,
+					});
+				}
+				if (opt && typeof opt === "object" && opt.label) {
+					return {
+						...opt,
+						label: localizeString(opt.label, locale, {
+							key: `${parentKey}.fields.${fSlug}.options.${opt.value || idx}.label`,
+							...options,
+						}),
+					};
+				}
+				return opt;
+			}),
+		};
+	}
+
+	// Subfields (repeaters, groups)
+	if (Array.isArray(field.fields)) {
+		field.fields = field.fields.map((sub) => localizeSingleField(sub, `${parentKey}.fields.${fSlug}`, locale, options));
+	}
+	if (field.validation && Array.isArray(field.validation.subFields)) {
+		field.validation = {
+			...field.validation,
+			subFields: field.validation.subFields.map((sub) =>
+				localizeSingleField(sub, `${parentKey}.fields.${fSlug}`, locale, options),
+			),
+		};
+	}
+
+	// Block types inside blocks fields (e.g. case_study.fields.blocks.blockTypes)
+	if (Array.isArray(field.blockTypes)) {
+		field.blockTypes = field.blockTypes.map((bt) => localizeSingleBlockType(bt, locale, options));
+	}
+
+	return field;
+}
+
+/**
+ * Localizes collections list / response (GET /_emdash/api/schema/collections).
+ *
+ * @param {any} data
+ * @param {string} locale
+ * @param {object} [options]
+ * @returns {any}
+ */
+export function localizeCollectionsResponse(data, locale, options = {}) {
+	if (!data || typeof data !== "object") return data;
+
+	if (data.data && typeof data.data === "object" && !Array.isArray(data.data)) {
+		return {
+			...data,
+			data: localizeCollectionsResponse(data.data, locale, options),
+		};
+	}
+
+	if (Array.isArray(data.items)) {
+		return {
+			...data,
+			items: data.items.map((col) => localizeSingleCollection(col, locale, options)),
+		};
+	}
+
+	if (Array.isArray(data)) {
+		return data.map((col) => localizeSingleCollection(col, locale, options));
+	}
+
+	if (data.slug && data.label) {
+		return localizeSingleCollection(data, locale, options);
+	}
+
+	return data;
+}
+
+function localizeSingleCollection(col, locale, options = {}) {
+	if (!col || typeof col !== "object") return col;
+	const c = { ...col };
+	const cSlug = c.slug || "unknown";
+
+	c.label = localizeString(c.label, locale, {
+		key: `collections.${cSlug}.label`,
+		...options,
+	});
+	if (c.labelSingular) {
+		c.labelSingular = localizeString(c.labelSingular, locale, {
+			key: `collections.${cSlug}.labelSingular`,
+			...options,
+		});
+	}
+	if (c.description) {
+		c.description = localizeString(c.description, locale, {
+			key: `collections.${cSlug}.description`,
+			...options,
+		});
+	}
+
+	if (c.fields && typeof c.fields === "object" && !Array.isArray(c.fields)) {
+		const newFields = {};
+		for (const [fSlug, fDef] of Object.entries(c.fields)) {
+			newFields[fSlug] = localizeSingleField(fDef, `collections.${cSlug}`, locale, options);
+		}
+		c.fields = newFields;
+	} else if (Array.isArray(c.fields)) {
+		c.fields = c.fields.map((fld) => localizeSingleField(fld, `collections.${cSlug}`, locale, options));
+	}
+
+	return c;
+}

package/src/middleware.mjs

@@ -0,0 +1,109 @@
+import {
+	resolveAdminLocale,
+	localizeManifest,
+	localizeBlockTypesResponse,
+	localizeCollectionsResponse,
+} from "./localizer.mjs";
+
+export const RELOAD_WATCHER_SCRIPT = `<script id="emdash-i18n-watcher">
+(() => {
+	if (typeof window === "undefined" || !window.MutationObserver || window.__emdash_i18n_lang_watcher__) return;
+	window.__emdash_i18n_lang_watcher__ = true;
+	let currentLang = document.documentElement.getAttribute("lang") || "";
+	const observer = new MutationObserver(() => {
+		const newLang = document.documentElement.getAttribute("lang") || "";
+		if (newLang && currentLang && newLang !== currentLang) {
+			currentLang = newLang;
+			setTimeout(() => { window.location.reload(); }, 60);
+		}
+	});
+	observer.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] });
+})();
+</script>`;
+
+/**
+ * Creates an Astro middleware handler that intercepts `/_emdash/api/manifest`,
+ * `/_emdash/api/schema/block-types`, and `/_emdash/api/schema/collections`
+ * and dynamically localizes the schema JSON according to the admin session language,
+ * and injects an auto-reload watcher on admin HTML pages so switching languages
+ * immediately refreshes schema and block types.
+ *
+ * @param {object} [options]
+ * @param {Record<string, Record<string, string>>} [options.dictionary]
+ * @param {string} [options.separator=" / "]
+ * @param {string} [options.defaultLocale="en"]
+ * @param {boolean} [options.autoReloadOnLocaleChange=true]
+ * @returns {(context: any, next: () => Promise<Response>) => Promise<Response>}
+ */
+export function createLocalizationMiddleware(options = {}) {
+	const { defaultLocale = "en", autoReloadOnLocaleChange = true } = options;
+
+	return async function localizationMiddleware(context, next) {
+		const response = await next();
+
+		if (response?.status >= 200 && response?.status < 300) {
+			const pathname = context.url.pathname;
+			const isManifest = pathname === "/_emdash/api/manifest";
+			const isBlockTypes = pathname === "/_emdash/api/schema/block-types";
+			const isCollections = pathname.startsWith("/_emdash/api/schema/collections");
+
+			if (isManifest || isBlockTypes || isCollections) {
+				try {
+					const locale = resolveAdminLocale(context.request, defaultLocale);
+					const data = await response.clone().json();
+					let localized = data;
+
+					if (isManifest) {
+						localized = localizeManifest(data, locale, options);
+					} else if (isBlockTypes) {
+						localized = localizeBlockTypesResponse(data, locale, options);
+					} else if (isCollections) {
+						localized = localizeCollectionsResponse(data, locale, options);
+					}
+
+					const headers = new Headers(response.headers);
+					headers.set("Content-Type", "application/json; charset=utf-8");
+					headers.set("Vary", "Cookie, Accept-Language");
+
+					return new Response(JSON.stringify(localized), {
+						status: response.status,
+						statusText: response.statusText,
+						headers,
+					});
+				} catch (err) {
+					console.error("[emdash-schema-i18n] Failed to localize schema response:", err);
+					return response;
+				}
+			}
+
+			if (
+				autoReloadOnLocaleChange &&
+				pathname.startsWith("/_emdash/admin") &&
+				response.headers.get("content-type")?.includes("text/html")
+			) {
+				try {
+					const resClone = response.clone();
+					const html = await resClone.text();
+					if (!html.includes('id="emdash-i18n-watcher"')) {
+						const injectedHtml = html.includes("</body>")
+							? html.replace("</body>", `${RELOAD_WATCHER_SCRIPT}</body>`)
+							: `${html}${RELOAD_WATCHER_SCRIPT}`;
+						const headers = new Headers(response.headers);
+						headers.delete("content-length");
+						return new Response(injectedHtml, {
+							status: response.status,
+							statusText: response.statusText,
+							headers,
+						});
+					}
+				} catch (err) {
+					console.error("[emdash-schema-i18n] Failed to inject auto-reload watcher:", err);
+				}
+			}
+		}
+
+		return response;
+	};
+}
+
+export default createLocalizationMiddleware;