@livestorm/ui-vue 2.0.2 → 2.0.4

package/src/utils/i18n.ts

@@ -0,0 +1,113 @@
+import i18next from 'i18next'
+import { getCurrentInstance, inject } from 'vue'
+import type { InjectionKey } from 'vue'
+
+/**
+ * Built-in translations for the few strings components render themselves
+ * (aria-labels, tooltips). Keyed like the Livestorm app locales so a host
+ * app running i18next with these keys keeps full control.
+ */
+const FALLBACK_BUNDLES: Record<string, Record<string, string>> = {
+  en: {
+    general_close: 'Close',
+    general_dialog_title: 'Dialog',
+    'general_misc_copied-text': 'Copied!',
+    'room_bottom-bar_controls-label_more': 'More',
+  },
+  fr: {
+    general_close: 'Fermer',
+    general_dialog_title: 'Dialog',
+    'general_misc_copied-text': 'Copié !',
+    'room_bottom-bar_controls-label_more': 'Plus',
+  },
+}
+
+/**
+ * Keys of the built-in labels. They MUST stay identical to the Livestorm
+ * app locale keys (Phrase): inside the app, translate() resolves through
+ * the app's i18next with these exact keys, and a silent mismatch would
+ * downgrade users to the EN/FR fallbacks. A spec in packages/frontend
+ * locks this contract against the app locales.
+ */
+export const BUILT_IN_LABEL_KEYS: readonly string[] = Object.freeze(Object.keys(FALLBACK_BUNDLES.en))
+
+/**
+ * A host-provided translate function. Return the translated string, or the
+ * key itself / null / undefined to decline and let the built-in bundles
+ * answer.
+ */
+export type Translator = (key: string) => string | null | undefined
+
+/**
+ * App-scoped translator: `app.provide(UI_VUE_TRANSLATOR, fn)` wires the
+ * host's i18n per application instance. This is the ONLY safe wiring for
+ * SSR servers rendering per-request locales — module state is shared
+ * between concurrent requests, an app-provided translator is not.
+ */
+export const UI_VUE_TRANSLATOR: InjectionKey<Translator> = Symbol('ui-vue-translator')
+
+let customTranslator: Translator | null = null
+
+/**
+ * Plug the host app's own i18n stack (an i18next `createInstance()`,
+ * vue-i18n, anything callable) into the library's built-in labels. An
+ * explicitly wired translator wins over the ambient i18next singleton.
+ * Pass null to restore the default behavior.
+ *
+ * This is process-level state, right for SPAs and static setups. On an SSR
+ * server with per-request locales, provide UI_VUE_TRANSLATOR on the app
+ * instead: concurrent renders would otherwise overwrite each other here.
+ */
+export function setTranslator (translator: Translator | null): void {
+  customTranslator = translator
+}
+
+function resolve (translator: Translator | null | undefined, key: string): string | null {
+  if (!translator) return null
+  const value = translator(key)
+  return typeof value === 'string' && value !== key ? value : null
+}
+
+/**
+ * Translate a key for a component's built-in label. Resolution order:
+ * 1. the translator wired via setTranslator(), when it answers;
+ * 2. the ambient i18next singleton, when initialized and it has the key
+ *    (the Livestorm app path);
+ * 3. the built-in EN/FR bundles, language picked from `<html lang>`.
+ * Apps not using i18next at all get proper strings instead of raw keys.
+ *
+ * Components call this through useTranslate(), which puts an app-provided
+ * UI_VUE_TRANSLATOR at the very top of that chain.
+ */
+export function translate (key: string): string {
+  return translateWith(null, key)
+}
+
+/**
+ * Component-side accessor: returns a translate function bound to the
+ * app-provided UI_VUE_TRANSLATOR when called inside setup(), falling back
+ * to the process-level chain otherwise. Safe to call outside a component.
+ */
+export function useTranslate (): (key: string) => string {
+  const injected = getCurrentInstance() ? inject(UI_VUE_TRANSLATOR, null) : null
+  return (key: string) => translateWith(injected, key)
+}
+
+function translateWith (appTranslator: Translator | null, key: string): string {
+  const fromApp = resolve(appTranslator, key)
+  if (fromApp !== null) return fromApp
+
+  const fromProcess = resolve(customTranslator, key)
+  if (fromProcess !== null) return fromProcess
+
+  if (i18next.isInitialized && i18next.exists(key)) {
+    return i18next.t(key)
+  }
+
+  const lang = typeof document === 'undefined'
+    ? 'en'
+    : (document.documentElement.lang || 'en').toLowerCase().split('-')[0]
+  const bundle = FALLBACK_BUNDLES[lang] || FALLBACK_BUNDLES.en
+
+  return bundle[key] ?? FALLBACK_BUNDLES.en[key] ?? key
+}