@multiplatform.one/i18n 6.0.0

package/tests/integrationFrappeEnabled.test.ts

@@ -0,0 +1,232 @@
+/**
+ * 10.1 Cross-group integration test: Frappe-enabled flow
+ *
+ * Simulates booting the i18n system with a Frappe backend (mocked),
+ * switching to a non-English language, and verifying:
+ *  - Frappe translations are loaded and override local resources
+ *  - frappe-ui strings render in translated language
+ *  - DocType metadata labels come back translated (mocked API)
+ */
+import { describe, it, expect } from "vitest";
+import i18next from "i18next";
+import type { BackendModule, ReadCallback } from "i18next";
+import enCommon from "../../../packages/i18n/en/common.json";
+import teCommon from "../../../packages/i18n/te/common.json";
+
+// Simulated Frappe Spanish translations (overrides for frappe-ui strings)
+const frappeEsTranslations: Record<string, string> = {
+  Save: "Guardar",
+  Delete: "Eliminar",
+  Cancel: "Cancelar",
+  Filters: "Filtros",
+  "Loading...": "Cargando...",
+  "Saved Filters": "Filtros guardados",
+  Name: "Nombre",
+  "Add Row": "Agregar fila",
+  "Expand All": "Expandir todo",
+  "Collapse All": "Contraer todo",
+  "No items found": "No se encontraron elementos",
+  "Loading {{doctype}}...": "Cargando {{doctype}}...",
+  "Loading {{doctype}} schema...": "Cargando esquema de {{doctype}}...",
+  Activity: "Actividad",
+  Attachments: "Adjuntos",
+  Tags: "Etiquetas",
+  // DocType metadata labels (what Frappe would return for field labels)
+  "Pokemon Name": "Nombre del Pokémon",
+  Species: "Especie",
+  Height: "Altura",
+  Weight: "Peso",
+};
+
+/**
+ * Build a mock Frappe backend that returns translations synchronously.
+ * i18next BackendModule `read` calls the callback synchronously
+ * so translations are available immediately after init.
+ */
+function createMockFrappeBackend(
+  mockTranslations: Record<string, Record<string, string>>,
+): BackendModule & { fetchCalls: Array<{ language: string; namespace: string }> } {
+  const fetchCalls: Array<{ language: string; namespace: string }> = [];
+  return {
+    type: "backend",
+    fetchCalls,
+    init() {},
+    read(language: string, namespace: string, callback: ReadCallback) {
+      fetchCalls.push({ language, namespace });
+      const translations = mockTranslations[language];
+      callback(null, translations ?? {});
+    },
+  };
+}
+
+/**
+ * Helper to init an i18next instance with a mock Frappe backend.
+ * Uses `partialBundledLanguages: true` so the backend is queried
+ * for languages NOT included in `resources`. English is always bundled
+ * as the fallback.
+ */
+async function initWithFrappeBackend(
+  mockBackend: BackendModule,
+  options: {
+    lng: string;
+    bundledResources?: Record<string, Record<string, unknown>>;
+    supportedLngs?: string[];
+  },
+) {
+  const instance = i18next.createInstance();
+  const { lng, bundledResources, supportedLngs = ["en", "es", "te"] } = options;
+
+  await new Promise<void>((resolve, reject) => {
+    instance.use(mockBackend).init(
+      {
+        lng,
+        defaultNS: "common",
+        ns: ["common"],
+        supportedLngs,
+        fallbackLng: "en",
+        // Only bundle English + any explicitly provided resources.
+        // Non-bundled languages (like es) will be fetched from backend.
+        resources: bundledResources ?? {
+          en: { common: enCommon },
+        },
+        partialBundledLanguages: true,
+        interpolation: { escapeValue: false },
+        returnNull: false,
+        returnEmptyString: false,
+      },
+      (err) => {
+        if (err) reject(err);
+        else resolve();
+      },
+    );
+  });
+
+  return instance;
+}
+
+describe("10.1 Frappe-enabled integration flow", () => {
+  it("loads Frappe translations that override local resources for Spanish", async () => {
+    const mockBackend = createMockFrappeBackend({
+      es: frappeEsTranslations,
+    });
+
+    const instance = await initWithFrappeBackend(mockBackend, { lng: "es" });
+
+    // The backend was called to fetch Spanish translations
+    expect(mockBackend.fetchCalls.length).toBeGreaterThanOrEqual(1);
+    expect(mockBackend.fetchCalls.some((c) => c.language === "es")).toBe(true);
+
+    // Frappe translations override local resources
+    expect(instance.t("Save")).toBe("Guardar");
+    expect(instance.t("Filters")).toBe("Filtros");
+    expect(instance.t("Cancel")).toBe("Cancelar");
+    expect(instance.t("Loading...")).toBe("Cargando...");
+    expect(instance.t("Expand All")).toBe("Expandir todo");
+    expect(instance.t("No items found")).toBe("No se encontraron elementos");
+  });
+
+  it("frappe-ui strings with interpolation render in translated language", async () => {
+    const mockBackend = createMockFrappeBackend({
+      es: frappeEsTranslations,
+    });
+
+    const instance = await initWithFrappeBackend(mockBackend, { lng: "es" });
+
+    // Interpolated frappe-ui strings
+    expect(instance.t("Loading {{doctype}}...", { doctype: "Pokemon" })).toBe(
+      "Cargando Pokemon...",
+    );
+    expect(instance.t("Loading {{doctype}} schema...", { doctype: "Pokemon" })).toBe(
+      "Cargando esquema de Pokemon...",
+    );
+  });
+
+  it("DocType metadata labels come back translated from Frappe", async () => {
+    const mockBackend = createMockFrappeBackend({
+      es: frappeEsTranslations,
+    });
+
+    const instance = await initWithFrappeBackend(mockBackend, {
+      lng: "es",
+      supportedLngs: ["en", "es"],
+    });
+
+    // DocType field labels translated by Frappe
+    expect(instance.t("Pokemon Name")).toBe("Nombre del Pokémon");
+    expect(instance.t("Species")).toBe("Especie");
+    expect(instance.t("Height")).toBe("Altura");
+    expect(instance.t("Weight")).toBe("Peso");
+  });
+
+  it("falls back to English local resource when Frappe has no translation for a key", async () => {
+    const mockBackend = createMockFrappeBackend({
+      es: { Save: "Guardar" }, // Only one key translated by Frappe
+    });
+
+    const instance = await initWithFrappeBackend(mockBackend, {
+      lng: "es",
+      supportedLngs: ["en", "es"],
+    });
+
+    // Key from Frappe
+    expect(instance.t("Save")).toBe("Guardar");
+    // Key NOT in Frappe's dict → falls back to English local resource (identity mapping)
+    expect(instance.t("Filters")).toBe("Filters");
+    expect(instance.t("common.appName")).toBe("multiplatform.one");
+  });
+
+  it("switching language triggers a new backend fetch", async () => {
+    const mockBackend = createMockFrappeBackend({
+      es: frappeEsTranslations,
+      te: { Save: "సేవ్ చేయండి", Filters: "ఫిల్టర్‌లు" },
+    });
+
+    // Start in English (bundled), then switch to Spanish (backend)
+    const instance = await initWithFrappeBackend(mockBackend, { lng: "en" });
+
+    // Initially English from bundled resources
+    expect(instance.t("Save")).toBe("Save");
+
+    // Switch to Spanish — triggers backend fetch
+    await instance.changeLanguage("es");
+    expect(instance.t("Save")).toBe("Guardar");
+    expect(mockBackend.fetchCalls.some((c) => c.language === "es")).toBe(true);
+
+    // Switch to Telugu — triggers another backend fetch
+    await instance.changeLanguage("te");
+    expect(instance.t("Save")).toBe("సేవ్ చేయండి");
+    expect(instance.t("Filters")).toBe("ఫిల్టర్‌లు");
+    expect(mockBackend.fetchCalls.some((c) => c.language === "te")).toBe(true);
+  });
+
+  it("bundled languages use local resources; backend only serves non-bundled languages", async () => {
+    // Architecture: en and te are bundled locally. Spanish is not bundled,
+    // so Frappe backend provides it. The backend is NOT called for bundled languages.
+    const mockBackend = createMockFrappeBackend({
+      es: frappeEsTranslations,
+    });
+
+    const instance = await initWithFrappeBackend(mockBackend, {
+      lng: "te",
+      // Telugu is fully bundled — backend should NOT be called for it
+      bundledResources: {
+        en: { common: enCommon },
+        te: { common: teCommon },
+      },
+    });
+
+    // Backend was NOT called for Telugu (it's bundled)
+    expect(mockBackend.fetchCalls.some((c) => c.language === "te")).toBe(false);
+
+    // Telugu translations come from local bundled resources
+    expect(instance.t("Save")).toBe("సేవ్ చేయండి");
+    expect(instance.t("Filters")).toBe("ఫిల్టర్‌లు");
+    expect(instance.t("Delete")).toBe("తొలగించు");
+
+    // Switch to Spanish (not bundled) — backend provides translations
+    await instance.changeLanguage("es");
+    expect(mockBackend.fetchCalls.some((c) => c.language === "es")).toBe(true);
+    expect(instance.t("Save")).toBe("Guardar");
+    expect(instance.t("Filters")).toBe("Filtros");
+  });
+});

package/tests/integrationLanguagePersistence.test.ts

@@ -0,0 +1,241 @@
+/**
+ * 10.3 Cross-group integration test: Language persistence roundtrip
+ *
+ * Verifies end-to-end language persistence:
+ *  - Change language → cookie set → simulate reload → same language restored
+ *  - Change language → Frappe API receives new language context
+ *  - SSR detection → correct language from Accept-Language
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import i18next from "i18next";
+import { persistLanguage, getPersistedLanguage, parseCookieValue } from "../src/localePersistence";
+import { detectLanguage } from "../src/detectLanguage";
+import enCommon from "../../../packages/i18n/en/common.json";
+import teCommon from "../../../packages/i18n/te/common.json";
+
+describe("10.3 Language persistence roundtrip", () => {
+  let cookieStore: string;
+
+  beforeEach(() => {
+    cookieStore = "";
+    Object.defineProperty(globalThis, "document", {
+      value: {
+        get cookie() {
+          return cookieStore;
+        },
+        set cookie(val: string) {
+          const name = val.split("=")[0];
+          const parts = cookieStore.split("; ").filter((c) => c && !c.startsWith(`${name}=`));
+          parts.push(val.split(";")[0]);
+          cookieStore = parts.filter(Boolean).join("; ");
+        },
+      },
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(globalThis, "document", {
+      value: undefined,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  it("change language → cookie set → simulate reload → same language restored", async () => {
+    // Step 1: Initialize i18next with English
+    const instance1 = i18next.createInstance();
+    await instance1.init({
+      lng: "en",
+      defaultNS: "common",
+      ns: ["common"],
+      supportedLngs: ["en", "te"],
+      fallbackLng: "en",
+      resources: {
+        en: { common: enCommon },
+        te: { common: teCommon },
+      },
+      interpolation: { escapeValue: false },
+      returnNull: false,
+    });
+
+    expect(instance1.language).toBe("en");
+    expect(instance1.t("Save")).toBe("Save");
+
+    // Step 2: Change language to Telugu and persist (simulates useLanguage.changeLanguage)
+    persistLanguage("te");
+    await instance1.changeLanguage("te");
+
+    expect(instance1.language).toBe("te");
+    expect(instance1.t("Save")).toBe("సేవ్ చేయండి");
+
+    // Verify cookie is set
+    expect(getPersistedLanguage()).toBe("te");
+
+    // Step 3: Simulate "reload" — create a new i18next instance and read persisted language
+    const persistedLang = getPersistedLanguage();
+    expect(persistedLang).toBe("te");
+
+    const instance2 = i18next.createInstance();
+    await instance2.init({
+      lng: persistedLang!, // Use the persisted language
+      defaultNS: "common",
+      ns: ["common"],
+      supportedLngs: ["en", "te"],
+      fallbackLng: "en",
+      resources: {
+        en: { common: enCommon },
+        te: { common: teCommon },
+      },
+      interpolation: { escapeValue: false },
+      returnNull: false,
+    });
+
+    // Language is restored from cookie
+    expect(instance2.language).toBe("te");
+    expect(instance2.t("Save")).toBe("సేవ్ చేయండి");
+    expect(instance2.t("Filters")).toBe("ఫిల్టర్‌లు");
+    expect(instance2.t("Delete")).toBe("తొలగించు");
+  });
+
+  it("language change updates cookie that Frappe API can read from request", async () => {
+    // Simulate language change
+    persistLanguage("es");
+    expect(getPersistedLanguage()).toBe("es");
+
+    // The preferred_language cookie is included in HTTP requests (via credentials: "include")
+    // Frappe reads this cookie to determine the user's language preference.
+    // Verify the cookie value is parseable from a simulated request cookie header.
+    const simulatedCookieHeader = `session_id=abc123; ${cookieStore}`;
+    const parsedLang = parseCookieValue(simulatedCookieHeader, "preferred_language");
+    expect(parsedLang).toBe("es");
+
+    // Change language again
+    persistLanguage("te");
+    const updatedCookieHeader = `session_id=abc123; ${cookieStore}`;
+    const updatedLang = parseCookieValue(updatedCookieHeader, "preferred_language");
+    expect(updatedLang).toBe("te");
+  });
+
+  it("SSR detects language from cookie in Request headers", () => {
+    const supported = ["en", "es", "te"];
+    const opts = { supportedLanguages: supported, defaultLanguage: "en" };
+
+    // User previously set Telugu
+    const req = new Request("http://localhost:8000/", {
+      headers: {
+        cookie: "preferred_language=te; session_id=xyz",
+        "accept-language": "en-US,en;q=0.9",
+      },
+    });
+
+    const detected = detectLanguage(req, opts);
+    // Cookie takes precedence over Accept-Language
+    expect(detected).toBe("te");
+  });
+
+  it("SSR falls back to Accept-Language when no cookie is set", () => {
+    const supported = ["en", "es", "te"];
+    const opts = { supportedLanguages: supported, defaultLanguage: "en" };
+
+    const req = new Request("http://localhost:8000/", {
+      headers: {
+        "accept-language": "es-MX;q=1.0, en;q=0.5",
+      },
+    });
+
+    const detected = detectLanguage(req, opts);
+    expect(detected).toBe("es");
+  });
+
+  it("full roundtrip: persist → SSR detect → initialize with correct language", async () => {
+    // Step 1: User changes language on the client
+    persistLanguage("te");
+
+    // Step 2: On next request, SSR reads cookie from the request
+    const simulatedRequest = new Request("http://localhost:8000/", {
+      headers: {
+        cookie: cookieStore,
+        "accept-language": "en-US,en;q=0.9",
+      },
+    });
+
+    const detected = detectLanguage(simulatedRequest, {
+      supportedLanguages: ["en", "te", "es"],
+      defaultLanguage: "en",
+    });
+
+    expect(detected).toBe("te");
+
+    // Step 3: SSR initializes i18next with detected language
+    const instance = i18next.createInstance();
+    await instance.init({
+      lng: detected,
+      defaultNS: "common",
+      ns: ["common"],
+      supportedLngs: ["en", "te"],
+      fallbackLng: "en",
+      resources: {
+        en: { common: enCommon },
+        te: { common: teCommon },
+      },
+      interpolation: { escapeValue: false },
+      returnNull: false,
+    });
+
+    // SSR renders in the user's chosen language
+    expect(instance.language).toBe("te");
+    expect(instance.t("Save")).toBe("సేవ్ చేయండి");
+    expect(instance.t("Filters")).toBe("ఫిల్టర్‌లు");
+    expect(instance.t("common.appName")).toBe("multiplatform.one");
+  });
+
+  it("language change triggers Frappe API to receive new language context via cookie", async () => {
+    // Simulate the sequence:
+    // 1. User is in English
+    // 2. User switches to Telugu
+    // 3. Next HTTP request includes preferred_language=te cookie
+    persistLanguage("en");
+    expect(getPersistedLanguage()).toBe("en");
+
+    // Simulate: user clicks "Telugu" in language switcher
+    persistLanguage("te");
+    expect(getPersistedLanguage()).toBe("te");
+
+    // Simulate: next API call includes cookies
+    // The HttpClient sends requests with credentials: "include",
+    // so the preferred_language cookie is automatically included.
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          data: [
+            { name: "Pikachu", species: "పికాచు" }, // Telugu metadata from Frappe
+          ],
+        }),
+    });
+
+    // Simulate an API call that would be made after language change
+    await mockFetch("/api/resource/Pokemon", {
+      credentials: "include",
+      headers: {
+        "Accept-Language": "te",
+        Cookie: cookieStore,
+      },
+    });
+
+    // Verify the API call was made with language context
+    expect(mockFetch).toHaveBeenCalledWith("/api/resource/Pokemon", {
+      credentials: "include",
+      headers: expect.objectContaining({
+        "Accept-Language": "te",
+      }),
+    });
+
+    // The cookie header contains preferred_language=te
+    const callArgs = mockFetch.mock.calls[0][1];
+    const cookieVal = parseCookieValue(callArgs.headers.Cookie, "preferred_language");
+    expect(cookieVal).toBe("te");
+  });
+});

package/tests/integrationTreeshaking.test.ts

@@ -0,0 +1,126 @@
+/**
+ * 10.5 Bundle size / tree-shaking verification
+ *
+ * Verifies that the Frappe backend plugin code is structured to tree-shake
+ * out of non-Frappe builds:
+ *  - createFrappeBackend is guarded by process.env.VITE_FRAPPE_ENABLED
+ *  - When VITE_FRAPPE_ENABLED=false, createFrappeBackend returns null
+ *  - createI18nConfig does not attach backend when VITE_FRAPPE_ENABLED=false
+ *  - The Frappe API URL telltale string is inside the guarded code path
+ *  - The module source structure enables dead-code elimination
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createFrappeBackend } from "../src/frappeBackend";
+import { createI18nConfig } from "../src/createI18nConfig";
+import type { BackendModule } from "i18next";
+
+describe("10.5 Tree-shaking & bundle verification", () => {
+  describe("runtime guards", () => {
+    it("createFrappeBackend returns null when VITE_FRAPPE_ENABLED is false", () => {
+      // In the test environment, VITE_FRAPPE_ENABLED defaults to "false"
+      const backend = createFrappeBackend();
+      expect(backend).toBeNull();
+    });
+
+    it("createI18nConfig does not attach backend when disabled", () => {
+      const config = createI18nConfig({
+        languages: ["en"],
+        namespaces: ["common"],
+        defaultLanguage: "en",
+        defaultNamespace: "common",
+        resources: { en: { common: {} } },
+        frappeBackend: null,
+      });
+
+      expect(config.backend).toBeUndefined();
+      expect(config.partialBundledLanguages).toBeUndefined();
+    });
+
+    it("createI18nConfig omits backend even when a non-null backend is passed but flag is false", () => {
+      const mockBackend: BackendModule = {
+        type: "backend",
+        init() {},
+        read() {},
+      };
+
+      const config = createI18nConfig({
+        languages: ["en"],
+        namespaces: ["common"],
+        defaultLanguage: "en",
+        defaultNamespace: "common",
+        resources: { en: { common: {} } },
+        frappeBackend: mockBackend,
+      });
+
+      // Even though a backend was provided, it's not attached because VITE_FRAPPE_ENABLED=false
+      expect(config.backend).toBeUndefined();
+    });
+  });
+
+  describe("source code structure enables tree-shaking", () => {
+    it("frappeBackend.ts guards the entire backend creation with VITE_FRAPPE_ENABLED check", () => {
+      const source = readFileSync(resolve(__dirname, "../src/frappeBackend.ts"), "utf-8");
+
+      // The guard must be present — this is what allows bundlers to eliminate the code
+      expect(source).toContain("process.env.VITE_FRAPPE_ENABLED");
+      expect(source).toContain("return null");
+
+      // The Frappe API URL (telltale string) is INSIDE the guarded code path
+      expect(source).toContain("frappe.translate.get_dict");
+
+      // The guard pattern: returns null early when flag is not "true"
+      // This means when the bundler replaces VITE_FRAPPE_ENABLED with "false",
+      // the entire backend object literal becomes dead code.
+      expect(source).toMatch(/VITE_FRAPPE_ENABLED.*!==.*"true".*return null/s);
+    });
+
+    it("createI18nConfig.ts guards backend attachment with VITE_FRAPPE_ENABLED check", () => {
+      const source = readFileSync(resolve(__dirname, "../src/createI18nConfig.ts"), "utf-8");
+
+      // The config conditionally includes backend only when enabled
+      expect(source).toContain("process.env.VITE_FRAPPE_ENABLED");
+      expect(source).toContain("partialBundledLanguages");
+
+      // The guard pattern: if block only executes when VITE_FRAPPE_ENABLED === "true"
+      expect(source).toMatch(/VITE_FRAPPE_ENABLED.*===.*"true".*frappeBackend/s);
+    });
+
+    it("frappeBackend.ts does not have side effects at module level", () => {
+      const source = readFileSync(resolve(__dirname, "../src/frappeBackend.ts"), "utf-8");
+
+      // The fetch function is defined but not called at module level.
+      // Only createFrappeBackend() is exported, and it returns null when disabled.
+      // This ensures Vite/Rollup can tree-shake the entire module.
+      expect(source).not.toMatch(/^fetch\(/m);
+      expect(source).not.toMatch(/^await /m);
+      // The package.json has "sideEffects": false, confirming tree-shaking
+    });
+
+    it("package.json has sideEffects: false for tree-shaking", () => {
+      const pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf-8"));
+      expect(pkg.sideEffects).toBe(false);
+    });
+  });
+
+  describe("export structure", () => {
+    it("index.ts exports createFrappeBackend (tree-shakeable named export)", () => {
+      const source = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+
+      // Named exports allow tree-shaking — consumers that don't import
+      // createFrappeBackend won't include it in their bundle
+      expect(source).toContain("createFrappeBackend");
+
+      // It's a named re-export, not a default export or namespace import
+      expect(source).toMatch(/export\s*\{.*createFrappeBackend.*\}/s);
+    });
+
+    it("all i18n exports are named (not default) for optimal tree-shaking", () => {
+      const source = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+
+      // No default export — all named exports are individually tree-shakeable
+      expect(source).not.toContain("export default");
+    });
+  });
+});