@olenbetong/appframe-core 2.13.1 → 2.14.0

package/es/getLocalizedString.d.ts

@@ -1,7 +1,69 @@
+/**
+ * Localized strings come from two places on a page:
+ *
+ * - `af.article.i18n`: the strings the article's project uses, rendered by the framework
+ *   into every page of that article. A string missing there is harvested by posting it to
+ *   `/api/user/localize/new/<article>`, which registers it as used by the article and
+ *   returns the translation.
+ * - `af.i18n[<project>]`: the strings of another project, for code that runs on every
+ *   page without belonging to any one article - the site chrome bundle, the shared
+ *   component packages. Such a project is a name, not an article; the harvest endpoint
+ *   accepts any name, so `localize/new/<project>` registers the string under that project.
+ *
+ * Keeping a project's strings apart from the article's matters when a word means
+ * different things: "Articles" is "Artikler" in the chrome and "Varer" in an accounting
+ * app, which the framework's project-specific base strings express only if the two are
+ * looked up in different dictionaries.
+ *
+ * A project's dictionary is in play only when something put it there: the template
+ * rendered it (`@Render("ChromeStrings", Project: "...")`), or the caller fetched it and
+ * assigned `af.i18n[project]` itself (an empty object counts). On a page that did neither -
+ * a legacy template - the project falls back to the article's dictionary and the article's
+ * harvesting, so the page behaves as it always did instead of posting every string of a
+ * grid on every load. The project fills up from the pages that render it.
+ */
+export type LocalizeOptions = {
+    /**
+     * The globalization project the string belongs to. Defaults to the article, whose
+     * strings the framework renders into `af.article.i18n`. Falls back to the article when
+     * the page carries no dictionary for the project (see the module comment).
+     */
+    project?: string;
+    /** Resolve with the translation once it has been fetched, instead of the base text at once. */
+    wait?: boolean;
+};
 export declare function getLocalizedStringAsync(string: undefined | null): undefined | null;
-export declare function getLocalizedStringAsync(string: string): Promise<string>;
+export declare function getLocalizedStringAsync(string: string, options?: Omit<LocalizeOptions, "wait">): Promise<string>;
 export declare function getLocalizedString(string: undefined | null): undefined | null;
 export declare function getLocalizedString(string: string): string;
 export declare function getLocalizedString(string: string, wait: false): string;
 export declare function getLocalizedString(string: string, wait: true): Promise<string>;
 export declare function getLocalizedString(string: undefined | null, wait: true): undefined | null;
+export declare function getLocalizedString(string: string, options: LocalizeOptions & {
+    wait: true;
+}): Promise<string>;
+export declare function getLocalizedString(string: string, options: LocalizeOptions): string;
+export declare function getLocalizedString(string: undefined | null, options: LocalizeOptions): undefined | null;
+/**
+ * `getLocalizedString` and `localize` bound to a globalization project, for code that is
+ * not part of the article it runs on: the site chrome, the shared component packages.
+ *
+ * On a page whose template renders the project (`af.i18n[project]` exists) the strings are
+ * looked up and harvested there; on any other page they resolve through the article's
+ * dictionary as a plain `getLocalizedString` would.
+ *
+ * @example
+ * ```ts
+ * const { getLocalizedString: t } = createLocalizer("synergi-chrome");
+ * t("Applications");
+ * ```
+ */
+export declare function createLocalizer(project: string): {
+    project: string;
+    getLocalizedString: {
+        (string: undefined | null): undefined | null;
+        (string: string): string;
+        (string: string, wait: true): Promise<string>;
+    };
+    localize: (stringParts: TemplateStringsArray, ...args: unknown[]) => string;
+};

package/es/getLocalizedString.js

@@ -1,6 +1,30 @@
-async function fetchLocalizedString(text) {
+/**
+ * Localized strings come from two places on a page:
+ *
+ * - `af.article.i18n`: the strings the article's project uses, rendered by the framework
+ *   into every page of that article. A string missing there is harvested by posting it to
+ *   `/api/user/localize/new/<article>`, which registers it as used by the article and
+ *   returns the translation.
+ * - `af.i18n[<project>]`: the strings of another project, for code that runs on every
+ *   page without belonging to any one article - the site chrome bundle, the shared
+ *   component packages. Such a project is a name, not an article; the harvest endpoint
+ *   accepts any name, so `localize/new/<project>` registers the string under that project.
+ *
+ * Keeping a project's strings apart from the article's matters when a word means
+ * different things: "Articles" is "Artikler" in the chrome and "Varer" in an accounting
+ * app, which the framework's project-specific base strings express only if the two are
+ * looked up in different dictionaries.
+ *
+ * A project's dictionary is in play only when something put it there: the template
+ * rendered it (`@Render("ChromeStrings", Project: "...")`), or the caller fetched it and
+ * assigned `af.i18n[project]` itself (an empty object counts). On a page that did neither -
+ * a legacy template - the project falls back to the article's dictionary and the article's
+ * harvesting, so the page behaves as it always did instead of posting every string of a
+ * grid on every load. The project fills up from the pages that render it.
+ */
+async function fetchLocalizedString(text, project) {
     try {
-        let response = await fetch(`/api/user/localize/new/${af.article.id}`, {
+        let response = await fetch(`/api/user/localize/new/${encodeURIComponent(project)}`, {
             body: JSON.stringify({ text }),
             headers: {
                 Accept: "application/json; */*",
@@ -16,32 +40,79 @@ async function fetchLocalizedString(text) {
     catch { }
     return text;
 }
-export function getLocalizedStringAsync(string) {
+/**
+ * The dictionary a string is resolved in: the project's when the page carries one,
+ * otherwise the article's; nothing when the page has no `af` at all.
+ */
+function sourceFor(project) {
+    let af = globalThis.af;
+    if (!af)
+        return undefined;
+    if (project) {
+        let dictionary = af.i18n?.[project];
+        if (dictionary)
+            return { dictionary, harvestAs: project };
+    }
+    let article = af.article;
+    if (!article?.i18n)
+        return undefined;
+    return { dictionary: article.i18n, harvestAs: article.id };
+}
+export function getLocalizedStringAsync(string, options) {
     if (!string)
         return string;
-    return getLocalizedString(string, true);
+    return getLocalizedString(string, { ...options, wait: true });
 }
-export function getLocalizedString(string, wait) {
+export function getLocalizedString(string, waitOrOptions) {
     if (typeof string === "string" && string.trim().length === 0) {
         return string;
     }
     if (string === undefined || string === "" || string === null) {
         return;
     }
-    if (globalThis.af?.article?.i18n !== undefined) {
-        if (!Object.hasOwn(af.article.i18n, string)) {
-            af.article.i18n[string] = string;
-            let promise = fetchLocalizedString(string).then((text) => {
-                af.article.i18n[string] = text;
-                return text;
-            });
-            if (wait) {
-                return promise;
-            }
+    let { project, wait } = typeof waitOrOptions === "object" ? waitOrOptions : { wait: waitOrOptions };
+    let source = sourceFor(project);
+    if (source === undefined) {
+        return string;
+    }
+    let { dictionary, harvestAs } = source;
+    if (!Object.hasOwn(dictionary, string)) {
+        dictionary[string] = string;
+        let promise = fetchLocalizedString(string, harvestAs).then((text) => {
+            dictionary[string] = text;
+            return text;
+        });
+        if (wait) {
+            return promise;
         }
-        return af.article.i18n[string];
     }
-    else {
-        return string;
+    return dictionary[string];
+}
+/**
+ * `getLocalizedString` and `localize` bound to a globalization project, for code that is
+ * not part of the article it runs on: the site chrome, the shared component packages.
+ *
+ * On a page whose template renders the project (`af.i18n[project]` exists) the strings are
+ * looked up and harvested there; on any other page they resolve through the article's
+ * dictionary as a plain `getLocalizedString` would.
+ *
+ * @example
+ * ```ts
+ * const { getLocalizedString: t } = createLocalizer("synergi-chrome");
+ * t("Applications");
+ * ```
+ */
+export function createLocalizer(project) {
+    function bound(string, wait) {
+        return getLocalizedString(string, { project, wait });
+    }
+    function localize(stringParts, ...args) {
+        let stringToLocalize = stringParts.map((s, i) => (i === stringParts.length - 1 ? s : `${s}$${i}`)).join("");
+        let localized = bound(stringToLocalize);
+        args.forEach((arg, index) => {
+            localized = localized.replace(`$${index}`, String(arg));
+        });
+        return localized;
     }
+    return { project, getLocalizedString: bound, localize };
 }

package/es/getLocalizedString.test.d.ts

@@ -0,0 +1 @@
+export {};

package/es/getLocalizedString.test.js

@@ -0,0 +1,66 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { createLocalizer, getLocalizedString } from "./getLocalizedString.js";
+function fetchAnswering(translations) {
+    return vi.fn(async (_url, init) => {
+        let { text } = JSON.parse(init.body);
+        return { ok: true, json: async () => translations[text] ?? text };
+    });
+}
+function harvestedProjects(fetchMock) {
+    return fetchMock.mock.calls.map(([url]) => url.replace("/api/user/localize/new/", ""));
+}
+describe("getLocalizedString", () => {
+    let af;
+    let fetchMock;
+    beforeEach(() => {
+        af = { article: { id: "my-article", i18n: { Save: "Lagre" } } };
+        globalThis.af = af;
+        fetchMock = fetchAnswering({ Cancel: "Avbryt", Articles: "Artikler" });
+        vi.stubGlobal("fetch", fetchMock);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        delete globalThis.af;
+    });
+    test("resolves in the article's dictionary and harvests under the article", async () => {
+        expect(getLocalizedString("Save")).toBe("Lagre");
+        expect(getLocalizedString("Cancel")).toBe("Cancel");
+        await vi.waitFor(() => expect(af.article.i18n.Cancel).toBe("Avbryt"));
+        expect(harvestedProjects(fetchMock)).toEqual(["my-article"]);
+    });
+    test("uses the project's dictionary when the page rendered it", async () => {
+        af.i18n = { "synergi-chrome": { Articles: "Artikler" } };
+        af.article.i18n.Articles = "Varer";
+        expect(getLocalizedString("Articles", { project: "synergi-chrome" })).toBe("Artikler");
+        expect(getLocalizedString("Articles")).toBe("Varer");
+        expect(await getLocalizedString("Cancel", { project: "synergi-chrome", wait: true })).toBe("Avbryt");
+        expect(af.i18n["synergi-chrome"].Cancel).toBe("Avbryt");
+        expect(af.article.i18n.Cancel).toBeUndefined();
+        expect(harvestedProjects(fetchMock)).toEqual(["synergi-chrome"]);
+    });
+    test("an empty rendered dictionary still means the project is in play", async () => {
+        af.i18n = { "appframe-ds": {} };
+        expect(await getLocalizedString("Cancel", { project: "appframe-ds", wait: true })).toBe("Avbryt");
+        expect(harvestedProjects(fetchMock)).toEqual(["appframe-ds"]);
+    });
+    test("falls back to the article when the page carries no dictionary for the project", async () => {
+        expect(getLocalizedString("Save", { project: "appframe-ds" })).toBe("Lagre");
+        expect(await getLocalizedString("Cancel", { project: "appframe-ds", wait: true })).toBe("Avbryt");
+        expect(af.i18n).toBeUndefined();
+        expect(af.article.i18n.Cancel).toBe("Avbryt");
+        expect(harvestedProjects(fetchMock)).toEqual(["my-article"]);
+    });
+    test("returns the base text when nothing is on the page", () => {
+        delete globalThis.af;
+        expect(getLocalizedString("Save", { project: "appframe-ds" })).toBe("Save");
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    test("createLocalizer binds the project for getLocalizedString and localize", () => {
+        af.i18n = { "synergi-chrome": { Articles: "Artikler", "Hello $0": "Hei $0" } };
+        let { getLocalizedString: t, localize, project } = createLocalizer("synergi-chrome");
+        expect(project).toBe("synergi-chrome");
+        expect(t("Articles")).toBe("Artikler");
+        expect(localize `Hello ${"Ola"}`).toBe("Hei Ola");
+        expect(t(null)).toBeUndefined();
+    });
+});

package/es/index.d.ts

@@ -13,7 +13,7 @@ export type { DownloadItem, DownloadParameters } from "./downloadRequest.js";
 export { downloadRequest } from "./downloadRequest.js";
 export { expose } from "./expose.js";
 export * from "./filter/index.js";
-export { getLocalizedString } from "./getLocalizedString.js";
+export { createLocalizer, getLocalizedString, type LocalizeOptions } from "./getLocalizedString.js";
 export type { getUserImageOptions } from "./getUserImage.js";
 export { getUserImage } from "./getUserImage.js";
 export { invariant } from "./invariant.js";
@@ -43,6 +43,12 @@ export interface AfArticle {
 }
 export interface AfCore {
     article: AfArticle;
+    /**
+     * Strings of globalization projects other than the article's, by project name, for
+     * code that runs on every page without belonging to an article (the site chrome).
+     * Rendered server side or filled by the caller; see `getLocalizedString`'s `project`.
+     */
+    i18n?: Record<string, Record<string, string>>;
     common: {
         getLocalizedString: typeof getLocalizedString;
         expose: typeof expose;

package/es/index.js

@@ -7,7 +7,7 @@ export { downloadBlob } from "./downloadBlob.js";
 export { downloadRequest } from "./downloadRequest.js";
 export { expose } from "./expose.js";
 export * from "./filter/index.js";
-export { getLocalizedString } from "./getLocalizedString.js";
+export { createLocalizer, getLocalizedString } from "./getLocalizedString.js";
 export { getUserImage } from "./getUserImage.js";
 export { invariant } from "./invariant.js";
 export { localize } from "./localize.js";
@@ -19,4 +19,4 @@ export { UserSession };
 export { alert, ConfirmButtons, confirm, openAlertDialog, waitForDialog } from "./alert.js";
 export { getSettings, saveSettings } from "./settings.js";
 // oxlint-disable-next-line no-use-before-define -- this is injected build time
-export const version = "2.13.0";
+export const version = "2.14.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-core",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "Javascript libraries to utilize the Appframe framework",
   "type": "module",
   "sideEffects": [
@@ -40,9 +40,9 @@
     "mitt": "^3.0.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.2",
-    "@types/bun": "^1.3.14",
-    "chalk": "^5.6.2"
+    "@happy-dom/global-registrator": "20.14.5",
+    "@types/bun": "^1.4.2",
+    "chalk": "^6.0.0"
   },
   "peerDependencies": {},
   "optionalDependencies": {},

package/src/getLocalizedString.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { createLocalizer, getLocalizedString } from "./getLocalizedString.js";
+
+type Af = { article: { id: string; i18n: Record<string, string> }; i18n?: Record<string, Record<string, string>> };
+
+function fetchAnswering(translations: Record<string, string>) {
+	return vi.fn(async (_url: string, init: RequestInit) => {
+		let { text } = JSON.parse(init.body as string) as { text: string };
+		return { ok: true, json: async () => translations[text] ?? text };
+	});
+}
+
+function harvestedProjects(fetchMock: ReturnType<typeof fetchAnswering>) {
+	return fetchMock.mock.calls.map(([url]) => (url as string).replace("/api/user/localize/new/", ""));
+}
+
+describe("getLocalizedString", () => {
+	let af: Af;
+	let fetchMock: ReturnType<typeof fetchAnswering>;
+
+	beforeEach(() => {
+		af = { article: { id: "my-article", i18n: { Save: "Lagre" } } };
+		(globalThis as { af?: Af }).af = af;
+		fetchMock = fetchAnswering({ Cancel: "Avbryt", Articles: "Artikler" });
+		vi.stubGlobal("fetch", fetchMock);
+	});
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+		delete (globalThis as { af?: Af }).af;
+	});
+
+	test("resolves in the article's dictionary and harvests under the article", async () => {
+		expect(getLocalizedString("Save")).toBe("Lagre");
+		expect(getLocalizedString("Cancel")).toBe("Cancel");
+		await vi.waitFor(() => expect(af.article.i18n.Cancel).toBe("Avbryt"));
+		expect(harvestedProjects(fetchMock)).toEqual(["my-article"]);
+	});
+
+	test("uses the project's dictionary when the page rendered it", async () => {
+		af.i18n = { "synergi-chrome": { Articles: "Artikler" } };
+		af.article.i18n.Articles = "Varer";
+
+		expect(getLocalizedString("Articles", { project: "synergi-chrome" })).toBe("Artikler");
+		expect(getLocalizedString("Articles")).toBe("Varer");
+
+		expect(await getLocalizedString("Cancel", { project: "synergi-chrome", wait: true })).toBe("Avbryt");
+		expect(af.i18n["synergi-chrome"].Cancel).toBe("Avbryt");
+		expect(af.article.i18n.Cancel).toBeUndefined();
+		expect(harvestedProjects(fetchMock)).toEqual(["synergi-chrome"]);
+	});
+
+	test("an empty rendered dictionary still means the project is in play", async () => {
+		af.i18n = { "appframe-ds": {} };
+
+		expect(await getLocalizedString("Cancel", { project: "appframe-ds", wait: true })).toBe("Avbryt");
+		expect(harvestedProjects(fetchMock)).toEqual(["appframe-ds"]);
+	});
+
+	test("falls back to the article when the page carries no dictionary for the project", async () => {
+		expect(getLocalizedString("Save", { project: "appframe-ds" })).toBe("Lagre");
+		expect(await getLocalizedString("Cancel", { project: "appframe-ds", wait: true })).toBe("Avbryt");
+
+		expect(af.i18n).toBeUndefined();
+		expect(af.article.i18n.Cancel).toBe("Avbryt");
+		expect(harvestedProjects(fetchMock)).toEqual(["my-article"]);
+	});
+
+	test("returns the base text when nothing is on the page", () => {
+		delete (globalThis as { af?: Af }).af;
+		expect(getLocalizedString("Save", { project: "appframe-ds" })).toBe("Save");
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	test("createLocalizer binds the project for getLocalizedString and localize", () => {
+		af.i18n = { "synergi-chrome": { Articles: "Artikler", "Hello $0": "Hei $0" } };
+		let { getLocalizedString: t, localize, project } = createLocalizer("synergi-chrome");
+
+		expect(project).toBe("synergi-chrome");
+		expect(t("Articles")).toBe("Artikler");
+		expect(localize`Hello ${"Ola"}`).toBe("Hei Ola");
+		expect(t(null)).toBeUndefined();
+	});
+});

package/src/getLocalizedString.ts

@@ -1,6 +1,42 @@
-async function fetchLocalizedString(text: string) {
+/**
+ * Localized strings come from two places on a page:
+ *
+ * - `af.article.i18n`: the strings the article's project uses, rendered by the framework
+ *   into every page of that article. A string missing there is harvested by posting it to
+ *   `/api/user/localize/new/<article>`, which registers it as used by the article and
+ *   returns the translation.
+ * - `af.i18n[<project>]`: the strings of another project, for code that runs on every
+ *   page without belonging to any one article - the site chrome bundle, the shared
+ *   component packages. Such a project is a name, not an article; the harvest endpoint
+ *   accepts any name, so `localize/new/<project>` registers the string under that project.
+ *
+ * Keeping a project's strings apart from the article's matters when a word means
+ * different things: "Articles" is "Artikler" in the chrome and "Varer" in an accounting
+ * app, which the framework's project-specific base strings express only if the two are
+ * looked up in different dictionaries.
+ *
+ * A project's dictionary is in play only when something put it there: the template
+ * rendered it (`@Render("ChromeStrings", Project: "...")`), or the caller fetched it and
+ * assigned `af.i18n[project]` itself (an empty object counts). On a page that did neither -
+ * a legacy template - the project falls back to the article's dictionary and the article's
+ * harvesting, so the page behaves as it always did instead of posting every string of a
+ * grid on every load. The project fills up from the pages that render it.
+ */
+
+export type LocalizeOptions = {
+	/**
+	 * The globalization project the string belongs to. Defaults to the article, whose
+	 * strings the framework renders into `af.article.i18n`. Falls back to the article when
+	 * the page carries no dictionary for the project (see the module comment).
+	 */
+	project?: string;
+	/** Resolve with the translation once it has been fetched, instead of the base text at once. */
+	wait?: boolean;
+};
+
+async function fetchLocalizedString(text: string, project: string) {
 	try {
-		let response = await fetch(`/api/user/localize/new/${af.article.id}`, {
+		let response = await fetch(`/api/user/localize/new/${encodeURIComponent(project)}`, {
 			body: JSON.stringify({ text }),
 			headers: {
 				Accept: "application/json; */*",
@@ -17,12 +53,38 @@ async function fetchLocalizedString(text: string) {
 
 	return text;
 }
+
+type Source = {
+	/** Where the string is looked up and the fetched translation is kept for the page. */
+	dictionary: Record<string, string>;
+	/** The name a missing string is harvested under: the project, or the article's id. */
+	harvestAs: string;
+};
+
+/**
+ * The dictionary a string is resolved in: the project's when the page carries one,
+ * otherwise the article's; nothing when the page has no `af` at all.
+ */
+function sourceFor(project: string | undefined): Source | undefined {
+	let af = globalThis.af;
+	if (!af) return undefined;
+
+	if (project) {
+		let dictionary = af.i18n?.[project];
+		if (dictionary) return { dictionary, harvestAs: project };
+	}
+
+	let article = af.article;
+	if (!article?.i18n) return undefined;
+	return { dictionary: article.i18n, harvestAs: article.id };
+}
+
 export function getLocalizedStringAsync(string: undefined | null): undefined | null;
-export function getLocalizedStringAsync(string: string): Promise<string>;
-export function getLocalizedStringAsync(string: string | undefined | null) {
+export function getLocalizedStringAsync(string: string, options?: Omit<LocalizeOptions, "wait">): Promise<string>;
+export function getLocalizedStringAsync(string: string | undefined | null, options?: Omit<LocalizeOptions, "wait">) {
 	if (!string) return string;
 
-	return getLocalizedString(string, true);
+	return getLocalizedString(string, { ...options, wait: true });
 }
 
 export function getLocalizedString(string: undefined | null): undefined | null;
@@ -30,9 +92,12 @@ export function getLocalizedString(string: string): string;
 export function getLocalizedString(string: string, wait: false): string;
 export function getLocalizedString(string: string, wait: true): Promise<string>;
 export function getLocalizedString(string: undefined | null, wait: true): undefined | null;
+export function getLocalizedString(string: string, options: LocalizeOptions & { wait: true }): Promise<string>;
+export function getLocalizedString(string: string, options: LocalizeOptions): string;
+export function getLocalizedString(string: undefined | null, options: LocalizeOptions): undefined | null;
 export function getLocalizedString(
 	string: string | undefined | null,
-	wait?: boolean,
+	waitOrOptions?: boolean | LocalizeOptions,
 ): string | undefined | null | Promise<string> {
 	if (typeof string === "string" && string.trim().length === 0) {
 		return string;
@@ -42,22 +107,61 @@ export function getLocalizedString(
 		return;
 	}
 
-	if (globalThis.af?.article?.i18n !== undefined) {
-		if (!Object.hasOwn(af.article.i18n, string)) {
-			af.article.i18n[string] = string;
+	let { project, wait } = typeof waitOrOptions === "object" ? waitOrOptions : { wait: waitOrOptions };
+	let source = sourceFor(project);
+	if (source === undefined) {
+		return string;
+	}
 
-			let promise = fetchLocalizedString(string).then((text) => {
-				af.article.i18n[string] = text;
-				return text;
-			});
+	let { dictionary, harvestAs } = source;
+	if (!Object.hasOwn(dictionary, string)) {
+		dictionary[string] = string;
 
-			if (wait) {
-				return promise;
-			}
+		let promise = fetchLocalizedString(string, harvestAs).then((text) => {
+			dictionary[string] = text;
+			return text;
+		});
+
+		if (wait) {
+			return promise;
 		}
+	}
 
-		return af.article.i18n[string];
-	} else {
-		return string;
+	return dictionary[string];
+}
+
+/**
+ * `getLocalizedString` and `localize` bound to a globalization project, for code that is
+ * not part of the article it runs on: the site chrome, the shared component packages.
+ *
+ * On a page whose template renders the project (`af.i18n[project]` exists) the strings are
+ * looked up and harvested there; on any other page they resolve through the article's
+ * dictionary as a plain `getLocalizedString` would.
+ *
+ * @example
+ * ```ts
+ * const { getLocalizedString: t } = createLocalizer("synergi-chrome");
+ * t("Applications");
+ * ```
+ */
+export function createLocalizer(project: string) {
+	function bound(string: undefined | null): undefined | null;
+	function bound(string: string): string;
+	function bound(string: string, wait: true): Promise<string>;
+	function bound(string: string | undefined | null, wait?: boolean): string | undefined | null | Promise<string> {
+		return getLocalizedString(string as string, { project, wait } as LocalizeOptions & { wait: true });
 	}
+
+	function localize(stringParts: TemplateStringsArray, ...args: unknown[]): string {
+		let stringToLocalize = stringParts.map((s, i) => (i === stringParts.length - 1 ? s : `${s}$${i}`)).join("");
+		let localized = bound(stringToLocalize);
+
+		args.forEach((arg, index) => {
+			localized = localized.replace(`$${index}`, String(arg));
+		});
+
+		return localized;
+	}
+
+	return { project, getLocalizedString: bound, localize };
 }

package/src/index.ts

@@ -14,7 +14,7 @@ export type { DownloadItem, DownloadParameters } from "./downloadRequest.js";
 export { downloadRequest } from "./downloadRequest.js";
 export { expose } from "./expose.js";
 export * from "./filter/index.js";
-export { getLocalizedString } from "./getLocalizedString.js";
+export { createLocalizer, getLocalizedString, type LocalizeOptions } from "./getLocalizedString.js";
 export type { getUserImageOptions } from "./getUserImage.js";
 export { getUserImage } from "./getUserImage.js";
 export { invariant } from "./invariant.js";
@@ -50,6 +50,12 @@ export interface AfArticle {
 
 export interface AfCore {
 	article: AfArticle;
+	/**
+	 * Strings of globalization projects other than the article's, by project name, for
+	 * code that runs on every page without belonging to an article (the site chrome).
+	 * Rendered server side or filled by the caller; see `getLocalizedString`'s `project`.
+	 */
+	i18n?: Record<string, Record<string, string>>;
 	common: {
 		getLocalizedString: typeof getLocalizedString;
 		expose: typeof expose;