@prosopo/locale 3.2.8 → 3.3.0

package/dist/tests/locale.test-d.js

@@ -0,0 +1,88 @@
+import { assertType, describe, expectTypeOf, it } from "vitest";
+import { LanguageSchema, Languages, TranslationKeysSchema, i18nMiddleware, isClientSide, loadI18next, useTranslation, } from "../index.js";
+describe("Languages", () => {
+    it("is a frozen const map of name to code, not a widened record", () => {
+        expectTypeOf(Languages.english).toEqualTypeOf();
+        expectTypeOf(Languages.chinese).toEqualTypeOf();
+    });
+    it("rejects assignment to a code", () => {
+        Languages.english = "fr";
+    });
+    it("has no member for a language that is not shipped", () => {
+        Languages.klingon;
+    });
+});
+describe("LanguageSchema", () => {
+    it("parses to a string", () => {
+        expectTypeOf(LanguageSchema.parse("en")).toEqualTypeOf();
+    });
+    it("exposes .enum as a lookup of codes", () => {
+        expectTypeOf(LanguageSchema.enum).toExtend();
+    });
+    it("accepts unknown input at the parse boundary", () => {
+        expectTypeOf(LanguageSchema.parse).toBeCallableWith("anything");
+    });
+});
+describe("TranslationKey", () => {
+    it("is inferred from the schema", () => {
+        expectTypeOf().toEqualTypeOf();
+    });
+    it("accepts a key literal, so error call sites need no cast", () => {
+        assertType("API.UNKNOWN");
+    });
+    it("exposes the derived keys as an array of options", () => {
+        expectTypeOf(TranslationKeysSchema.options).toExtend();
+    });
+});
+describe("isClientSide", () => {
+    it("takes no arguments and returns a boolean", () => {
+        expectTypeOf(isClientSide).parameters.toEqualTypeOf();
+        expectTypeOf(isClientSide).returns.toEqualTypeOf();
+    });
+});
+describe("loadI18next", () => {
+    it("requires the backend flag", () => {
+        expectTypeOf(loadI18next).toBeCallableWith(true);
+        expectTypeOf(loadI18next).toBeCallableWith(false, "fr");
+    });
+    it("rejects a call with no arguments", () => {
+        loadI18next();
+    });
+    it("rejects a non-boolean first argument", () => {
+        loadI18next("fr");
+    });
+    it("resolves to the i18next instance type the package re-exports", () => {
+        expectTypeOf(loadI18next).returns.toEqualTypeOf();
+    });
+});
+describe("Ti18n", () => {
+    it("carries the i18next surface consumers need", () => {
+        expectTypeOf().toHaveProperty("t");
+        expectTypeOf().toHaveProperty("language");
+        expectTypeOf().toHaveProperty("changeLanguage");
+    });
+});
+describe("i18nMiddleware", () => {
+    it("takes handler options and resolves to an express handler", () => {
+        expectTypeOf(i18nMiddleware).toBeCallableWith({});
+        expectTypeOf(i18nMiddleware).returns.toExtend();
+    });
+    it("rejects an unknown option", () => {
+        i18nMiddleware({ notAnOption: true });
+    });
+    it("rejects being called with no options", () => {
+        i18nMiddleware();
+    });
+});
+describe("useTranslation", () => {
+    it("is callable with no options", () => {
+        expectTypeOf(useTranslation).toBeCallableWith();
+    });
+    it("returns a t function", () => {
+        expectTypeOf(useTranslation).returns.toHaveProperty("t");
+    });
+    it("rejects an unknown option", () => {
+        useTranslation({ notAnOption: 1 });
+    });
+});
+//# sourceMappingURL=locale.test-d.js.map

package/dist/tests/locale.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.test-d.js","sourceRoot":"","sources":["../../src/tests/locale.test-d.ts"],"names":[],"mappings":"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"}

package/dist/tests/process.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=process.unit.test.d.ts.map

package/dist/tests/process.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.unit.test.d.ts","sourceRoot":"","sources":["../../src/tests/process.unit.test.ts"],"names":[],"mappings":""}

package/dist/tests/process.unit.test.js

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+import { getProcess } from "../process.js";
+describe("getProcess", () => {
+    test("returns the process global when one exists", () => {
+        expect(getProcess()).toBe(process);
+    });
+    test("exposes env, which is the only member consumers use", () => {
+        expect(getProcess()?.env).toBe(process.env);
+    });
+    test("is stable across calls rather than returning a copy", () => {
+        expect(getProcess()).toBe(getProcess());
+    });
+});
+//# sourceMappingURL=process.unit.test.js.map

package/dist/tests/process.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.unit.test.js","sourceRoot":"","sources":["../../src/tests/process.unit.test.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAI3B,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAChE,MAAM,CAAC,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAChE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/tests/translationKey.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=translationKey.unit.test.d.ts.map

package/dist/tests/translationKey.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translationKey.unit.test.d.ts","sourceRoot":"","sources":["../../src/tests/translationKey.unit.test.ts"],"names":[],"mappings":""}

package/dist/tests/translationKey.unit.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "vitest";
+import translationEn from "../locales/en/translation.json" with {
+    type: "json"
+};
+import { TranslationKeysSchema, getLeafFieldPath, } from "../translationKey.js";
+describe("getLeafFieldPath", () => {
+    test("returns no paths for a bare string, which is a leaf and not a container", () => {
+        expect(getLeafFieldPath("a string")).toEqual([]);
+    });
+    test("returns no paths for the empty string", () => {
+        expect(getLeafFieldPath("")).toEqual([]);
+    });
+    test("emits a top-level string value under its own key", () => {
+        expect(getLeafFieldPath({ topLevel: "value" })).toEqual(["topLevel"]);
+    });
+    test("emits section.key for a one-level-deep section", () => {
+        expect(getLeafFieldPath({ section: { key: "value" } })).toEqual([
+            "section.key",
+        ]);
+    });
+    test("emits every key of a section, in insertion order", () => {
+        expect(getLeafFieldPath({ section: { first: "1", second: "2", third: "3" } })).toEqual(["section.first", "section.second", "section.third"]);
+    });
+    test("recurses to arbitrary depth, joining each level with a dot", () => {
+        expect(getLeafFieldPath({ a: { b: { c: { d: "leaf" } } } })).toEqual([
+            "a.b.c.d",
+        ]);
+    });
+    test("handles sibling branches of differing depth", () => {
+        expect(getLeafFieldPath({
+            shallow: { key: "v" },
+            deep: { nested: { key: "v" } },
+        })).toEqual(["shallow.key", "deep.nested.key"]);
+    });
+    test("returns no paths for an empty object", () => {
+        expect(getLeafFieldPath({})).toEqual([]);
+    });
+    test("drops an empty nested section rather than erroring", () => {
+        expect(getLeafFieldPath({ section: {} })).toEqual([]);
+    });
+    test("keeps populated siblings when one section is empty", () => {
+        expect(getLeafFieldPath({ empty: {}, full: { key: "v" } })).toEqual([
+            "full.key",
+        ]);
+    });
+    test("throws on an explicitly undefined value, naming the offending key", () => {
+        const node = {
+            section: { broken: undefined },
+        };
+        expect(() => getLeafFieldPath(node)).toThrow("Undefined value for key broken");
+    });
+    test("throws before emitting any of the sibling keys of the broken one", () => {
+        const node = {
+            section: { ok: "v", broken: undefined },
+        };
+        expect(() => getLeafFieldPath(node)).toThrow(/Undefined value/);
+    });
+    test("does not mutate the input", () => {
+        const node = { section: { key: "value" } };
+        const snapshot = JSON.stringify(node);
+        getLeafFieldPath(node);
+        expect(JSON.stringify(node)).toBe(snapshot);
+    });
+});
+describe("TranslationKeysSchema", () => {
+    const keys = getLeafFieldPath(translationEn);
+    test("is non-empty — an empty z.enum would throw at module load", () => {
+        expect(keys.length).toBeGreaterThan(0);
+    });
+    test("accepts every key derived from the English translation", () => {
+        for (const key of keys) {
+            expect(TranslationKeysSchema.parse(key)).toBe(key);
+        }
+    });
+    test("rejects a key that is not in the English translation", () => {
+        expect(() => TranslationKeysSchema.parse("no.such.key")).toThrow();
+    });
+    test("rejects the empty string", () => {
+        expect(() => TranslationKeysSchema.parse("")).toThrow();
+    });
+    test("rejects a section name on its own — only leaves are valid keys", () => {
+        const [firstKey] = keys;
+        expect(firstKey).toBeDefined();
+        const section = String(firstKey).split(".")[0];
+        expect(() => TranslationKeysSchema.parse(section)).toThrow();
+    });
+    test("rejects non-string input", () => {
+        expect(() => TranslationKeysSchema.parse(42)).toThrow();
+        expect(() => TranslationKeysSchema.parse(null)).toThrow();
+        expect(() => TranslationKeysSchema.parse(undefined)).toThrow();
+    });
+    test("safeParse reports failure without throwing", () => {
+        const result = TranslationKeysSchema.safeParse("no.such.key");
+        expect(result.success).toBe(false);
+    });
+    test("is case sensitive", () => {
+        const [firstKey] = keys;
+        expect(firstKey).toBeDefined();
+        const upper = String(firstKey).toUpperCase();
+        if (upper !== firstKey) {
+            expect(() => TranslationKeysSchema.parse(upper)).toThrow();
+        }
+    });
+    test("exposes exactly the derived keys as enum options", () => {
+        expect(new Set(TranslationKeysSchema.options)).toEqual(new Set(keys));
+    });
+});
+//# sourceMappingURL=translationKey.unit.test.js.map

package/dist/tests/translationKey.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translationKey.unit.test.js","sourceRoot":"","sources":["../../src/tests/translationKey.unit.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/translations.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=translations.unit.test.d.ts.map

package/dist/tests/translations.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translations.unit.test.d.ts","sourceRoot":"","sources":["../../src/tests/translations.unit.test.ts"],"names":[],"mappings":""}

package/dist/tests/translations.unit.test.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { LanguageSchema, Languages } from "../translations.js";
+const codes = Object.values(Languages);
+describe("Languages", () => {
+    test("is non-empty", () => {
+        expect(codes.length).toBeGreaterThan(0);
+    });
+    test("maps English language names to BCP 47 codes", () => {
+        expect(Languages.english).toBe("en");
+        expect(Languages.chinese).toBe("zh-CN");
+        expect(Languages.portugeseBrazil).toBe("pt-BR");
+    });
+    test("includes the fallback language", () => {
+        expect(codes).toContain("en");
+    });
+    test("has no duplicate codes", () => {
+        expect(new Set(codes).size).toBe(codes.length);
+    });
+    test("every code is a well-formed, lowercase-primary language tag", () => {
+        for (const code of codes) {
+            expect(code).toMatch(/^[a-z]{2}(-[A-Z]{2})?$/);
+        }
+    });
+    test("every code has a locales directory containing translation.json", () => {
+        for (const code of codes) {
+            const file = path.resolve(`./src/locales/${code}/translation.json`);
+            expect(fs.existsSync(file), `missing ${code}`).toBe(true);
+        }
+    });
+    test("every locales directory is claimed by a code — no orphans", () => {
+        const dirs = fs.readdirSync(path.resolve("./src/locales"));
+        for (const dir of dirs) {
+            expect(codes, `orphan locale directory ${dir}`).toContain(dir);
+        }
+    });
+});
+describe("LanguageSchema", () => {
+    test("accepts every declared code", () => {
+        for (const code of codes) {
+            expect(LanguageSchema.parse(code)).toBe(code);
+        }
+    });
+    test("exposes each code on .enum for use as a constant", () => {
+        expect(LanguageSchema.enum.en).toBe("en");
+    });
+    test("rejects an undeclared language code", () => {
+        expect(() => LanguageSchema.parse("xx")).toThrow();
+    });
+    test("rejects the empty string", () => {
+        expect(() => LanguageSchema.parse("")).toThrow();
+    });
+    test("rejects a regional variant of a supported language", () => {
+        expect(() => LanguageSchema.parse("en-GB")).toThrow();
+    });
+    test("is case sensitive — `EN` is not `en`", () => {
+        expect(() => LanguageSchema.parse("EN")).toThrow();
+    });
+    test("rejects non-string input", () => {
+        expect(() => LanguageSchema.parse(1)).toThrow();
+        expect(() => LanguageSchema.parse(null)).toThrow();
+        expect(() => LanguageSchema.parse(undefined)).toThrow();
+        expect(() => LanguageSchema.parse(["en"])).toThrow();
+    });
+    test("safeParse reports failure without throwing", () => {
+        expect(LanguageSchema.safeParse("xx").success).toBe(false);
+        expect(LanguageSchema.safeParse("en").success).toBe(true);
+    });
+    test("its options are exactly the declared codes", () => {
+        expect(new Set(LanguageSchema.options)).toEqual(new Set(codes));
+    });
+});
+//# sourceMappingURL=translations.unit.test.js.map

package/dist/tests/translations.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translations.unit.test.js","sourceRoot":"","sources":["../../src/tests/translations.unit.test.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,KAAK,GAAa,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAEjD,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IAC1B,IAAI,CAAC,cAAc,EAAE,GAAG,EAAE;QACzB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,gCAAgC,EAAE,GAAG,EAAE;QAC3C,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAKH,IAAI,CAAC,wBAAwB,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACxE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;IACF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,gEAAgE,EAAE,GAAG,EAAE;QAC3E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI,mBAAmB,CAAC,CAAC;YACpE,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,CAAC;IACF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACtE,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;QAC3D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,CAAC,KAAK,EAAE,2BAA2B,GAAG,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAChE,CAAC;IACF,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC/B,IAAI,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;IACF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAChD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAClD,CAAC,CAAC,CAAC;IAKH,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC/D,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,sCAAsC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAChD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACnD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACxD,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3D,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/tests/useTranslation.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useTranslation.unit.test.d.ts.map

package/dist/tests/useTranslation.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTranslation.unit.test.d.ts","sourceRoot":"","sources":["../../src/tests/useTranslation.unit.test.ts"],"names":[],"mappings":""}

package/dist/tests/useTranslation.unit.test.js

@@ -0,0 +1,81 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+const asI18n = (value) => value;
+const load = async () => {
+    vi.resetModules();
+    const instance = asI18n({ name: "package instance" });
+    const calls = [];
+    let initCalls = 0;
+    vi.doMock("../i18nFrontend.js", () => ({
+        default: () => {
+            initCalls += 1;
+            return instance;
+        },
+    }));
+    vi.doMock("react-i18next", () => ({
+        useTranslation: (namespace, options) => {
+            calls.push([namespace, options]);
+            return { t: (key) => key, i18n: options.i18n };
+        },
+    }));
+    const imported = await import("../useTranslation.js");
+    return {
+        useTranslation: imported.default,
+        instance,
+        calls,
+        initCount: () => initCalls,
+    };
+};
+afterEach(() => {
+    vi.resetModules();
+    vi.doUnmock("../i18nFrontend.js");
+    vi.doUnmock("react-i18next");
+});
+describe("useTranslation", () => {
+    test("always asks for the translation namespace", async () => {
+        const { useTranslation, calls } = await load();
+        useTranslation();
+        expect(calls[0]?.[0]).toBe("translation");
+    });
+    test("injects the package's own i18next instance", async () => {
+        const { useTranslation, calls, instance } = await load();
+        useTranslation();
+        expect(calls[0]?.[1].i18n).toBe(instance);
+    });
+    test("initialises the frontend instance on use", async () => {
+        const { useTranslation, initCount } = await load();
+        useTranslation();
+        expect(initCount()).toBe(1);
+    });
+    test("works with no options at all", async () => {
+        const { useTranslation, calls } = await load();
+        useTranslation();
+        expect(calls[0]?.[1]).toEqual({ i18n: expect.anything() });
+    });
+    test("passes caller options through", async () => {
+        const { useTranslation, calls } = await load();
+        useTranslation({ nsMode: "fallback", useSuspense: false });
+        expect(calls[0]?.[1]).toMatchObject({
+            nsMode: "fallback",
+            useSuspense: false,
+        });
+    });
+    test("lets the caller override the instance, since options spread last", async () => {
+        const { useTranslation, calls, instance } = await load();
+        const other = asI18n({ name: "caller instance" });
+        useTranslation({ i18n: other });
+        expect(calls[0]?.[1].i18n).toBe(other);
+        expect(calls[0]?.[1].i18n).not.toBe(instance);
+    });
+    test("returns whatever react-i18next returns", async () => {
+        const { useTranslation } = await load();
+        const result = useTranslation();
+        expect(result.t("WIDGET.SUBMIT")).toBe("WIDGET.SUBMIT");
+    });
+    test("re-initialises on every call, matching hook semantics", async () => {
+        const { useTranslation, initCount } = await load();
+        useTranslation();
+        useTranslation();
+        expect(initCount()).toBe(2);
+    });
+});
+//# sourceMappingURL=useTranslation.unit.test.js.map

package/dist/tests/useTranslation.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTranslation.unit.test.js","sourceRoot":"","sources":["../../src/tests/useTranslation.unit.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/util.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=util.unit.test.d.ts.map

package/dist/tests/util.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.unit.test.d.ts","sourceRoot":"","sources":["../../src/tests/util.unit.test.ts"],"names":[],"mappings":""}

package/dist/tests/util.unit.test.js

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { isClientSide, isServerSide } from "../util.js";
+const setWindow = (value) => {
+    if (value === undefined) {
+        Reflect.deleteProperty(globalThis, "window");
+        return;
+    }
+    Object.defineProperty(globalThis, "window", {
+        value,
+        configurable: true,
+        writable: true,
+    });
+};
+afterEach(() => {
+    setWindow(undefined);
+});
+describe("isClientSide", () => {
+    test("is false under plain node, where there is no window at all", () => {
+        expect(isClientSide()).toBe(false);
+    });
+    test("is true when window exposes document.createElement", () => {
+        setWindow({ document: { createElement: () => { } } });
+        expect(isClientSide()).toBe(true);
+    });
+    test("is false when window exists but has no document", () => {
+        setWindow({});
+        expect(isClientSide()).toBe(false);
+    });
+    test("is false when document exists but has no createElement", () => {
+        setWindow({ document: {} });
+        expect(isClientSide()).toBe(false);
+    });
+    test("is false when createElement is present but undefined", () => {
+        setWindow({ document: { createElement: undefined } });
+        expect(isClientSide()).toBe(false);
+    });
+    test("returns a real boolean, not the truthy function itself", () => {
+        const createElement = () => { };
+        setWindow({ document: { createElement } });
+        const result = isClientSide();
+        expect(result).toBe(true);
+        expect(typeof result).toBe("boolean");
+    });
+});
+describe("isServerSide", () => {
+    test("is true under plain node", () => {
+        expect(isServerSide()).toBe(true);
+    });
+    test("is false in a browser-like environment", () => {
+        setWindow({ document: { createElement: () => { } } });
+        expect(isServerSide()).toBe(false);
+    });
+    test("is always the exact negation of isClientSide", () => {
+        const environments = [
+            undefined,
+            {},
+            { document: {} },
+            { document: { createElement: () => { } } },
+        ];
+        for (const environment of environments) {
+            setWindow(environment);
+            expect(isServerSide()).toBe(!isClientSide());
+        }
+    });
+});
+//# sourceMappingURL=util.unit.test.js.map

package/dist/tests/util.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.unit.test.js","sourceRoot":"","sources":["../../src/tests/util.unit.test.ts"],"names":[],"mappings":"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"}

package/dist/translationKey.d.ts

@@ -1,4 +1,8 @@
 import { z } from "zod";
+export type TranslationNode = {
+    [key: string]: TranslationNode | string;
+} | string;
+export declare function getLeafFieldPath(obj: TranslationNode): string[];
 export declare const TranslationKeysSchema: z.ZodEnum<[string, ...string[]]>;
 export type TranslationKey = z.infer<typeof TranslationKeysSchema>;
 //# sourceMappingURL=translationKey.d.ts.map

package/dist/translationKey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"translationKey.d.ts","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA6BxB,eAAO,MAAM,qBAAqB,kCAEjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"translationKey.d.ts","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,MAAM,eAAe,GACxB;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,CAAC;CACvC,GACD,MAAM,CAAC;AAKV,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,EAAE,CA8B/D;AAED,eAAO,MAAM,qBAAqB,kCAEjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/translationKey.js

@@ -6,6 +6,7 @@ function getLeafFieldPath(obj) {
 	return Object.keys(obj).reduce((arr, key) => {
 		const value = obj[key];
 		if (value === void 0) throw new Error(`Undefined value for key ${key}`);
+		if (typeof value === "string") return arr.concat(key);
 		const children = getLeafFieldPath(value);
 		return arr.concat(children.map((child) => {
 			return `${key}.${child}`;
@@ -14,4 +15,4 @@ function getLeafFieldPath(obj) {
 }
 var TranslationKeysSchema = z$1.enum(getLeafFieldPath(translation_default));
 //#endregion
-export { TranslationKeysSchema };
+export { TranslationKeysSchema, getLeafFieldPath };

package/dist/translationKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"translationKey.js","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,aAAa,MAAM,+BAA+B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAQhF,SAAS,gBAAgB,CAAC,GAAS;IAClC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAEzC,OAAO,GAAG,CAAC,MAAM,CAChB,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACtB,OAAO,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;QAC1B,CAAC,CAAC,CACF,CAAC;IACH,CAAC,EAAE,EAAc,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAC1C,gBAAgB,CAAC,aAAa,CAA0B,CACxD,CAAC"}
+{"version":3,"file":"translationKey.js","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,aAAa,MAAM,+BAA+B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAWhF,MAAM,UAAU,gBAAgB,CAAC,GAAoB;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,EAAE,CAAC,CAAC;QACnD,CAAC;QASD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAEzC,OAAO,GAAG,CAAC,MAAM,CAChB,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACtB,OAAO,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;QAC1B,CAAC,CAAC,CACF,CAAC;IACH,CAAC,EAAE,EAAc,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAC1C,gBAAgB,CAAC,aAAa,CAA0B,CACxD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/locale",
-	"version": "3.2.8",
+	"version": "3.3.0",
 	"description": "Prosopo locale library",
 	"type": "module",
 	"engines": {
@@ -43,7 +43,7 @@
 		"zod": "3.23.8"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.5",
+		"@prosopo/config": "3.3.7",
 		"@types/node": "22.10.2",
 		"@vitest/coverage-v8": "4.1.10",
 		"concurrently": "9.0.1",

package/src/i18SharedOptions.ts

@@ -11,14 +11,14 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+import { getProcess } from "./process.js";
 import { LanguageSchema, Languages } from "./translations.js";
 
-// Guard the `process.env` read so the module is loadable in a plain browser
-// runtime where `process` is undefined. Without the guard, any side-effectful
+// Read through getProcess() so the module stays loadable in a plain browser
+// runtime where `process` is undefined. Without that guard, any side-effectful
 // runtime import of `@prosopo/types` (which transitively reaches here via
 // `LanguageSchema`) crashes the page in Vite's dev/preview mode.
-const logLevel =
-	typeof process !== "undefined" ? process.env?.PROSOPO_LOG_LEVEL : undefined;
+const logLevel = getProcess()?.env?.PROSOPO_LOG_LEVEL;
 
 export const i18nSharedOptions = {
 	debug: logLevel === "debug",

package/src/i18nBackend.ts

@@ -43,9 +43,25 @@ export function initializeI18n(
 					loadPath,
 				},
 			});
+		// "loaded" fires once per namespace, and again after changeLanguage(),
+		// so the raw event is not the one-shot signal the callback expects.
+		// Latch it here as well as in loadI18next: this callback is public and
+		// a caller could reasonably use it to run a side effect.
+		let notified = false;
 		i18n.on("loaded", () => {
+			if (notified) {
+				return;
+			}
+			notified = true;
 			i18nLoadedCallback?.(i18n);
 		});
+	} else {
+		// Nothing to initialise — either i18next is already up (a frontend
+		// consumer got there first) or we are not on the server. The `loaded`
+		// handler above is only registered inside the init branch, so without
+		// this the callback would never fire and loadI18next() would stay
+		// pending forever instead of handing back the instance we already have.
+		i18nLoadedCallback?.(i18n);
 	}
 	return i18n;
 }