@peax/consent-banner-locales 0.7.0 → 0.8.0

package/README.md

@@ -31,6 +31,23 @@ The default export is the complete map. Named root imports support normal ESM tr
 
 Supported codes: `bg`, `cs`, `da`, `de`, `el`, `en`, `es`, `et`, `fi`, `fr`, `ga`, `hr`, `hu`, `it`, `lt`, `lv`, `mt`, `nl`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sv`. Portuguese uses European wording.
 
+## Your own copy over a language
+
+Keep only the lines you change, for example in a `locales.json`, and lay them over the dictionaries you import. Every field you leave out stays the dictionary's, so the banner never falls back to English mid-sentence:
+
+```tsx
+import { de, fr, mergeWithDefaultLocales } from '@peax/consent-banner-locales'
+import copy from './locales.json' // { "de": { "banner": { "title": "Kekse" } } }
+
+const locales = mergeWithDefaultLocales({ de, fr }, copy)
+
+<Banner locale="de" locales={locales} />
+```
+
+Merge once, as above, or memoize the call: every merge returns a new map, and the banner resolves its copy again whenever `locales` is a new object.
+
+The merge is field by field: an omitted, `null`, or `undefined` field keeps the dictionary's line, and an empty string is kept (`text: ''` hides a section description). Sections your copy adds, such as `custom-1`, are kept. Tags match as the banner matches them, trimmed and case-insensitive. Copy for a regional tag without its own dictionary, such as `de-AT`, is laid over its base language (`de`). Copy for a language you pass no dictionary for is kept as it is and falls back to English. A namespace or section that is not an object, such as `"banner": "Kekse"`, changes nothing. Every dictionary you pass is kept, one whose copy changes no line is returned as it is, and neither input is changed. Import only the languages you use: the helper adds no dictionaries of its own.
+
 ## Copy and fallback
 
 Banner fields: `title`, `collapsedText`, `acceptAllLabel`, `rejectAllLabel`, `customizePreferencesLabel`, `preferencesTitle`, `closePreferencesLabel`, `applyPreferencesLabel`, and `cookiePolicyLabel`. Optional `preferencesText` has no bundled default. `collapsedText` includes a `<cookiePolicy>` placeholder; the application supplies its URL through `cookiePolicyUrl`.
@@ -43,7 +60,7 @@ The shared resolver matches exact tags, then their base language, ignoring case
 
 | Entry | Exports |
 | --- | --- |
-| `@peax/consent-banner-locales` | Default complete map and named `en`, `de`, `fr`, etc. |
+| `@peax/consent-banner-locales` | Default complete map, named `en`, `de`, `fr`, etc., and `mergeWithDefaultLocales` |
 | `@peax/consent-banner-locales/<code>` | Named composite dictionary, e.g. `de` |
 
 Replace `dePreferences` with `de.preferences` and old banner fields with `de.banner`. Parser/types now live in `@peax/consent-banner-shared`. The old package-bound resolvers are removed; shared `resolveLocaleContent` accepts the application's map. Pass dictionaries explicitly to Banner after upgrading.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+declare type BannerLocales = Readonly<Record<string, LocaleContent | undefined>>;
+
 declare type BannerMessages = Readonly<{
     title: string;
     collapsedText: string;
@@ -42,6 +44,11 @@ export declare const hu: LocaleMessages;
 declare const it_2: LocaleMessages;
 export { it_2 as it }
 
+declare type LocaleContent = Readonly<{
+    banner?: Partial<BannerMessages>;
+    preferences?: PreferencesLocaleContent;
+}>;
+
 /** Complete copy shipped by a built-in language entry. */
 declare type LocaleMessages = Readonly<{
     banner: BannerMessages;
@@ -156,12 +163,38 @@ export declare const lt: LocaleMessages;
 
 export declare const lv: LocaleMessages;
 
+/**
+ * Lays an application's copy over dictionaries it imports, field by field, so the banner gets
+ * a complete dictionary for every language that has one and the application keeps only the
+ * lines it changed. A field the copy omits, or sets to `null` or `undefined`, is the
+ * dictionary's; an empty string is kept. Sections the copy adds are kept as they are.
+ *
+ * Tags are matched as the banner matches them: trimmed and case-insensitive. Copy for a tag
+ * with no dictionary of its own, such as `de-AT`, is laid over its base language's (`de`); copy
+ * for a language with no dictionary at all is kept as it is and falls back to English in the
+ * banner. Every dictionary passed in is kept, written over or not, and one whose copy changes
+ * no line is returned as it is. The inputs are not changed.
+ *
+ * ```ts
+ * import { de, fr, mergeWithDefaultLocales } from '@peax/consent-banner-locales'
+ *
+ * const locales = mergeWithDefaultLocales({ de, fr }, { de: { banner: { title: 'Kekse' } } })
+ * ```
+ */
+export declare const mergeWithDefaultLocales: (defaults?: BannerLocales | null, copies?: BannerLocales | null) => BannerLocales;
+
 export declare const mt: LocaleMessages;
 
 export declare const nl: LocaleMessages;
 
 export declare const pl: LocaleMessages;
 
+/** Application copy can translate custom sections and omit any field. */
+declare type PreferencesLocaleContent = Readonly<Record<string, Readonly<{
+    title?: string;
+    text?: string;
+}> | undefined>>;
+
 declare type PreferencesMessages = Readonly<Record<BuiltInPreferencesSectionId, Readonly<{
     title: string;
     text: string;

package/dist/index.js

@@ -23,8 +23,36 @@ import { ru as x } from "./ru.js";
 import { sk as S } from "./sk.js";
 import { sl as C } from "./sl.js";
 import { sv as w } from "./sv.js";
-//#region src/index.ts
-var T = {
+//#region src/merge.ts
+var T = (e, t) => e && Object.hasOwn(e, t) ? e[t] : void 0, E = (e) => Object.fromEntries(Object.entries(e && typeof e == "object" && !Array.isArray(e) ? e : {}).filter(([, e]) => e != null)), D = (e, t) => {
+	let n = /* @__PURE__ */ new Set([...Object.keys(E(e)), ...Object.keys(E(t))]);
+	return Object.fromEntries([...n].map((n) => [n, {
+		...E(T(e, n)),
+		...E(T(t, n))
+	}]));
+}, O = (e, t) => ({
+	banner: {
+		...E(e?.banner),
+		...E(t.banner)
+	},
+	preferences: D(e?.preferences, t.preferences)
+}), k = (e) => Object.keys(E(e.banner)).length > 0 || Object.values(E(e.preferences)).some((e) => Object.keys(E(e)).length > 0), A = (e) => e.trim().toLowerCase(), j = (e) => e.replace(/-.*/s, ""), M = (e, t) => {
+	let n = /* @__PURE__ */ new Map();
+	for (let [t, r] of Object.entries(e ?? {})) r && n.set(A(t), {
+		key: t,
+		base: r
+	});
+	for (let [e, r] of Object.entries(t ?? {})) {
+		if (!r) continue;
+		let t = A(e), i = n.get(t);
+		i ? i.copy = r : n.set(t, {
+			key: e,
+			base: n.get(j(t))?.base,
+			copy: r
+		});
+	}
+	return Object.fromEntries([...n.values()].map(({ key: e, base: t, copy: n }) => [e, n && (!t || k(n)) ? O(t, n) : t]));
+}, N = {
 	bg: e,
 	cs: t,
 	da: n,
@@ -52,4 +80,4 @@ var T = {
 	sv: w
 };
 //#endregion
-export { e as bg, t as cs, n as da, r as de, T as default, i as el, a as en, o as es, s as et, c as fi, l as fr, u as ga, d as hr, f as hu, p as it, m as lt, h as lv, g as mt, _ as nl, v as pl, y as pt, b as ro, x as ru, S as sk, C as sl, w as sv };
+export { e as bg, t as cs, n as da, r as de, N as default, i as el, a as en, o as es, s as et, c as fi, l as fr, u as ga, d as hr, f as hu, p as it, m as lt, h as lv, M as mergeWithDefaultLocales, g as mt, _ as nl, v as pl, y as pt, b as ro, x as ru, S as sk, C as sl, w as sv };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@peax/consent-banner-locales",
   "description": "Optional framework-independent translation dictionaries for Peax Consent banners.",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "homepage": "https://github.com/peaxco/consent",
   "repository": {
@@ -164,7 +164,7 @@
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.59.3",
-    "@peax/consent-banner-shared": "^0.7.0",
+    "@peax/consent-banner-shared": "^0.8.0",
     "@types/node": "^26.6.4",
     "typescript": "5.9.3",
     "vite": "^8.3.2",