@carlonicora/nextjs-jsonapi 5.0.2 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",
@@ -89,13 +89,14 @@
       "import": "./dist/next-config/index.mjs",
       "require": "./dist/next-config/index.js"
     },
-    "./pwa/*": "./pwa/*"
+    "./pwa/*": "./pwa/*",
+    "./messages/*": "./messages/*"
   },
   "scripts": {
     "build": "rm -rf dist && NODE_OPTIONS='--max-old-space-size=8192' tsup && tsc -p scripts/generate-web-module/tsconfig.json",
     "dev": "node scripts/dev-watch.mjs",
     "clean": "rm -rf dist",
-    "lint": "eslint \"src/**/*.ts\" \"src/**/*.tsx\" --fix && node scripts/check-rtl-classes.mjs",
+    "lint": "eslint \"src/**/*.ts\" \"src/**/*.tsx\" --fix && node scripts/check-rtl-classes.mjs && node scripts/validate-messages.mjs",
     "format": "prettier --write \"src/**/*.ts\"",
     "prepublishOnly": "pnpm build",
     "prepare": "tsc -p scripts/generate-web-module/tsconfig.json",
@@ -110,6 +111,7 @@
     "src",
     "scripts",
     "pwa",
+    "messages",
     "README.md"
   ],
   "peerDependencies": {

package/pwa/offline.template.html

@@ -5,10 +5,11 @@
   build assets, no external script, stylesheet or font, because the build's
   chunks are not available offline and change on every deploy.
 
-  This is a template. Each app copies it to public/offline.html and fills the
-  placeholders by hand: the app name, the theme blocks (one root block of the
-  six tokens, then one class block per non-light theme), the default-locale
-  strings, and the config object read by the script below.
+  Filled by hand from @carlonicora/nextjs-jsonapi pwa/offline.template.html:
+  the app name, the theme blocks (one root block of the six tokens, then one
+  class block per non-light theme), the default-locale strings, and the config
+  object read by the script below. After any edit, set offlineRevision in
+  public/sw-config.js to the first 8 hex characters of this file's sha256.
 -->
 <html lang="en">
   <head>

package/scripts/package-surface.spec.ts

@@ -0,0 +1,15 @@
+import { createRequire } from "node:module";
+import { describe, expect, it } from "vitest";
+import pkg from "../package.json";
+
+describe("package surface", () => {
+  it("ships and exports messages and pwa", () => {
+    expect(pkg.files).toEqual(expect.arrayContaining(["messages", "pwa"]));
+    expect((pkg.exports as Record<string, unknown>)["./messages/*"]).toBe("./messages/*");
+    expect(pkg.scripts.lint).toContain("node scripts/validate-messages.mjs");
+  });
+  it("messages resolve through the self-reference", () => {
+    const require = createRequire(import.meta.url);
+    expect(require.resolve("@carlonicora/nextjs-jsonapi/messages/en.json")).toMatch(/messages\/en\.json$/);
+  });
+});

package/scripts/validate-messages.mjs

@@ -0,0 +1,412 @@
+// Lint-time guard: every text the library renders has an English and an
+// Italian value in messages/, no leaf is dead, and no value names an app.
+// Resolver copied from neural-erp's apps/web/scripts/validate-translations.mjs.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Patterns to match translation usage
+const USE_TRANSLATIONS_PATTERN = /useTranslations\(\s*["']([^"']*)["']\s*\)/g;
+const USE_TRANSLATIONS_NO_NS_PATTERN = /useTranslations\(\s*\)/g;
+const T_CALL_PATTERN = /\bt\(\s*["']([^"']+)["']/g;
+const T_TEMPLATE_CALL_PATTERN = /\bt\(\s*`([^`]+)`/g;
+const GET_TRANSLATIONS_PATTERN = /getTranslations\(\s*["']([^"']*)["']\s*\)/g;
+
+// A dotted string literal anywhere in src: a key reached through a constant
+// (`labelKey: "entities.companies"`, i18n-keys.ts, OPERATION_LABEL_NAMESPACE).
+const LITERAL_PATTERN = /["'`]([a-z0-9_]+(?:\.[a-z0-9_]+)+)["'`]/g;
+
+// Keys the library renders but whose text is the app's by nature (owner
+// decision 3: the library holds no information about the application). They
+// must NOT be in messages/*.json; every app provides them, with no fallback.
+export const APP_PROVIDED_KEYS = [
+  /^common\.title$/, // the app's own name
+  /^common\.description$/, // the app's own tagline
+  /^auth\.login_description$/, // the app's product pitch on the login page
+  /^auth\.register_description$/, // the app's product pitch on the register page
+  /^features\.assistant\.composer_placeholder$/, // names what the app's assistant knows about
+  /^features\.assistant\.starters\./, // example questions about the app's own domain
+  /^features\.assistant\.empty_state\.subtitle$/, // says what the app's assistant knows about
+  /^auth\.gdpr\.marketing_consent$/, // a consent must name who sends the news: the app
+  // The app's own entities (CommonDeleter / RecentPagesNavigator render
+  // `entities.${type}` for any module). Only the library's own entities ship.
+  /^entities\.(?!(?:assistants|companies|howtos|rbac|roles|users)(?:\.|$))/,
+  // Token-usage operation types an app backend defines (operation-label.ts: the
+  // app supplies this vocabulary, unknown types render raw). Only the types the
+  // backend library emits, plus its customer/platform scopes, ship.
+  /^token_usage\.types\.(?!(?:analyser|communitySummariser|counterpartIdentificator|customer|embedding|ethicist|graphCreator|imageAnalysis|imageGeneration|operator|platform|responder|strategy|summariser|textGeneration|transcription)$)/,
+];
+
+// Values the app-word rule would flag although the word is the library's own
+// meaning, not an app's domain. Each entry carries its reason.
+const APP_WORD_EXEMPT_KEYS = new Map([
+  ["analytics.admin.dimensions.campaign", "the utm_campaign dimension of web analytics"],
+  ["help.modes.how-to", 'Italian "pratiche" = practical (how-to guides), not a case file'],
+  ["howto.howToType.how-to", 'Italian "pratica" = practical (how-to guide), not a case file'],
+]);
+
+// Template keys whose ids an app backend defines at runtime: there is nothing
+// in the library to enumerate, so they are not checked against messages/.
+export const DYNAMIC_KEY_ALLOWLIST = [
+  // Notification.tsx: notificationType comes from the app's API; each app owns its types.
+  "notification.${notification.notificationType}.title",
+  // Notification.tsx: the action button of an app-defined notification type.
+  "notification.${notification.notificationType}.buttons.action",
+];
+
+// No value may name an app or use an app's domain word (owner decision 3).
+const APP_WORDS = [
+  /wyrdli/i,
+  /phlow/i,
+  /adhstudy/i,
+  /neural[- ]erp/i,
+  /a360ai/i,
+  /avvocato360/i,
+  /360studioai/i,
+  /only35/i,
+  /dreamer/i,
+  /\bcampaigns?\b/i,
+  /\bcampagn[ae]\b/i,
+  /\bscenes?\b/i,
+  /\bscen[ae]\b/i,
+  /\bnpcs?\b/i,
+  /\bpratich?[ae]\b/i,
+];
+
+const isAppProvided = (key) => APP_PROVIDED_KEYS.some((p) => p.test(key));
+
+/**
+ * Recursively get all keys from a nested object
+ */
+function getAllKeys(obj, prefix = "") {
+  const keys = new Set();
+
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const nestedKeys = getAllKeys(value, fullKey);
+      nestedKeys.forEach((k) => keys.add(k));
+    } else {
+      keys.add(fullKey);
+    }
+  }
+
+  return keys;
+}
+
+export function leafKeys(tree, prefix = "") {
+  return getAllKeys(tree, prefix);
+}
+
+/**
+ * Escape a string for literal use inside a RegExp
+ */
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Turn a template-literal key (`a.${x}.label`) into a RegExp matching full leaf keys.
+ * Returns null when the template cannot be parsed reliably (nested template literals).
+ */
+export function dynamicKeyToRegExp(template) {
+  const parts = [];
+  let index = 0;
+  while (index < template.length) {
+    const start = template.indexOf("${", index);
+    if (start === -1) {
+      parts.push(escapeRegExp(template.slice(index)));
+      break;
+    }
+    parts.push(escapeRegExp(template.slice(index, start)));
+    let depth = 1;
+    let cursor = start + 2;
+    while (cursor < template.length && depth > 0) {
+      if (template[cursor] === "{") depth++;
+      else if (template[cursor] === "}") depth--;
+      cursor++;
+    }
+    if (depth !== 0) return null;
+    parts.push("[^.]+");
+    index = cursor;
+  }
+  return new RegExp(`^${parts.join("")}$`);
+}
+
+/**
+ * Extract translation keys from a single file
+ */
+function extractKeysFromFile(filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const usages = [];
+
+  // Find all useTranslations calls with namespaces in this file
+  const namespaces = [];
+
+  // Match useTranslations("namespace")
+  let match;
+  const contentForNamespace = content;
+
+  // Reset regex
+  USE_TRANSLATIONS_PATTERN.lastIndex = 0;
+  while ((match = USE_TRANSLATIONS_PATTERN.exec(contentForNamespace)) !== null) {
+    const lineNumber = content.substring(0, match.index).split("\n").length;
+    namespaces.push({ namespace: match[1], line: lineNumber });
+  }
+
+  // Match useTranslations() without namespace
+  USE_TRANSLATIONS_NO_NS_PATTERN.lastIndex = 0;
+  while ((match = USE_TRANSLATIONS_NO_NS_PATTERN.exec(contentForNamespace)) !== null) {
+    const lineNumber = content.substring(0, match.index).split("\n").length;
+    namespaces.push({ namespace: "", line: lineNumber });
+  }
+
+  // Match getTranslations("namespace") for server components
+  GET_TRANSLATIONS_PATTERN.lastIndex = 0;
+  while ((match = GET_TRANSLATIONS_PATTERN.exec(contentForNamespace)) !== null) {
+    const lineNumber = content.substring(0, match.index).split("\n").length;
+    namespaces.push({ namespace: match[1], line: lineNumber });
+  }
+
+  // If no useTranslations found but t() is used, assume no namespace
+  if (namespaces.length === 0) {
+    namespaces.push({ namespace: "", line: 0 });
+  }
+
+  const activeNamespaceAt = (lineNumber) => {
+    let activeNamespace = "";
+    for (const ns of namespaces) {
+      if (ns.line <= lineNumber) {
+        activeNamespace = ns.namespace;
+      }
+    }
+    return activeNamespace;
+  };
+
+  const addUsage = (key, index, dynamic) => {
+    const lineNumber = content.substring(0, index).split("\n").length;
+    const activeNamespace = activeNamespaceAt(lineNumber);
+    usages.push({
+      key: activeNamespace ? `${activeNamespace}.${key}` : key,
+      file: filePath,
+      line: lineNumber,
+      dynamic,
+    });
+  };
+
+  // Find all t("key") / t('key') calls
+  T_CALL_PATTERN.lastIndex = 0;
+  while ((match = T_CALL_PATTERN.exec(content)) !== null) {
+    // Plain-quoted strings cannot interpolate; a "{" means this is not a key
+    if (match[1].includes("{")) continue;
+    addUsage(match[1], match.index, false);
+  }
+
+  // Find all t(`key`) and t(`prefix.${expr}.suffix`) calls
+  T_TEMPLATE_CALL_PATTERN.lastIndex = 0;
+  while ((match = T_TEMPLATE_CALL_PATTERN.exec(content)) !== null) {
+    const key = match[1];
+    const dynamic = key.includes("${");
+    if (!dynamic && key.includes("{")) continue;
+    // A key that is nothing but an interpolation carries no static information
+    if (dynamic && /^\$\{[^]*\}$/.test(key) && dynamicKeyToRegExp(key)?.source === "^[^.]+$") continue;
+    addUsage(key, match.index, dynamic);
+  }
+
+  return usages;
+}
+
+/**
+ * Recursively find all TypeScript/JavaScript files
+ */
+function findSourceFiles(dir, files = []) {
+  if (!fs.existsSync(dir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (
+        entry.name === "node_modules" ||
+        entry.name === ".next" ||
+        entry.name === "coverage" ||
+        entry.name === "__tests__" ||
+        entry.name === "tests"
+      ) {
+        continue;
+      }
+      findSourceFiles(fullPath, files);
+    } else if (
+      entry.isFile() &&
+      (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) &&
+      !entry.name.endsWith(".test.ts") &&
+      !entry.name.endsWith(".test.tsx") &&
+      !entry.name.endsWith(".spec.ts") &&
+      !entry.name.endsWith(".spec.tsx") &&
+      !entry.name.endsWith(".d.ts")
+    ) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+export function collectUsages(sourceRoot) {
+  return findSourceFiles(sourceRoot).flatMap((file) => extractKeysFromFile(file));
+}
+
+/**
+ * Dotted literals in one file's source. Comment lines (`//`, `/*`, ` *`) are
+ * skipped: prose there quotes config paths and keys that are not usages.
+ */
+export function literalsIn(content) {
+  const literals = new Set();
+  for (const line of content.split("\n")) {
+    if (/^\s*(\/\/|\/\*|\*)/.test(line)) continue;
+    for (const m of line.matchAll(LITERAL_PATTERN)) literals.add(m[1]);
+  }
+  return literals;
+}
+
+export function collectLiterals(sourceRoot) {
+  const literals = new Set();
+  for (const file of findSourceFiles(sourceRoot)) {
+    for (const literal of literalsIn(fs.readFileSync(file, "utf-8"))) literals.add(literal);
+  }
+  return literals;
+}
+
+function valueAt(tree, key) {
+  let node = tree;
+  for (const part of key.split(".")) {
+    if (node === null || typeof node !== "object") return undefined;
+    node = node[part];
+  }
+  return node;
+}
+
+function dottedPrefixes(key) {
+  const parts = key.split(".");
+  return parts.map((_, i) => parts.slice(0, i + 1).join("."));
+}
+
+export function validate({ en, it, usages, literals }) {
+  const findings = [];
+  const enKeys = leafKeys(en);
+  const itKeys = leafKeys(it);
+  const where = (u) => `${u.file}:${u.line}`;
+
+  const patterns = [];
+  for (const usage of usages) {
+    if (isAppProvided(usage.key)) continue;
+    if (!usage.dynamic) {
+      if (!enKeys.has(usage.key)) findings.push({ rule: "missing", key: usage.key, detail: where(usage) });
+      continue;
+    }
+    if (DYNAMIC_KEY_ALLOWLIST.includes(usage.key)) continue;
+    const pattern = dynamicKeyToRegExp(usage.key);
+    if (!pattern) continue;
+    patterns.push(pattern);
+    if (![...enKeys].some((k) => pattern.test(k))) {
+      findings.push({ rule: "dynamic-unmatched", key: usage.key, detail: where(usage) });
+    }
+  }
+
+  // A dotted string literal anchored in a library namespace (its first segment is
+  // a top-level key of en.json) is a key the code reaches without t(): the
+  // i18n-keys.ts contracts, labelKey props, OPERATION_LABEL_NAMESPACE. It must
+  // resolve to a leaf or to a prefix of leaves, or the app renders the key path.
+  const namespaces = new Set(Object.keys(en));
+  for (const literal of literals) {
+    if (!namespaces.has(literal.split(".")[0])) continue;
+    if (isAppProvided(literal) || isAppProvided(`${literal}.`)) continue;
+    const resolves = enKeys.has(literal) || [...enKeys].some((k) => k.startsWith(`${literal}.`));
+    if (!resolves) findings.push({ rule: "missing", key: literal, detail: "string literal anchored in a library namespace resolves to no text" });
+  }
+
+  for (const key of enKeys) {
+    if (!itKeys.has(key)) findings.push({ rule: "parity", key, detail: "in en.json, not in it.json" });
+  }
+  for (const key of itKeys) {
+    if (!enKeys.has(key)) findings.push({ rule: "parity", key, detail: "in it.json, not in en.json" });
+  }
+
+  const staticKeys = new Set(usages.filter((u) => !u.dynamic).map((u) => u.key));
+  for (const key of enKeys) {
+    if (isAppProvided(key)) {
+      findings.push({ rule: "app-word", key, detail: "app-provided key must not ship in the library" });
+      continue;
+    }
+    const used =
+      staticKeys.has(key) || patterns.some((p) => p.test(key)) || dottedPrefixes(key).some((p) => literals.has(p));
+    if (!used) findings.push({ rule: "unused", key, detail: "no t() call or literal reaches it" });
+  }
+
+  for (const [locale, tree, keys] of [
+    ["en", en, enKeys],
+    ["it", it, itKeys],
+  ]) {
+    for (const key of keys) {
+      if (APP_WORD_EXEMPT_KEYS.has(key)) continue;
+      const value = valueAt(tree, key);
+      const word = APP_WORDS.find((w) => typeof value === "string" && w.test(value));
+      if (word) findings.push({ rule: "app-word", key, detail: `${locale}: "${value}" matches ${word}` });
+    }
+  }
+
+  for (const key of enKeys) {
+    if (!itKeys.has(key)) continue;
+    const value = valueAt(en, key);
+    if (value === valueAt(it, key)) findings.push({ rule: "identical", key, detail: JSON.stringify(value) });
+  }
+
+  return findings;
+}
+
+// `process.argv[1]` is not symlink-resolved by node while `import.meta.url` is,
+// so compare real paths — otherwise the CLI silently does nothing.
+function isDirectInvocation() {
+  try {
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) {
+  const root = path.join(fileURLToPath(new URL(".", import.meta.url)), "..");
+  const src = path.join(root, "src");
+  const read = (name) => JSON.parse(fs.readFileSync(path.join(root, "messages", name), "utf-8"));
+  const en = read("en.json");
+  const findings = validate({ en, it: read("it.json"), usages: collectUsages(src), literals: collectLiterals(src) });
+
+  const byRule = new Map();
+  for (const f of findings) byRule.set(f.rule, [...(byRule.get(f.rule) ?? []), f]);
+
+  const identical = byRule.get("identical") ?? [];
+  if (identical.length) {
+    console.log(`identical en/it values (report only, ${identical.length}):`);
+    for (const f of identical) console.log(`  ${f.key}  ${f.detail}`);
+    console.log("");
+  }
+
+  let failures = 0;
+  for (const [rule, list] of byRule) {
+    if (rule === "identical") continue;
+    failures += list.length;
+    console.error(`${rule} (${list.length}):`);
+    for (const f of list) console.error(`  ${f.key}  ${f.detail}`);
+    console.error("");
+  }
+  if (failures) {
+    console.error(`validate-messages: ${failures} problem(s)`);
+    process.exit(1);
+  }
+  console.log(`validate-messages: clean (${leafKeys(en).size} keys)`);
+}

package/scripts/validate-messages.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { leafKeys, validate, APP_PROVIDED_KEYS, literalsIn } from "./validate-messages.mjs";
+
+const en = { auth: { buttons: { login: "Log in" } }, oauth: { ui: { scopes: { read: { name: "Read" } } } }, dead: { key: "x" } };
+const itTree = { auth: { buttons: { login: "Accedi" } }, oauth: { ui: { scopes: { read: { name: "Lettura" } } } }, dead: { key: "x" } };
+const usage = (key: string, dynamic = false) => ({ key, file: "f.tsx", line: 1, dynamic });
+
+describe("validate-messages", () => {
+  it("leafKeys flattens nested paths", () => {
+    expect([...leafKeys(en)].sort()).toEqual(["auth.buttons.login", "dead.key", "oauth.ui.scopes.read.name"]);
+  });
+  it("reports a static key with no text", () => {
+    const f = validate({ en, it: itTree, usages: [usage("auth.buttons.register")], literals: new Set() });
+    expect(f).toContainEqual(expect.objectContaining({ rule: "missing", key: "auth.buttons.register" }));
+  });
+  it("matches a dynamic key by pattern and reports one that matches nothing", () => {
+    const ok = validate({ en, it: itTree, usages: [usage("oauth.ui.scopes.${id}.name", true)], literals: new Set(["dead.key"]) });
+    expect(ok.filter((x) => x.rule === "dynamic-unmatched")).toHaveLength(0);
+    const bad = validate({ en, it: itTree, usages: [usage("oauth.ui.scopes.${id}.label", true)], literals: new Set(["dead.key"]) });
+    expect(bad).toContainEqual(expect.objectContaining({ rule: "dynamic-unmatched" }));
+  });
+  it("reports en/it parity both ways", () => {
+    const f = validate({ en, it: { auth: { buttons: { login: "Accedi", extra: "x" } } }, usages: [], literals: new Set() });
+    expect(f.filter((x) => x.rule === "parity").map((x) => x.key).sort()).toEqual(["auth.buttons.extra", "dead.key", "oauth.ui.scopes.read.name"]);
+  });
+  it("counts a leaf as used through t(), a literal, or a dotted prefix literal; otherwise unused", () => {
+    const f = validate({ en, it: itTree, usages: [usage("auth.buttons.login")], literals: new Set(["oauth.ui.scopes"]) });
+    expect(f.filter((x) => x.rule === "unused").map((x) => x.key)).toEqual(["dead.key"]);
+  });
+  it("requires a namespace-anchored literal to resolve; ignores literals outside the namespaces", () => {
+    const f = validate({
+      en,
+      it: itTree,
+      usages: [usage("auth.buttons.login"), usage("dead.key"), usage("oauth.ui.scopes.read.name")],
+      literals: new Set(["auth.buttons.register", "auth.buttons", "next.config", "common.title"]),
+    });
+    expect(f.filter((x) => x.rule === "missing").map((x) => x.key)).toEqual(["auth.buttons.register"]);
+  });
+  it("collects dotted literals from code lines only, never from comment lines", () => {
+    const src = `// a consumer with no \`handbook.path\`\n/* "x.y.z" */\n * "p.q"\nconst k = "billing.admin.title"; t(\`a.b\`);\n`;
+    expect([...literalsIn(src)].sort()).toEqual(["a.b", "billing.admin.title"]);
+  });
+  it("fails on an app name in any value, case-insensitive", () => {
+    const f = validate({ en: { a: "Welcome to Wyrdli" }, it: { a: "Benvenuto in wyrdli" }, usages: [usage("a")], literals: new Set() });
+    expect(f.filter((x) => x.rule === "app-word")).toHaveLength(2);
+  });
+  it("exempts app-provided keys from missing and parity, and never lists them as unused", () => {
+    expect(APP_PROVIDED_KEYS.some((p) => p.test("common.title"))).toBe(true);
+    const f = validate({ en, it: itTree, usages: [usage("common.title")], literals: new Set() });
+    expect(f.filter((x) => x.key === "common.title")).toHaveLength(0);
+  });
+  it("reports an identical en/it value without failing", () => {
+    const f = validate({ en, it: itTree, usages: [usage("auth.buttons.login"), usage("dead.key"), usage("oauth.ui.scopes.read.name")], literals: new Set() });
+    expect(f).toContainEqual(expect.objectContaining({ rule: "identical", key: "dead.key" }));
+  });
+});

package/src/core/utils/__tests__/mergeMessages.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { mergeMessages, type MessageTree } from "../mergeMessages";
+
+describe("mergeMessages", () => {
+  const base: MessageTree = { auth: { buttons: { login: "Log in", register: "Register" } }, onlyBase: { x: "b" } };
+  const override: MessageTree = { auth: { buttons: { login: "Sign in" }, extra: "e" }, onlyOverride: { y: "o" } };
+
+  it("override leaf wins, base-only and override-only paths survive", () => {
+    const merged = mergeMessages(base, override);
+    expect(merged).toEqual({
+      auth: { buttons: { login: "Sign in", register: "Register" }, extra: "e" },
+      onlyBase: { x: "b" },
+      onlyOverride: { y: "o" },
+    });
+  });
+  it("merges three levels deep", () => {
+    expect(mergeMessages({ a: { b: { c: "1", d: "2" } } }, { a: { b: { c: "9" } } })).toEqual({
+      a: { b: { c: "9", d: "2" } },
+    });
+  });
+  it("replaces when one side is a string and the other a tree", () => {
+    expect(mergeMessages({ a: "s" }, { a: { b: "t" } })).toEqual({ a: { b: "t" } });
+    expect(mergeMessages({ a: { b: "t" } }, { a: "s" })).toEqual({ a: "s" });
+  });
+  it("inputs untouched, result is a new object", () => {
+    const b = { a: { x: "1" } };
+    const o = { a: { y: "2" } };
+    const merged = mergeMessages(b, o);
+    expect(b).toEqual({ a: { x: "1" } });
+    expect(o).toEqual({ a: { y: "2" } });
+    expect(merged).not.toBe(b);
+    expect(merged.a).not.toBe(b.a);
+  });
+  it("empty override returns a deep copy of the base", () => {
+    const merged = mergeMessages(base, {});
+    expect(merged).toEqual(base);
+    expect(merged).not.toBe(base);
+  });
+});

package/src/core/utils/index.ts

@@ -1,2 +1,3 @@
 export * from "./translateResponse";
 export * from "./rehydrate";
+export * from "./mergeMessages";

package/src/core/utils/mergeMessages.ts

@@ -0,0 +1,29 @@
+/**
+ * A next-intl message file: nested objects whose leaves are strings.
+ */
+export type MessageTree = { [key: string]: string | MessageTree };
+
+function isMessageTree(value: unknown): value is MessageTree {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Deep-merges two message trees. At every path the override's leaf wins; a path
+ * only in the base stays; a path only in the override is added. A non-object
+ * value replaces, never merges. Neither input is mutated; the result is a new
+ * object at every level.
+ */
+export function mergeMessages(base: MessageTree, override: MessageTree): MessageTree {
+  const merged: MessageTree = {};
+
+  for (const [key, value] of Object.entries(base)) {
+    merged[key] = isMessageTree(value) ? mergeMessages(value, {}) : value;
+  }
+
+  for (const [key, value] of Object.entries(override)) {
+    const current = merged[key];
+    merged[key] = isMessageTree(value) ? mergeMessages(isMessageTree(current) ? current : {}, value) : value;
+  }
+
+  return merged;
+}