@unbrained/pm-web 2026.7.17 → 2026.7.18

package/public/src/i18n.js

@@ -0,0 +1,287 @@
+// ═══════════════════════════════════════════════════════════════
+// i18n — locale resolution, catalog lookup, DOM binding
+// ═══════════════════════════════════════════════════════════════
+//
+// Flat JSON catalogs (one file per locale) live alongside this module in
+// `public/src/i18n/{en,de}.json`. They are fetched at runtime so the browser
+// bundle stays free of new build-time dependencies and the same JSON files
+// can be audited by tests directly. The English catalog is the source of
+// truth: every key must exist in `en.json`; other locales fall back to it.
+//
+// Scope: this module covers *package-owned* SPA UI strings (auth screen, nav,
+// banners, settings incl. registration acknowledgement, consent UI). Server
+// API error strings stay English on the wire and are translated at the
+// display layer via `translateError()` (fallback: raw message).
+//
+// Legal pages (`public/*.html`) are operator-overlay templates
+// (`PM_WEB_LEGAL_DIR`); their localization is an operator concern and is NOT
+// handled here. The language selector deliberately does not promise
+// translated legal pages — see `settings.languageHint` and the German
+// disclaimer string `legal.disclaimer`.
+/** localStorage key persisting the user's locale choice. */
+export const LOCALE_STORAGE_KEY = 'pmLocale';
+/** Locales shipped by this package. The first entry is the default/fallback. */
+export const SUPPORTED_LOCALES = ['en', 'de', 'es', 'zh'];
+const DEFAULT_LOCALE = 'en';
+/**
+ * Resolve the active locale without touching the DOM, so it is unit-testable
+ * in Node. Resolution order:
+ *   1. `opts.storage[LOCALE_STORAGE_KEY]` (explicit user choice)
+ *   2. `opts.navLang` prefix match against SUPPORTED_LOCALES (e.g. `de-DE` → `de`)
+ *   3. default locale (`en`)
+ *
+ * `opts.storage` may be `null` to skip the localStorage step; `opts.navLang`
+ * may be omitted to skip navigator negotiation. When called with no
+ * arguments the real browser globals (`localStorage`, `navigator.language`)
+ * are used — but only inside this function, never at module top level, so
+ * importing this module in Node has no side effects.
+ */
+export function resolveLocale(opts) {
+    // A property that is present (even if `null`) means the caller explicitly
+    // wants that value: `null` skips the step. A property that is absent falls
+    // back to the real browser global, so the no-argument browser path still
+    // works. This keeps the function deterministic and unit-testable in Node.
+    const hasStorage = opts != null && Object.prototype.hasOwnProperty.call(opts, 'storage');
+    const storage = hasStorage ? opts.storage : safeLocalStorage();
+    if (storage) {
+        let stored = null;
+        try {
+            stored = storage.getItem(LOCALE_STORAGE_KEY);
+        }
+        catch { /* privacy mode */ }
+        if (stored && isSupported(stored))
+            return stored;
+    }
+    const hasNav = opts != null && Object.prototype.hasOwnProperty.call(opts, 'navLang');
+    const navLang = hasNav ? opts.navLang : safeNavLang();
+    if (navLang) {
+        const prefix = navLang.toLowerCase().split('-')[0];
+        if (prefix && isSupported(prefix))
+            return prefix;
+    }
+    return DEFAULT_LOCALE;
+}
+function isSupported(value) {
+    return SUPPORTED_LOCALES.includes(value);
+}
+/** localStorage access guarded so Node imports/tests never crash.
+ * Resolving the storage reference itself can throw a `SecurityError` in
+ * privacy/incognito modes that disable storage, so the lookup is wrapped too. */
+function safeLocalStorage() {
+    try {
+        const g = globalThis;
+        return g.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** navigator.language access guarded so Node imports/tests never crash. */
+function safeNavLang() {
+    const n = globalThis.navigator;
+    return n?.language;
+}
+/**
+ * Pure catalog lookup with fallback. Used by `t()` and directly by tests.
+ *
+ * @param catalog   the active locale catalog (may be partial)
+ * @param fallback  the fallback catalog (English — must contain every key)
+ * @param key       dotted string id
+ * @param params    optional `{name: value}` substitutions for `{name}` tokens
+ * @returns the translated string, or the key itself if missing from both
+ */
+export function translate(catalog, fallback, key, params) {
+    let raw = catalog[key] ?? fallback[key] ?? key;
+    if (params) {
+        for (const [name, value] of Object.entries(params)) {
+            raw = raw.replaceAll(`{${name}}`, String(value));
+        }
+    }
+    return raw;
+}
+// ── Runtime state (populated by initI18n / setLocale) ───────────────
+let currentLocale = DEFAULT_LOCALE;
+let activeCatalog = {};
+let enCatalog = {};
+let initialized = false;
+/**
+ * Monotonic request id for setLocale. Each invocation increments this; an
+ * in-flight request records its id and, after its awaited catalog fetch,
+ * commits state only if it is still the latest. This discards stale catalogs
+ * when language changes overlap (e.g. rapid de → en) so a slower earlier
+ * fetch can never overwrite a newer selection.
+ */
+let localeReqId = 0;
+/** Fetch a locale catalog JSON. Best-effort: returns {} on any failure. */
+async function fetchCatalog(locale) {
+    try {
+        const res = await fetch(`/src/i18n/${locale}.json`, { credentials: 'same-origin' });
+        if (!res.ok)
+            return {};
+        const data = (await res.json());
+        return data && typeof data === 'object' ? data : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Apply the resolved locale to `<html lang>` so AT/browsers report it. */
+function syncHtmlLang(locale) {
+    const el = globalThis.document?.documentElement;
+    if (el)
+        el.lang = locale;
+}
+/**
+ * Initialize i18n: resolve the locale, load the English fallback + the active
+ * catalog, set `<html lang>`, and apply `data-i18n` bindings in the document.
+ * Safe to call once at boot; subsequent calls re-apply translations.
+ */
+export async function initI18n() {
+    if (!initialized) {
+        currentLocale = resolveLocale();
+    }
+    if (!Object.keys(enCatalog).length) {
+        enCatalog = await fetchCatalog('en');
+    }
+    if (currentLocale === 'en') {
+        activeCatalog = enCatalog;
+    }
+    else {
+        activeCatalog = await fetchCatalog(currentLocale);
+    }
+    initialized = true;
+    syncHtmlLang(currentLocale);
+    applyTranslations();
+}
+/** Current active locale. */
+export function getLocale() {
+    return currentLocale;
+}
+/**
+ * Translate a key using the active locale with English fallback. Requires
+ * `initI18n()` to have completed; before that, returns the English value (or
+ * the key if English is also missing).
+ */
+export function t(key, params) {
+    return translate(activeCatalog, enCatalog, key, params);
+}
+/**
+ * Persist a new locale choice, load its catalog, update `<html lang>`, and
+ * re-apply `data-i18n` bindings across the document. Falls back to `en` for
+ * unsupported values.
+ */
+export async function setLocale(locale) {
+    const next = isSupported(locale) ? locale : DEFAULT_LOCALE;
+    const storage = safeLocalStorage();
+    if (storage) {
+        try {
+            storage.setItem(LOCALE_STORAGE_KEY, next);
+        }
+        catch { /* privacy mode */ }
+    }
+    currentLocale = next;
+    const myReqId = ++localeReqId;
+    if (!Object.keys(enCatalog).length) {
+        const en = await fetchCatalog('en');
+        // A newer setLocale superseded this one: do not assign enCatalog.
+        if (myReqId !== localeReqId)
+            return;
+        enCatalog = en;
+    }
+    const fetched = next === 'en' ? enCatalog : await fetchCatalog(next);
+    // Stale request: discard the fetched catalog so it can never overwrite a
+    // newer selection (e.g. a slow German fetch finishing after en was chosen).
+    if (myReqId !== localeReqId)
+        return;
+    activeCatalog = fetched;
+    initialized = true;
+    syncHtmlLang(next);
+    applyTranslations();
+}
+/**
+ * Walk the document for `data-i18n` attributes and bind translations. Three
+ * attribute flavors are supported:
+ *   - `data-i18n="key"`           → sets `textContent`
+ *   - `data-i18n-html="key"`     → sets `innerHTML` (for strings with markup)
+ *   - `data-i18n-title="key"`    → sets the `title` attribute
+ *   - `data-i18n-placeholder="key"` → sets the `placeholder` attribute
+ *   - `data-i18n-aria="key"`      → sets the `aria-label` attribute
+ *
+ * `data-i18n-params` may carry a JSON object literal for parameterized keys.
+ */
+export function applyTranslations(root) {
+    const doc = globalThis.document;
+    if (!doc)
+        return;
+    const scope = root ?? doc;
+    bindAttr(scope, '[data-i18n]', 'data-i18n', (el, v) => { el.textContent = v; });
+    bindAttr(scope, '[data-i18n-html]', 'data-i18n-html', (el, v) => { el.innerHTML = v; });
+    bindAttr(scope, '[data-i18n-title]', 'data-i18n-title', (el, v) => { el.setAttribute('title', v); });
+    bindAttr(scope, '[data-i18n-placeholder]', 'data-i18n-placeholder', (el, v) => { el.setAttribute('placeholder', v); });
+    bindAttr(scope, '[data-i18n-aria]', 'data-i18n-aria', (el, v) => { el.setAttribute('aria-label', v); });
+}
+function bindAttr(scope, selector, attr, setter) {
+    scope.querySelectorAll(selector).forEach((el) => {
+        const key = el.getAttribute(attr);
+        if (!key)
+            return;
+        const paramsJson = el.getAttribute('data-i18n-params');
+        const params = paramsJson ? safeParseParams(paramsJson) : undefined;
+        setter(el, t(key, params));
+    });
+}
+function safeParseParams(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Map a known server error message (English, as sent on the wire) to the
+ * active locale's catalog. Unknown messages are returned unchanged so the
+ * user always sees something meaningful. This is the display-layer
+ * translation boundary for API/OIDC errors.
+ */
+export function translateError(message) {
+    const reverse = errorReverseMap();
+    const key = reverse.get(message);
+    if (key)
+        return t(key);
+    return message;
+}
+// Lazy reverse map: English error text → catalog key. Built from enCatalog
+// so it tracks the catalog without a hand-maintained second table.
+let cachedErrorReverse = null;
+function errorReverseMap() {
+    if (cachedErrorReverse)
+        return cachedErrorReverse;
+    const map = new Map();
+    for (const [key, value] of Object.entries(enCatalog)) {
+        if (key.startsWith('error.'))
+            map.set(value, key);
+    }
+    cachedErrorReverse = map;
+    return map;
+}
+/** Compile-time-complete mapping from supported locale → BCP 47 tag. */
+const LOCALE_TAGS = {
+    en: 'en-US',
+    de: 'de-DE',
+    es: 'es-ES',
+    zh: 'zh-CN',
+};
+/**
+ * Format a date in the active locale (`de-DE` for de, `en-US` for en) using
+ * Intl.DateTimeFormat. Replaces hard-coded `toLocaleDateString('en-US', …)`.
+ */
+export function localeDate(date, options) {
+    const localeTag = LOCALE_TAGS[currentLocale];
+    const d = date instanceof Date ? date : new Date(date);
+    return new Intl.DateTimeFormat(localeTag, options).format(d);
+}
+//# sourceMappingURL=i18n.js.map

package/public/src/i18n.js.map

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

package/public/src/i18n.ts

@@ -0,0 +1,306 @@
+// ═══════════════════════════════════════════════════════════════
+// i18n — locale resolution, catalog lookup, DOM binding
+// ═══════════════════════════════════════════════════════════════
+//
+// Flat JSON catalogs (one file per locale) live alongside this module in
+// `public/src/i18n/{en,de}.json`. They are fetched at runtime so the browser
+// bundle stays free of new build-time dependencies and the same JSON files
+// can be audited by tests directly. The English catalog is the source of
+// truth: every key must exist in `en.json`; other locales fall back to it.
+//
+// Scope: this module covers *package-owned* SPA UI strings (auth screen, nav,
+// banners, settings incl. registration acknowledgement, consent UI). Server
+// API error strings stay English on the wire and are translated at the
+// display layer via `translateError()` (fallback: raw message).
+//
+// Legal pages (`public/*.html`) are operator-overlay templates
+// (`PM_WEB_LEGAL_DIR`); their localization is an operator concern and is NOT
+// handled here. The language selector deliberately does not promise
+// translated legal pages — see `settings.languageHint` and the German
+// disclaimer string `legal.disclaimer`.
+
+/** localStorage key persisting the user's locale choice. */
+export const LOCALE_STORAGE_KEY = 'pmLocale';
+
+/** Locales shipped by this package. The first entry is the default/fallback. */
+export const SUPPORTED_LOCALES = ['en', 'de', 'es', 'zh'] as const;
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+
+const DEFAULT_LOCALE: SupportedLocale = 'en';
+
+/**
+ * Resolve the active locale without touching the DOM, so it is unit-testable
+ * in Node. Resolution order:
+ *   1. `opts.storage[LOCALE_STORAGE_KEY]` (explicit user choice)
+ *   2. `opts.navLang` prefix match against SUPPORTED_LOCALES (e.g. `de-DE` → `de`)
+ *   3. default locale (`en`)
+ *
+ * `opts.storage` may be `null` to skip the localStorage step; `opts.navLang`
+ * may be omitted to skip navigator negotiation. When called with no
+ * arguments the real browser globals (`localStorage`, `navigator.language`)
+ * are used — but only inside this function, never at module top level, so
+ * importing this module in Node has no side effects.
+ */
+export function resolveLocale(opts?: {
+  storage?: Storage | null;
+  navLang?: string;
+}): SupportedLocale {
+  // A property that is present (even if `null`) means the caller explicitly
+  // wants that value: `null` skips the step. A property that is absent falls
+  // back to the real browser global, so the no-argument browser path still
+  // works. This keeps the function deterministic and unit-testable in Node.
+  const hasStorage = opts != null && Object.prototype.hasOwnProperty.call(opts, 'storage');
+  const storage = hasStorage ? opts!.storage : safeLocalStorage();
+  if (storage) {
+    let stored: string | null = null;
+    try { stored = storage.getItem(LOCALE_STORAGE_KEY); } catch { /* privacy mode */ }
+    if (stored && isSupported(stored)) return stored;
+  }
+  const hasNav = opts != null && Object.prototype.hasOwnProperty.call(opts, 'navLang');
+  const navLang = hasNav ? opts!.navLang : safeNavLang();
+  if (navLang) {
+    const prefix = navLang.toLowerCase().split('-')[0];
+    if (prefix && isSupported(prefix)) return prefix;
+  }
+  return DEFAULT_LOCALE;
+}
+
+function isSupported(value: string): value is SupportedLocale {
+  return (SUPPORTED_LOCALES as readonly string[]).includes(value);
+}
+
+/** localStorage access guarded so Node imports/tests never crash.
+ * Resolving the storage reference itself can throw a `SecurityError` in
+ * privacy/incognito modes that disable storage, so the lookup is wrapped too. */
+function safeLocalStorage(): Storage | null {
+  try {
+    const g = globalThis as { localStorage?: Storage };
+    return g.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** navigator.language access guarded so Node imports/tests never crash. */
+function safeNavLang(): string | undefined {
+  const n = (globalThis as { navigator?: { language?: string } }).navigator;
+  return n?.language;
+}
+
+/**
+ * Pure catalog lookup with fallback. Used by `t()` and directly by tests.
+ *
+ * @param catalog   the active locale catalog (may be partial)
+ * @param fallback  the fallback catalog (English — must contain every key)
+ * @param key       dotted string id
+ * @param params    optional `{name: value}` substitutions for `{name}` tokens
+ * @returns the translated string, or the key itself if missing from both
+ */
+export function translate(
+  catalog: Record<string, string>,
+  fallback: Record<string, string>,
+  key: string,
+  params?: Record<string, string | number>,
+): string {
+  let raw = catalog[key] ?? fallback[key] ?? key;
+  if (params) {
+    for (const [name, value] of Object.entries(params)) {
+      raw = raw.replaceAll(`{${name}}`, String(value));
+    }
+  }
+  return raw;
+}
+
+// ── Runtime state (populated by initI18n / setLocale) ───────────────
+let currentLocale: SupportedLocale = DEFAULT_LOCALE;
+let activeCatalog: Record<string, string> = {};
+let enCatalog: Record<string, string> = {};
+let initialized = false;
+
+/**
+ * Monotonic request id for setLocale. Each invocation increments this; an
+ * in-flight request records its id and, after its awaited catalog fetch,
+ * commits state only if it is still the latest. This discards stale catalogs
+ * when language changes overlap (e.g. rapid de → en) so a slower earlier
+ * fetch can never overwrite a newer selection.
+ */
+let localeReqId = 0;
+
+/** Fetch a locale catalog JSON. Best-effort: returns {} on any failure. */
+async function fetchCatalog(locale: string): Promise<Record<string, string>> {
+  try {
+    const res = await fetch(`/src/i18n/${locale}.json`, { credentials: 'same-origin' });
+    if (!res.ok) return {};
+    const data = (await res.json()) as Record<string, string>;
+    return data && typeof data === 'object' ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Apply the resolved locale to `<html lang>` so AT/browsers report it. */
+function syncHtmlLang(locale: string): void {
+  const el = (globalThis as { document?: Document }).document?.documentElement;
+  if (el) el.lang = locale;
+}
+
+/**
+ * Initialize i18n: resolve the locale, load the English fallback + the active
+ * catalog, set `<html lang>`, and apply `data-i18n` bindings in the document.
+ * Safe to call once at boot; subsequent calls re-apply translations.
+ */
+export async function initI18n(): Promise<void> {
+  if (!initialized) {
+    currentLocale = resolveLocale();
+  }
+  if (!Object.keys(enCatalog).length) {
+    enCatalog = await fetchCatalog('en');
+  }
+  if (currentLocale === 'en') {
+    activeCatalog = enCatalog;
+  } else {
+    activeCatalog = await fetchCatalog(currentLocale);
+  }
+  initialized = true;
+  syncHtmlLang(currentLocale);
+  applyTranslations();
+}
+
+/** Current active locale. */
+export function getLocale(): SupportedLocale {
+  return currentLocale;
+}
+
+/**
+ * Translate a key using the active locale with English fallback. Requires
+ * `initI18n()` to have completed; before that, returns the English value (or
+ * the key if English is also missing).
+ */
+export function t(
+  key: string,
+  params?: Record<string, string | number>,
+): string {
+  return translate(activeCatalog, enCatalog, key, params);
+}
+
+/**
+ * Persist a new locale choice, load its catalog, update `<html lang>`, and
+ * re-apply `data-i18n` bindings across the document. Falls back to `en` for
+ * unsupported values.
+ */
+export async function setLocale(locale: string): Promise<void> {
+  const next: SupportedLocale = isSupported(locale) ? locale : DEFAULT_LOCALE;
+  const storage = safeLocalStorage();
+  if (storage) { try { storage.setItem(LOCALE_STORAGE_KEY, next); } catch { /* privacy mode */ } }
+  currentLocale = next;
+  const myReqId = ++localeReqId;
+  if (!Object.keys(enCatalog).length) {
+    const en = await fetchCatalog('en');
+    // A newer setLocale superseded this one: do not assign enCatalog.
+    if (myReqId !== localeReqId) return;
+    enCatalog = en;
+  }
+  const fetched = next === 'en' ? enCatalog : await fetchCatalog(next);
+  // Stale request: discard the fetched catalog so it can never overwrite a
+  // newer selection (e.g. a slow German fetch finishing after en was chosen).
+  if (myReqId !== localeReqId) return;
+  activeCatalog = fetched;
+  initialized = true;
+  syncHtmlLang(next);
+  applyTranslations();
+}
+
+/**
+ * Walk the document for `data-i18n` attributes and bind translations. Three
+ * attribute flavors are supported:
+ *   - `data-i18n="key"`           → sets `textContent`
+ *   - `data-i18n-html="key"`     → sets `innerHTML` (for strings with markup)
+ *   - `data-i18n-title="key"`    → sets the `title` attribute
+ *   - `data-i18n-placeholder="key"` → sets the `placeholder` attribute
+ *   - `data-i18n-aria="key"`      → sets the `aria-label` attribute
+ *
+ * `data-i18n-params` may carry a JSON object literal for parameterized keys.
+ */
+export function applyTranslations(root?: ParentNode): void {
+  const doc = (globalThis as { document?: Document }).document;
+  if (!doc) return;
+  const scope = root ?? doc;
+  bindAttr(scope, '[data-i18n]', 'data-i18n', (el, v) => { el.textContent = v; });
+  bindAttr(scope, '[data-i18n-html]', 'data-i18n-html', (el, v) => { el.innerHTML = v; });
+  bindAttr(scope, '[data-i18n-title]', 'data-i18n-title', (el, v) => { el.setAttribute('title', v); });
+  bindAttr(scope, '[data-i18n-placeholder]', 'data-i18n-placeholder', (el, v) => { el.setAttribute('placeholder', v); });
+  bindAttr(scope, '[data-i18n-aria]', 'data-i18n-aria', (el, v) => { el.setAttribute('aria-label', v); });
+}
+
+function bindAttr(
+  scope: ParentNode,
+  selector: string,
+  attr: string,
+  setter: (el: Element, value: string) => void,
+): void {
+  scope.querySelectorAll<Element>(selector).forEach((el) => {
+    const key = el.getAttribute(attr);
+    if (!key) return;
+    const paramsJson = el.getAttribute('data-i18n-params');
+    const params = paramsJson ? safeParseParams(paramsJson) : undefined;
+    setter(el, t(key, params));
+  });
+}
+
+function safeParseParams(json: string): Record<string, string | number> | undefined {
+  try {
+    const parsed = JSON.parse(json) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, string | number>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Map a known server error message (English, as sent on the wire) to the
+ * active locale's catalog. Unknown messages are returned unchanged so the
+ * user always sees something meaningful. This is the display-layer
+ * translation boundary for API/OIDC errors.
+ */
+export function translateError(message: string): string {
+  const reverse = errorReverseMap();
+  const key = reverse.get(message);
+  if (key) return t(key);
+  return message;
+}
+
+// Lazy reverse map: English error text → catalog key. Built from enCatalog
+// so it tracks the catalog without a hand-maintained second table.
+let cachedErrorReverse: Map<string, string> | null = null;
+function errorReverseMap(): Map<string, string> {
+  if (cachedErrorReverse) return cachedErrorReverse;
+  const map = new Map<string, string>();
+  for (const [key, value] of Object.entries(enCatalog)) {
+    if (key.startsWith('error.')) map.set(value, key);
+  }
+  cachedErrorReverse = map;
+  return map;
+}
+
+/** Compile-time-complete mapping from supported locale → BCP 47 tag. */
+const LOCALE_TAGS: Record<SupportedLocale, string> = {
+  en: 'en-US',
+  de: 'de-DE',
+  es: 'es-ES',
+  zh: 'zh-CN',
+};
+
+/**
+ * Format a date in the active locale (`de-DE` for de, `en-US` for en) using
+ * Intl.DateTimeFormat. Replaces hard-coded `toLocaleDateString('en-US', …)`.
+ */
+export function localeDate(
+  date: Date | string | number,
+  options?: Intl.DateTimeFormatOptions,
+): string {
+  const localeTag = LOCALE_TAGS[currentLocale];
+  const d = date instanceof Date ? date : new Date(date);
+  return new Intl.DateTimeFormat(localeTag, options).format(d);
+}

package/public/src/sw.ts

@@ -37,6 +37,9 @@ const STATIC_ASSETS: readonly string[] = [
   '/src/components/toast.js',
   '/src/constants.js',
   '/src/filters.js',
+  '/src/i18n.js',
+  '/src/i18n/de.json',
+  '/src/i18n/en.json',
   '/src/state.js',
   '/src/theme.js',
   '/src/types.js',

package/public/src/views/auth.js

@@ -4,6 +4,7 @@
 import { state } from '../state.js';
 import { api } from '../api.js';
 import { bootApp } from '../app.js';
+import { t, translateError } from '../i18n.js';
 async function configureOidcLogin() {
     const button = document.getElementById('oidc-login');
     const divider = document.getElementById('oidc-divider');
@@ -14,7 +15,7 @@ async function configureOidcLogin() {
         button.hidden = !config.enabled;
         if (divider)
             divider.hidden = !config.enabled;
-        button.textContent = `Continue with ${config.label}`;
+        button.textContent = t('auth.oidc.template', { label: config.label });
     }
     catch {
         button.hidden = true;
@@ -34,13 +35,13 @@ export function switchAuthTab(tab) {
         fieldName.style.display = tab === 'register' ? '' : 'none';
     const authTitle = document.getElementById('auth-title');
     if (authTitle)
-        authTitle.textContent = tab === 'login' ? 'Welcome back' : 'Create account';
+        authTitle.textContent = tab === 'login' ? t('auth.title.login') : t('auth.title.register');
     const authSub = document.getElementById('auth-sub');
     if (authSub)
-        authSub.textContent = tab === 'login' ? 'Sign in to your account to continue' : 'Join pm-web and start managing projects';
+        authSub.textContent = tab === 'login' ? t('auth.sub.login') : t('auth.sub.register');
     const authBtnText = document.getElementById('auth-btn-text');
     if (authBtnText)
-        authBtnText.textContent = tab === 'login' ? 'Sign In' : 'Create Account';
+        authBtnText.textContent = tab === 'login' ? t('auth.button.login') : t('auth.button.register');
     const authError = document.getElementById('auth-error');
     if (authError)
         authError.style.display = 'none';
@@ -61,7 +62,7 @@ export async function submitAuth(e) {
     btn.disabled = true;
     const span = btn.querySelector('span');
     if (span)
-        span.textContent = 'Please wait…';
+        span.textContent = t('auth.loading');
     try {
         let data;
         if (state.authTab === 'login') {
@@ -74,11 +75,11 @@ export async function submitAuth(e) {
         await bootApp();
     }
     catch (err) {
-        errEl.textContent = err instanceof Error ? err.message : String(err);
+        errEl.textContent = translateError(err instanceof Error ? err.message : String(err));
         errEl.style.display = 'block';
         btn.disabled = false;
         if (span)
-            span.textContent = state.authTab === 'login' ? 'Sign In' : 'Create Account';
+            span.textContent = state.authTab === 'login' ? t('auth.button.login') : t('auth.button.register');
     }
 }
 export async function logout() {