alepha 0.15.1 → 0.15.3

package/src/react/i18n/providers/I18nProvider.spec.ts

@@ -0,0 +1,389 @@
+import { Alepha } from "alepha";
+import { describe, test } from "vitest";
+import { AlephaReactI18n } from "../index.ts";
+import { $dictionary } from "../primitives/$dictionary.ts";
+import { I18nProvider } from "./I18nProvider.ts";
+
+describe("I18nProvider", () => {
+  test("should register dictionaries on initialization", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { hello: "Bonjour" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    expect(i18n.registry).toHaveLength(2);
+    expect(i18n.registry[0].lang).toBe("en");
+    expect(i18n.registry[1].lang).toBe("fr");
+  });
+
+  test("should load all translations on server start", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello", world: "World" } }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { hello: "Bonjour", world: "Monde" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.registry[0].translations).toEqual({
+      hello: "Hello",
+      world: "World",
+    });
+    expect(i18n.registry[1].translations).toEqual({
+      hello: "Bonjour",
+      world: "Monde",
+    });
+  });
+
+  test("should default to fallback language", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    expect(i18n.lang).toBe("en");
+  });
+
+  test("should translate keys in current language", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { greeting: "Hello, World!" } }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { greeting: "Bonjour, Monde!" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.tr("greeting")).toBe("Hello, World!");
+
+    await i18n.setLang("fr");
+    expect(i18n.tr("greeting")).toBe("Bonjour, Monde!");
+  });
+
+  test("should fallback to fallback language when key missing", async ({
+    expect,
+  }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({
+          default: { hello: "Hello", world: "World" },
+        }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { hello: "Bonjour" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+    await i18n.setLang("fr");
+
+    expect(i18n.tr("hello")).toBe("Bonjour");
+    expect(i18n.tr("world")).toBe("World"); // Falls back to English
+  });
+
+  test("should return key when translation not found", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.tr("missing.key")).toBe("missing.key");
+  });
+
+  test("should support default option when key missing", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.tr("missing", { default: "Default Text" })).toBe(
+      "Default Text",
+    );
+  });
+
+  test("should support variable interpolation", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({
+          default: { greeting: "Hello, $1! You have $2 messages." },
+        }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.tr("greeting", { args: ["John", "5"] })).toBe(
+      "Hello, John! You have 5 messages.",
+    );
+  });
+
+  test("should list all available languages", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { hello: "Bonjour" } }),
+      });
+
+      de = $dictionary({
+        lazy: async () => ({ default: { hello: "Hallo" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    const languages = i18n.languages;
+    expect(languages).toContain("en");
+    expect(languages).toContain("fr");
+    expect(languages).toContain("de");
+    expect(languages).toHaveLength(3);
+  });
+
+  test("should support custom language codes", async ({ expect }) => {
+    class App {
+      enUS = $dictionary({
+        lang: "en-US",
+        lazy: async () => ({ default: { color: "color" } }),
+      });
+
+      enGB = $dictionary({
+        lang: "en-GB",
+        lazy: async () => ({ default: { color: "colour" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.registry[0].lang).toBe("en-US");
+    expect(i18n.registry[1].lang).toBe("en-GB");
+  });
+
+  test("should support custom dictionary names", async ({ expect }) => {
+    class App {
+      english = $dictionary({
+        name: "custom-en",
+        lang: "en",
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    expect(i18n.registry[0].name).toBe("custom-en");
+  });
+
+  test("should update state when language changes", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { hello: "Bonjour" } }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    // State is set lazily, so we should set a language first
+    await i18n.setLang("en");
+    expect(alepha.store.get("alepha.react.i18n.lang")).toBe("en");
+
+    await i18n.setLang("fr");
+    expect(alepha.store.get("alepha.react.i18n.lang")).toBe("fr");
+  });
+
+  test("should have number formatter for current language", async ({
+    expect,
+  }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: {} }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.numberFormat).toBeDefined();
+    expect(i18n.numberFormat.format).toBeTypeOf("function");
+  });
+
+  test("should handle multiple translations with same key across dictionaries", async ({
+    expect,
+  }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({
+          default: {
+            app: "Application",
+            settings: "Settings",
+          },
+        }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({
+          default: {
+            app: "Programme",
+            settings: "Paramètres",
+          },
+        }),
+      });
+
+      es = $dictionary({
+        lazy: async () => ({
+          default: {
+            app: "Aplicación",
+            settings: "Configuración",
+          },
+        }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.tr("app")).toBe("Application");
+    expect(i18n.tr("settings")).toBe("Settings");
+
+    await i18n.setLang("fr");
+    expect(i18n.tr("app")).toBe("Programme");
+    expect(i18n.tr("settings")).toBe("Paramètres");
+
+    await i18n.setLang("es");
+    expect(i18n.tr("app")).toBe("Aplicación");
+    expect(i18n.tr("settings")).toBe("Configuración");
+  });
+
+  test("should handle empty dictionaries", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: {} }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.tr("anything")).toBe("anything");
+  });
+
+  test("should handle complex interpolation patterns", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({
+          default: {
+            complex: "User $1 has $2 followers and follows $3 people",
+          },
+        }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    expect(i18n.tr("complex", { args: ["Alice", "1000", "500"] })).toBe(
+      "User Alice has 1000 followers and follows 500 people",
+    );
+  });
+
+  test("should handle partial interpolation args", async ({ expect }) => {
+    class App {
+      en = $dictionary({
+        lazy: async () => ({
+          default: { message: "Hello $1, you have $2 messages and $3 alerts" },
+        }),
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaReactI18n);
+    const app = alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+
+    await alepha.start();
+
+    // Provide fewer args than placeholders
+    expect(i18n.tr("message", { args: ["Bob"] })).toBe(
+      "Hello Bob, you have $2 messages and $3 alerts",
+    );
+  });
+});

package/src/react/i18n/providers/I18nProvider.ts

@@ -0,0 +1,278 @@
+import { $hook, $inject, Alepha, TypeBoxError, TypeProvider, t } from "alepha";
+import { type DateTime, DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $cookie } from "alepha/server/cookies";
+import type { ServiceDictionary } from "../hooks/useI18n.ts";
+
+export class I18nProvider<
+  S extends object,
+  K extends keyof ServiceDictionary<S>,
+> {
+  protected log = $logger();
+  protected alepha = $inject(Alepha);
+  protected dateTimeProvider = $inject(DateTimeProvider);
+
+  protected cookie = $cookie({
+    name: "lang",
+    schema: t.text(),
+    ttl: [1, "year"],
+  });
+
+  public readonly registry: Array<{
+    target: string;
+    name: string;
+    lang: string;
+    loader: () => Promise<Record<string, string>>;
+    translations: Record<string, string>;
+  }> = [];
+
+  options = {
+    fallbackLang: "en",
+  };
+
+  public dateFormat: { format: (value: Date) => string } =
+    new Intl.DateTimeFormat(this.lang);
+
+  public numberFormat: { format: (value: number) => string } =
+    new Intl.NumberFormat(this.lang);
+
+  public get languages() {
+    const languages = new Set<string>();
+
+    for (const item of this.registry) {
+      languages.add(item.lang);
+    }
+    languages.add(this.options.fallbackLang);
+
+    return Array.from(languages);
+  }
+
+  constructor() {
+    this.refreshLocale();
+  }
+
+  protected readonly onRender = $hook({
+    on: "server:onRequest",
+    priority: "last",
+    handler: async ({ request }) => {
+      this.alepha.store.set("alepha.react.i18n.lang", this.cookie.get(request));
+    },
+  });
+
+  protected readonly onStart = $hook({
+    on: "start",
+    handler: async () => {
+      if (this.alepha.isBrowser()) {
+        // get cookie lang
+        const cookieLang = this.cookie.get();
+        if (cookieLang) {
+          this.alepha.store.set("alepha.react.i18n.lang", cookieLang);
+        }
+
+        for (const item of this.registry) {
+          if (
+            item.lang === this.lang ||
+            item.lang === this.options.fallbackLang
+          ) {
+            this.log.trace("Loading language", {
+              lang: item.lang,
+              name: item.name,
+              target: item.target,
+            });
+            item.translations = await item.loader();
+          }
+        }
+        return;
+      }
+
+      for (const item of this.registry) {
+        item.translations = await item.loader();
+      }
+    },
+  });
+
+  protected refreshLocale() {
+    this.numberFormat = new Intl.NumberFormat(this.lang);
+    this.dateFormat = new Intl.DateTimeFormat(this.lang);
+    this.dateTimeProvider.setLocale(this.lang);
+    TypeProvider.setLocale(this.lang);
+  }
+
+  public setLang = async (lang: string) => {
+    if (this.alepha.isBrowser()) {
+      for (const item of this.registry) {
+        if (lang === item.lang) {
+          if (Object.keys(item.translations).length > 0) {
+            continue; // already loaded
+          }
+          item.translations = await item.loader();
+        }
+      }
+      this.cookie.set(lang);
+    }
+
+    this.alepha.store.set("alepha.react.i18n.lang", lang);
+    this.refreshLocale();
+  };
+
+  protected readonly mutate = $hook({
+    on: "state:mutate",
+    handler: async ({ key, value }) => {
+      if (key === "alepha.react.i18n.lang" && this.alepha.isBrowser()) {
+        let hasChanged = false;
+        for (const item of this.registry) {
+          if (value === item.lang) {
+            if (Object.keys(item.translations).length > 0) {
+              continue; // already loaded
+            }
+            item.translations = await item.loader();
+            hasChanged = true;
+          }
+        }
+
+        this.refreshLocale();
+
+        if (hasChanged) {
+          this.alepha.store.set("alepha.react.i18n.lang", value);
+        }
+      }
+    },
+  });
+
+  public get lang(): string {
+    return (
+      this.alepha.store.get("alepha.react.i18n.lang") ||
+      this.options.fallbackLang
+    );
+  }
+
+  public translate = (key: string, args: string[] = []) => {
+    for (const item of this.registry) {
+      if (item.lang === this.lang) {
+        if (item.translations[key]) {
+          return this.render(item.translations[key], args); // append lang for fallback
+        }
+      }
+    }
+
+    for (const item of this.registry) {
+      if (item.lang === this.options.fallbackLang) {
+        if (item.translations[key]) {
+          return this.render(item.translations[key], args); // append lang for fallback
+        }
+      }
+    }
+
+    return key; // fallback to the key itself if not found
+  };
+
+  public readonly l = (
+    value: I18nLocalizeType,
+    options: I18nLocalizeOptions = {},
+  ) => {
+    // Handle numbers
+    if (typeof value === "number" && !options.date) {
+      return new Intl.NumberFormat(this.lang, options.number).format(value);
+    }
+
+    // Handle dates
+    if (
+      value instanceof Date ||
+      this.dateTimeProvider.isDateTime(value) ||
+      (typeof value === "string" && options.date) ||
+      (typeof value === "number" && options.date)
+    ) {
+      // convert to DateTime with locale applied
+      let dt = this.dateTimeProvider.of(value);
+
+      // apply timezone if specified
+      if (options.timezone) {
+        dt = dt.tz(options.timezone);
+      }
+
+      // format using dayjs format string
+      if (typeof options.date === "string") {
+        if (options.date === "fromNow") {
+          return dt.locale(this.lang).fromNow();
+        }
+        return dt.locale(this.lang).format(options.date);
+      }
+
+      // format using Intl.DateTimeFormatOptions
+      if (options.date) {
+        return new Intl.DateTimeFormat(
+          this.lang,
+          options.timezone
+            ? { ...options.date, timeZone: options.timezone }
+            : options.date,
+        ).format(dt.toDate());
+      }
+
+      // default formatting with timezone
+      if (options.timezone) {
+        return new Intl.DateTimeFormat(this.lang, {
+          timeZone: options.timezone,
+        }).format(dt.toDate());
+      }
+
+      // default formatting
+      return new Intl.DateTimeFormat(this.lang).format(dt.toDate());
+    }
+
+    // handle TypeBox errors
+    if (value instanceof TypeBoxError) {
+      return TypeProvider.translateError(value, this.lang);
+    }
+
+    // return string values as-is
+    return value;
+  };
+
+  public readonly tr = (
+    key: keyof ServiceDictionary<S>[K],
+    options: {
+      args?: string[];
+      default?: string;
+    } = {},
+  ) => {
+    const translation = this.translate(key as string, options.args || []);
+    if (translation === key && options.default) {
+      return options.default;
+    }
+    return translation;
+  };
+
+  protected render(item: string, args: string[]): string {
+    let result = item;
+    for (let i = 0; i < args.length; i++) {
+      result = result.replace(`$${i + 1}`, args[i]);
+    }
+    return result;
+  }
+}
+
+export type I18nLocalizeType = string | number | Date | DateTime | TypeBoxError;
+
+export interface I18nLocalizeOptions {
+  /**
+   * Options for number formatting (when value is a number)
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat
+   */
+  number?: Intl.NumberFormatOptions;
+  /**
+   * Options for date formatting (when value is a Date or DateTime)
+   * Can be:
+   * - A dayjs format string (e.g., "LLL", "YYYY-MM-DD", "dddd, MMMM D YYYY")
+   * - "fromNow" for relative time (e.g., "2 hours ago")
+   * - Intl.DateTimeFormatOptions for native formatting
+   * @see https://day.js.org/docs/en/display/format
+   * @see https://day.js.org/docs/en/display/from-now
+   */
+  date?: string | "fromNow" | Intl.DateTimeFormatOptions;
+  /**
+   * Timezone to display dates in (when value is a Date or DateTime)
+   * Uses IANA timezone names (e.g., "America/New_York", "Europe/Paris", "Asia/Tokyo")
+   * @see https://day.js.org/docs/en/timezone/timezone
+   */
+  timezone?: string;
+}